Vale.sh – A Linter for Prose
vale.sh
vale.sh
A few notes while getting it set up for macOS:
1. brew install vale
2. Create .vale.ini (in root dir, I think)
3. A minimal setup that lets you lint with Microsoft and Google style guides:
MinAlertLevel = suggestion
StylesPath = styles
Packages = Google, Microsoft
[*]
BasedOnStyles = Vale, Google, Microsoft
4. Run `vale sync` to install the Google and Microsoft style guide extensions.
5. Run 'vale {file}.md` to run the linter.* 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.
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"
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.
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
I currently use crate-ci/typos in my CI runs (it's great, humans often miss dumb typos), vale looks like typos but supercharged (but limited to markdown files?).
So like Grammarly, but you bring your own rules.
There's already the Vale programming language (https://vale.dev/), but moreover, I don't get the meaning of "vale". You could call it something like "Englint" which actually hints its purpose.
- nlprule: https://github.com/bminixhofer/nlprule
- prosemd: https://github.com/kitten/prosemd-lsp
- cargo spellcheck: https://github.com/drahnr/cargo-spellcheck
- typosaur: https://typosaur.com
A free, local, grammar checker that I can integrate into my existing editor? Pretty cool!
Update: Oh, cool! After installing the third party language server they recommend that wraps Vale, I have decent realtime grammar checking in my editor of choice.
I have used it previously, it's nice for documentation especially when engineers needs to write it but can be very daunting to setup and depressing when you receive hundreds of automated comments in a single PR.
Vale seems to do this out of the box, which is great, but the suggestion I get, while better than nothing, are still very rudimentary compared to Grammarly[1] (which I haven't used for at least a year at this point).
For example, I've enabled all styles. The alex and write-good ones gave actionable suggestions. Readability however had suggestions of the form "Try to keep the Automated Readability Index (8.83) below 8.", "Try to keep the SMOG grade (11.35) below 10.", "Try to keep the Coleman–Liau Index grade (9.57) below 9". If I knew what that was maybe I could improve my score. Is there another FLOSS tool that can turn those in actionable steps?
[1] And LanguageTool, even if sometimes advertised by FLOSS folk as a Grammarly alternative, it really isn't. Every time I try it, I feel disappointed. Has anyone tried their premium option to see if it's better?
Vale.sh: open-source linter for prose - https://news.ycombinator.com/item?id=31782688 - June 2022 (3 comments)
Vale: A syntax-aware linter for prose - https://news.ycombinator.com/item?id=30479010 - Feb 2022 (1 comment)
The rules seem like they would be incredibly brittle and not necessarily able to deal with countless variations that are seem in English.
What is this?
There should definitely be an accessibility text on these
By the way, I can't be the only one using ChatGPT to rewrite docs and messages, right? I regularly tell ChatGPT: "Rewrite the following, don't make it too formal:.." or "rewrite the following optimizing for brevity:..." and it usually spits something out much clearer than my first revision. Sometimes there's just one sentence I was struggling to write clearly and this helps a ton. Really valuable in this remote work world we live in where so much of our communication happens in writing.
Playing with ChatGPT certainly felt like more fun at first. It feels like you’re making more progress until you look at the clock and realize you’ve spent 10 minutes messing around in ChatGPT where another 60 seconds of rewriting would have worked fine.
Personally interested where the confusion is- maybe unfamiliarity with "linting" or "prose"?
It would also be nice to see examples of what it can do. Again, if it's hard Coded grammar it would be nice to see the complexity it can handle, if llm, the lengths the token limits can manage
Instead of the long list of integrations, more exposition and context would be helpful, or at least an immediate link to an introduction page providing that. In earlier times, software documentation would provide a whole introductory book chapter providing the context, use cases, and some examples.
As a side note, regarding the screenshot, I’m wondering whether the tool also provides a rationale for each item, as the displayed text isn’t very informational on the why.
1. "Your style, our editor" Wait is this an editor or a command line tool? I was able to figure it out but the word "editor" is ambiguous here.
2. "that brings your editorial style guide to life." Ok, so do I have to write all my own rules? Or is it like eslint where I choose a base config with ability to override, and possibly add more? These questions are so fundamental I would like to see succint answers at least hinted at in another tag line or short paragraph, even if I can figure them out by digging into the docs.
There is no clear explanation of what it actually is, just a vague sentence saying "brings your editorial style guide to life" which can mean a lot of things. And the screenshot is a wall of text in the smallest font size across the entire page (even smaller than the labels of the logos that make up 50% of the area), so if it was intended as carrier of important information it wasn't the right choice.
The HN post title says more in four words than the entire landing page.
I think it's probably because the purpose of computer languages is different from human language. It's certainly valuable to have a linter to make sure the code works, and there's probably value in "style" as well for readability.
But when you get to human language, I don't know, feels like you have the potential to suck out soul/creativity etc. As in, I imagine you throw a great poem or something in here and of course it will tear it apart.
I strive to write with a very neutral tone, and without any strong words, so it really helps me.
You can see the results of that process at https://blog.bayindirh.io
Curious, why? I would think this would make your writing more "boring", which would make it less likely for people to pay attention to.
As a fellow iA Writer enthusiast – it makes your writing less boring because it nudges you to get rid of filler.
for example: “Usually you can just remove some words that iA Writer suggests are filler and your sentence improves so much” —> “You can remove words that iA Writer suggests are filler and your sentence improves”
Now, on to your question.
I don't believe words have to be strong or provocative or divisive to be true. Life is not black and white, neither my choice of words. Also, I practice zen in my daily life, so my writing is both a reflection of my inner state and the state I aspire to be in, at the same time.
Yes, as a human being, I want my blog to be read, and get some feedback occasionally, but at the end, it's a blog for myself. An instrument for taking note of my life and my journey on this pale blue dot.
As for feedback, since you asked, I'll be honest and say that it does read pretty boring... Very monotone with too many idioms. Feels like what you read from schoolchildren writing about a topic they're not really interested in.
I'll also say, there's no _you_ in this writing. Reviewing the latest entry, "Practice and Experience" - no stories, metaphors, or even examples of real events to impress your point. People understand a lot through storytelling, often the only takeaway we will have will be a story or metaphor. More importantly though, they are an opportunity to identify with the reader and share something about you and your life.
Apologies if that felt harsh.
> I'll also say, there's no _you_ in this writing.
It's intentional to remove myself from my writing, because it's not about me. I'm not trying to put myself out there, and say "look at me". These are distilled mind notes. A way of sharing what I learnt about life, without me.
The writings I publish are intended to make readers to reflect themselves upon and see themselves, or get some personal insight about themselves or life. Maybe they also fascinated by this, or they never observed that angle about the life. If they think 5 seconds about the subject itself, that's nice. If they say it's boring, that's fine.
On the other hand, what I'm sharing there is highly personal. It's just devoid of bells, whistles and blinkenlights. Much like a Dieter Rams or Bauhaus design, in a sense.
> Feels like what you read from schoolchildren writing about a topic they're not really interested in.
That's an interesting take. It's true that I'm not aiming for a literary tour de force there, but it's not true that I'm not interested in the subject, it's actually the contrary. The language is simplified to that point to make it straightforward and direct.
Making indirect statements, and slowly approaching points while not quite touching them is very easily accomplished by constructing freight-train long sentences by chaining seldomly used vocabulary end to end with small punctuation marks, as if they were small fragile cotton strings knotted meticulously, and with care, if one decides to write in that way.
However, writing with no fillers have a feel of density and directness, which makes things appear with no fanfare. It's up to the reader to process this "thing" they just encountered.
> no stories, metaphors, or even examples of real events to impress your point.
"Practice and Experience" is a distillation of at least two decades of observation and self-reflection. If I decided to add the stories and examples paved the way to the realizations made in that piece, it'd be a novella. Not that I remember every detail of it, either.
That blog lives true to its tag line "tail -f /dev/brain0". When I understand something, I draft an entry. It sits and simmers for some time, refined occasionally, and when it reaches a density and purity I like, I publish.
However, thanks again for your honest feedback. I'll be saving this.
For docs, technical writing, and other formal content where you have multiple authors and consistency matters, Vale can be a fantastic tool to remind users of situations where rules help maintain standards without needing to dedicate time to editing. It can also be terrible, if it's used to force awkwardness to satisfy rules arbitrarily, especially in something like CI (which is where I see Vale abused most often - never block a docs contribution on a prose style rule violation that has no functional effect on the content, just iterate on the language).
[1] https://en.wikipedia.org/wiki/Controlled_natural_language
Edit: Ok, now I see, it is like an offline version of Grammarly for the editor of your choosing, as well as a lint tool for CI for your docs, like docs.konghq.com.