4 ms·
Have tried to use this a few times but it's a big lift. Like adding unit tests to an existing application, it's a good idea to start small. And vale doesn't mak
by mooreds 3y ago
Have tried to use this a few times but it's a big lift. Like adding unit tests to an existing application, it's a good idea to start small. And vale doesn't make this super easy (at least I couldn't figure out an easy way to do this). If I could wave my wand, I'd want a way to:
* apply vale to just the doc I was working on
* have a minimal set of rules
* add to them over time
At $curjob, we have a detailed public list of rules of doc ( https://github.com/FusionAuth/fusionauth-site/blob/master/DocsDevREADME.md https://github.com/FusionAuth/fusionauth-site/blob/master/Do... ) and as our team expands, I'd love to have them be applied rigorously. vale seems like a good fit, but there's an activation energy that I haven't been able to get over yet.
I am not aware of any other cli tools similar to this, though, so totally admire the team behind it.
- block_dagger 3y agoIn the first bullet point of the linked document, there is an inconsistency in the very style it’s trying to enforce, namely capitalization. UUID vs Id. Consistency is hard!
- mgaunard 3y agoAcronyms and abbreviations are different things though.
- tomjakubowski 3y agoA not-untypical style (as used by the BBC) is to write initialisms like UUID in all caps, and acronyms like Nasa in title case. Initialisms are pronounced by saying each letter in order. Acronyms are pronounced as if they were words. "ID" is a funny case because it's an ordinary abbreviation, and not really an initialism* or acronym, but it's pronounced just like an initialism. I think I'd prefer it "ID". I would definitely avoid writing it "Id", lest it be confused with Freud's concept. * unless as Norm Macdonald joked, the "D" is short for "dentification"
- cpeterso 3y ago“ID” can mean “identity document”, such as a passport.
- User23 3y agoThis is, to my half American ears, bizarre prescriptivism. We pronounce NASA as “nasa” and UUID as “yoo-id” (and GUID as “goo-id). And ID is pronounced “eye-dee.” And of course we pronounce OK (short for “oll korrect”) as “okay.”
- uuuuuuuuuid 3y agoIs “yoo-id” a common way of pronouncing UUID? I’ve only every spoken each letter in turn.
- dharmab 3y agoI've only ever heard U-U-I-D, but I've also heard GUID pronounced as a single syllable like Gwid.
- mooreds 3y agoI don't know why we use `Id` for identifer, but that's consistent across our codebase and documentation (we may have missed a few spots, but that's an error on our part). Not sure why it is inconsistent to have UUID be all caps and Id be title cased? They feel different to me. But maybe I'm missing something.
- starkparker 3y agoIronically, perhaps, considering its popularity among technical writers, Vale's documentation is ambiguous in places and difficult to navigate.
- MilStdJunkie 3y agoIt's in keeping with traditional techpubs software being an unmitigated dumpster fire. :) Not Vale, though. Vale's pretty slick; although personally I've always gravitated to RedPen.cc and LanguageTools[1] more than Vale. Grammarly, yes, Grammarly is also in this natlang linter space, but has possibly the least responsible data safety rules of any VSC extension I've ever seen. It's harsh, but I comprehensively advise customers away from Grammarly if they have any kind of data restriction at all. [1] LT for no other reason than ASD STE-100 checking - it's old tech