News for hackers. Stuff that matters.
Re:Vale.sh – A Linter for Prose by mooreds on Sunday September 03, 2023 @02:47PM (#37373119)
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/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.

Re:Vale.sh – A Linter for Prose by block_dagger on Sunday September 03, 2023 @03:28PM (#37373511)
In 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!
Re:Vale.sh – A Linter for Prose by mgaunard on Sunday September 03, 2023 @04:05PM (#37373937)
Acronyms and abbreviations are different things though.
Re:Vale.sh – A Linter for Prose by tomjakubowski on Sunday September 03, 2023 @04:21PM (#37374102)
A 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"

Re:Vale.sh – A Linter for Prose by cpeterso on Sunday September 03, 2023 @08:14PM (#37375933)
“ID” can mean “identity document”, such as a passport.
Re:Vale.sh – A Linter for Prose by User23 on Sunday September 03, 2023 @11:51PM (#37376966)
This 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.”
Re:Vale.sh – A Linter for Prose by uuuuuuuuuid on Monday September 04, 2023 @02:03AM (#37377588)
Is “yoo-id” a common way of pronouncing UUID? I’ve only every spoken each letter in turn.
Re:Vale.sh – A Linter for Prose by dharmab on Monday September 04, 2023 @03:17AM (#37377977)
I've only ever heard U-U-I-D, but I've also heard GUID pronounced as a single syllable like Gwid.
Re:Vale.sh – A Linter for Prose by mooreds on Monday September 04, 2023 @04:02PM (#37384397)
I 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.

Re:Vale.sh – A Linter for Prose by starkparker on Sunday September 03, 2023 @07:50PM (#37375768)
Ironically, perhaps, considering its popularity among technical writers, Vale's documentation is ambiguous in places and difficult to navigate.
Re:Vale.sh – A Linter for Prose by MilStdJunkie on Monday September 04, 2023 @12:02AM (#37377012)
It'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