Hacker News Reader

Comment by mooreds | Hacker News Reader

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.

View on HN

Ironically, perhaps, considering its popularity among technical writers, Vale's documentation is ambiguous in places and difficult to navigate.

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

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!

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.

Acronyms and abbreviations are different things though.

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"

“ID” can mean “identity document”, such as a passport.

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.”

Is “yoo-id” a common way of pronouncing UUID? I’ve only every spoken each letter in turn.

I've only ever heard U-U-I-D, but I've also heard GUID pronounced as a single syllable like Gwid.

Reply on news.ycombinator.com