Writing like a pro with Vale and Neovim
bhupesh.me
bhupesh.me
There is an attempt to build and open source version of Grammarly using vale rules here[1]. Rules are mainly regex based, but some target readability measures[2] or use parts of speech[3].
[1]: https://github.com/testthedocs/Openly
[2]: https://github.com/testthedocs/Openly/blob/master/Openly/Rea...
I won’t use another office product from them if so.
Seriously.
When enabled, it does basically send every keystroke to the mothership except in some fields on webpages and on mobile apps marked sensitive.
However, they do have what seems like a solid privacy policy in how they handle the data they receive.
Not to be a Debbie Downer, but that provides no comfort at all. The best privacy policy is to not have access to your data.
I would not use anything closed source and bloated as Word. I wrote my BSc. thesis in it in the 2000s. Could not open it correctly anymore after 5 years. It took ages to open.
Switched to vim and latex for my master and phd thesis. Never looked back ...
Very poorly worded on my part.
To over-simplify, vale runs hundreds of pre-built regexes that suggest changes to over-used phrases, likely function names etc etc. Google etc have pre-built fairly good defaults I suspect.
(To be fair this is trying to get consistency across huge document bases, and will never replace a human's authentic voice for communication. But sometimes you just want to make sure there are the same number of blueberries in each muffin)
Ok - my mission after next - get something like this brought in at work
* creating my own style guide
* using one of the existing ones
We have a DevDocsReadme that has some style rules we enforce manually. Is the best way to get going with vale to start with that doc and write rules for that?
Can you apply rules to asciidoc and markdown source docs, or do you have to apply it to the end product (HTML, etc)?
It seems like such a cool idea. Any pointers to 'get started' for existing largeish documentation sets would be much appreciated. (I will read your tutorial, @remoquete.)
Leave it to the tech industry to really exemplify the “when all you have is a hammer…” mentality.
Obviously, linters can produce many false positives--they shouldn't be used blindly.
But obviously enough people disagree that this is a thing.. although that could be said for quite a number of “technical progress” milestones we currently celebrate.
I wonder if tools like grammarly have this problem..
I typically get two different people to edit my blog posts...
Nobody writes flawlessly. It is hard to find your own mistakes, much less understand if content will make sense to someone else.
An editor is someone who can read your work, help catch errors and suggest improvements.
No you don't need to go pay someone, but either trade editing with a friend or find another way to compensate whoever is providing editing for you. I usually buy my editors dinner but adjust based on how much time investment you are asking of them.
You do not get to choose when a writer uses a contraction. You might expect that I'd have used "don't" there, but the simple truth is people use the full words even conversationally sometimes. This is especially true when they want to emphasize the "not" part of a phrase like "will not", "would not", or "do not". Your suggested edit changes the meaning of the parent post a shade.
Where's the mixed metaphor? You may be able to sell me on "weird gate to keep" being a trite metaphor or perhaps even an awkward metaphor. What's mixed about gatekeeping, which seems to be a single common metaphor?
If this is the quality of editing the tool offers, one may wish to stick with spellcheck. Encouraging a particular organization's writing style within that organization can have some nice effects, but you don't get to determine everyone else's writing style.
Skilled labor is expensive. Editors are skilled labor. Those who use them will benefit from that labor.
Really, anyone considering working as an author who can’t produce an excellent, polished first draft without an editor should consider a line of work more attuned to his or her talents.
If tools save time or reduce the technical skill required, that seems great to me. Art's about the finished product, not how it gets there, though popular understanding of how artists work and how they actually work may differ substantially. Almost no authors can always recall the exact word they want, the precise wording of that phrase they want to quote, the rule for some particular piece of grammar, and so on—they may have a whole shelf of Brewer's and Roget's and Webster's and Garner's and Strunk & White for that, plus computerized tools, these days. Why not have tools for the other aspects of editing? Why not have a computer find a suggestion for you, before you even think to consult a source or scrutinize a passage more closely?
Plus, I guess I don't care much about any sort of purity in the writing process since practically the only accepted style, these days, in English writing at any rate, is fairly rote and prescribed and very simple. Did that sentence seem too complex? Did it have too many clauses? Does your inner editor's voice pipe up while reading it? Yep, exactly—it violates that very-modern style, even if only a bit. May as well take the next step and let a machine enforce those rules.
More generally, as a lover of books and reading and writing, I'm pessimistic about the future of the whole enterprise. I think making a living as a writer, outside the usual handful of trust fund minor-celebrity lit-fic authors, is going to involve a lot of machine assistance, to the point that "writing" will mostly be massaging and curating the output of machines. Ghostwriters beware—and/or get ready to quintuple your output, using new tools, just to keep your head above water. In the meantime, a little help from tools like this might get the last generation of small-time authors, with actual ideas of their own but without an eye for editing, to print, before that becomes all but impossible even for the very-talented.
It's a good thing there's already enough excellent fully-human-produced writing to last even fairly-avid readers several lifetimes. At least until and unless life extension really gets going.
[EDIT] I'm aware, incidentally, that some of these paragraphs disagree with one another. I stand by my contradictions. :-)
Really, anyone considering being a programmer who can't write a program without bugs on the first try without an IDE should...
Yeah that seems overly harsh and incorrect. Skills take time and practice to develop.
Your experience is that editors are cheap and that publishers readily supply substantial editing services, not requiring that practically all editing work is done before entertaining a submission? That's contrary to the experience of multiple close friends and relatives who are writers or are working on getting published, and to that of multiple others I follow whose experiences I've heard or read about.
I don’t know what you mean by editors being cheap. I don’t pay them, they’re employees of the publications I write for. I assume they’re underpaid, of course.
My first draft is better than the finished product you’ll find in most publications (not bragging, it’s just the truth). Before it’s published, however, it goes through several rounds of editing with from one to three editors, and a technical review. This can last weeks. I may have to generate five revisions before it’s good enough. It could be that your acquaintances are writing for publications with lower standards.
EDIT: By the way, if you have friends who are submitting to publications that don’t pay, or pay only a token amount, please suggest to them that they stop. This depresses the market for writers who are tying to make a living with it. Don’t fall for the “exposure” gambit or give away your stuff to feed your ego. You‘re being robbed.
No problem, shit happens.
> My first draft is better than the finished product you’ll find in most publications (not bragging, it’s just the truth). Before it’s published, however, it goes through several rounds of editing with from one to three editors, and a technical review. This can last weeks. I may have to generate five revisions before it’s good enough. It could be that your acquaintances are writing for publications with lower standards.
Premier genre periodicals, as no other short fiction venues pay worth a damn, these days. Novels through trad publishing—the ones I know who self-publish barely edit at all and certainly don't pay for editors, which is, judging from the quality of the median self-published work, evidently the norm in that world. Household-name monthlies, with non-fiction writing, in those cases, though some of those publications do also print fiction.
The ones I know who publish longer-form non-fiction writing do seem to get somewhat more support from their publishers, to be fair, but most of the editing work does still need to be done before submission or you're getting round-filed. Those also tend to be more well-defined and goal-oriented pieces, so content editing is less necessary or extensive.
What most will do, at least, is tell you what to cut if they need the piece to be shorter.
[EDIT]
> EDIT: By the way, if you have friends who are submitting to publications that don’t pay, or pay only a token amount, please suggest to them that they stop. This depresses the market for writers who are tying to make a living with it. Don’t fall for the “exposure” gambit or give away your stuff to feed your ego. You‘re being robbed.
Oh don't worry, they're all pretty allergic to that. Good warning though, and worth mentioning. The lit-fic market especially is a complete joke in this regard. But I suppose it's hard to blame publishers when they have such a glut of people willing to put words to paper for little or no compensation.
I’ve read plenty of books that could have told the story in 20% fewer pages, or had a swapped character name, or…
Some of these passed through multiple layers of editing. Some of these "passed" through those layers because the writer got too famous or cantankerous or…
I acted as one of my wife’s editors for her books, and some of the things that I checked (as it was recent historical fiction) included whether the weather she described for a chapter matched the weather reported by Environment Canada. She had one scene in early April of a year where she said that the "last of the snows had gone…", but there was a snowstorm on the 3rd of April or something like that. As the weather was not critical to the scene, I insisted that it either be dropped or changed (she changed it) — because getting that sort of item wrong can throw a reader out of the flow of the book.
In another instance in her second book, she had a weather condition that was crucial to the plot. We looked to see that it would be plausible (e.g., it was not 50℃ in February in Toronto in 1979), then let the weather condition stand because it mattered.
TFA is explicitly targeting technical writing.
It's like writing is a complex activity, and just one of its sub-tasks is editing prose.
They aren't, typically, talking about the kind of stuff that you work on in a creative writing elective you take one semester. The very same class, in fact, that gave you this presumptuousness.
What details? Things like "do you use 's for possessives even for a word/name ending in s, or is it s'?" or "oxford comma or no?". Writers argue over these just like programmers argue over tabs v spaces or the place of braces. Sure, if you're just blogging for personal use, go crazy, don't worry about a consistent style, do what you want. When writing for publication, instead of arguing over whether or not it's ok to use certain slang or contractions, the editors just chose a preferred way.
Tools like Vale streamline the process of aligning to a style, just like coding style checkers and autoformatters relieve programmers of the tedium fixing up all the indentation manually.
Ultimately, it is the technical limitations that make the tool unusable for me. On one hand, a Github-flavoured markdown parser is used. It filters out some obscure HTML tags such as `mathp`, and I couldn’t find a way to configure the tool so it would ignore the math segments. I even tried to forgo vale’s built-in markdown converter, and run the check on the output of the static site generator instead, but that plan was quickly foiled by the soft hyphens my generator inserts. Given such an input vale considers every syllable a separate word.
I strongly suggest learning to write better instead of relying on this. There are writing classes. There are teachers. There are editors. And if all of that is too expensive for you, ask friends and colleagues for feedback.
Relying on algorithms to improve your style is at best a no-op, and at worst actively harmful to good writing.
There's no law saying that you have to get all of your phrasing and flow perfect the first time around.
The tool described in this blog post is all about text-based rules: what the _text_ ought to look like. To improve your own writing (a) learn who your readers are, (b) know what they value, and (c) write so that as readers, they find your work valuable to them.
[1] https://youtu.be/vtIzMaLkCaM [2] https://youtu.be/aFwVf5a3pZM
Writing, like programming, is a task that involves work at multiple levels.
Not sure if it makes sense as an LSP, but if it was i could hook it into my editor of choice (Helix, at the time of writing) easily
Even something arguably well-executed and compatible with "established" style heuristics, like Grammarly, will always be dubious, as they perpetuate the myth of linguistic prescriptivism weaponized by language pedants. All of whom are annoyingly, vocally, interminably incorrect.
But this, this is just baldly idiotic.
Vale also has multiple severity levels, so disabling e.g. the "suggestion" (and maybe even "warning") level while writing live would make a lot of sense.
Not even true. They recommend against first person singular.
Not exactly selling the value of vale when I see "let's" used like this.
1: https://github.com/dense-analysis/ale/blob/master/supported-...
That's what most of my personal "resistance" is about. The rest is due to fact that I'm still a little bitter from some bad interactions with some early neovim developers and fans.
I find configuration frameworks, which are so popular right now, a lot of work to understand and not very flexible/opinionated.
Lastly, vim is usually available everywhere, so I am just a git clone away from having my configuration deployed.
I’ve tried all the GUIs that compile for the Mac. I can’t stand a single one of them.
I can’t stand using vim / nvim on the terminal for most of my editing. Not sure why, but that’s my reasoning.
>Download a latest version of vale from their github releases page.
Looks like Vale took a break in this section.
Having to provide a configuration file for every little fucking thing and completely refusing to have any set of reasonable defaults when you install a package is the worst part of Neovim.