[HN Gopher] Writing like a pro with Vale and Neovim ___________________________________________________________________ Writing like a pro with Vale and Neovim Author : feross Score : 155 points Date : 2022-06-17 16:01 UTC (6 hours ago) (HTM) web link (bhupesh.me) (TXT) w3m dump (bhupesh.me) | remoquete wrote: | As a technical writer, I use Vale every day. It helps protect | consistency and style. I wrote a brief tutorial here: | https://passo.uno/posts/first-steps-with-the-vale-prose-lint... | lifeisstillgood wrote: | Thank you for this - an example of the config made it all so | much clearer - I would recommended the author steal some of | that post for their README | | 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 | mjrbrennan wrote: | What a coincidence, I watched Casino just last night! | remoquete wrote: | Feel free to reach out to me if you need some ideas. I | brought it to work successfully and I'm now trying to get the | rules to go open source. | lifeisstillgood wrote: | Thank you - I could not find your details in your profile - | my email is in my profile so please feel free to ping me | :-) | malikNF wrote: | It's in their about page. https://passo.uno/about/ | mooreds wrote: | I took a whack at using Vale a year or so ago, but was | overwhelmed by having to either: | | * 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.) | user3939382 wrote: | It feels weird to me to read/write prose in monospaced fonts. | Semiapies wrote: | I'm comfortable writing prose in monospaced fonts, but I tend | to switch out for reading and revising. In Emacs, I just hit | variable-pitch-mode. | 1970-01-01 wrote: | >Installing vale | | >Download a latest version of vale from their github releases | page. | | Looks like Vale took a break in this section. | mempko wrote: | This is really cool. Never heard of vale until today. Is there a | vim plugin that can take advantage of it? I don't use neovim and | never plan to. | aidenn0 wrote: | vim-ale[1] combines a LSP client with the ability to shell out | to linters and supports vale | | 1: https://github.com/dense- | analysis/ale/blob/master/supported-... | tombert wrote: | Out of curiosity, and this isn't meant to be passive aggressive | or anything, but why the resistance to NeoVim? | teruakohatu wrote: | I have an old vim config that I haven't had motivation to | switch over to Neovim. | | 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. | halostatue wrote: | There's no good replacement for gvim / MacVim. | | 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. | joemi wrote: | I'm not the person you asked, but in my case it's mostly a | "if it's not broke, don't fix it" situation. I don't need | neovim since vim is just fine for me. There are a few neovim- | only plugins I wouldn't mind trying out sometime, but I don't | need them, and I use very few plugins so they probably | wouldn't make the cut for me anyway. And there aren't any | neovim-only features I care about (besides mild interest in a | few plugins). | | 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. | alpaca128 wrote: | A quick search got me `vim-compiler-vale`, which seems to do | exactly that. | groby_b wrote: | Pretty much every recommendation in the example screenshot is | nonsense. | | 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. | andrewflnr wrote: | IMO one of the best ways to improve your writing is just to | read a metric crapload of good writing so it seeps in to you. | tombert wrote: | Another thing is to not be afraid _rewriting_. Usually when I | write an essay /paper, I take a short break after the first | draft, and then go through, re-read it, and make major | changes to the wording/structure in the process. Generally, | the first revision is substantially better than the draft, | and the second revision is substantially better than the | first revision. | | There's no law saying that you have to get all of your | phrasing and flow perfect the first time around. | runevault wrote: | Huh never seen this before or managed to forget it exists. Also | looks like it does have a VSCode plugin for those of us who don't | wanna fight with Vim. Tempted to try it with the write-good | linter and see what it says about some of my novel prose. | ComputerGuru wrote: | The answer to writing better isn't a "static code | completion/linting tool, but for English." | | Leave it to the tech industry to really exemplify the "when all | you have is a hammer..." mentality. | d0mine wrote: | Any activity has boring aspects. Using the tool to automate | such things should be encouraged. | | Obviously, linters can produce many false positives--they | shouldn't be used blindly. | ComputerGuru wrote: | I can see where you're coming from but I don't believe | something like Vale will - in practice, not in theory - | actually do that. You would need a general purpose AI to pull | that off, otherwise domain-specific, bespoke, one-off tools | (eg to transform an API into a documentation template, to | make skeleton release notes out of git/GitHub/Jira/whatever | records, etc) combined with a two-hour crash course on | effective writing are probably the way to go. | | 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. | vorpalhex wrote: | Sometimes tools that seem to help us make us more reckless. | | I wonder if tools like grammarly have this problem.. | rojobuffalo wrote: | boredom is useful to a writer. a lot of my favorite writers | have mentioned writing all first drafts with pen and paper. | what happens in your brain when you're writing is important, | even when it feels boring, slow, or repetitive. who has a | better sense of where my attention should be, me or a tool? | imo better writing is the product of practice, reading, and | better thinking. all of that to say, if you have a pre- | publishing step where you need to check spelling, grammar, | capitalization, punctuation, etc. a linter might fit in at | that step. but i really don't think a tool is better than | your own reading or giving it to an editor you trust. | Jolter wrote: | Nice post contents, but is your shift key broken or | something? | hsbauauvhabzb wrote: | You don't use any kind of spellcheck / grammar checks on | documents? | ComputerGuru wrote: | That's hardly the raison d'etre of Vale and co, and that's | arguably replacing (quite poorly!) the job of an _editor_ not | the _writer_. | stingraycharles wrote: | Most people that write content, even more so the target | audience of this post, don't have a editor (other than the | software editor). | vorpalhex wrote: | Please use editors. | | I typically get two different people to edit my blog | posts... | toma_caliente wrote: | As someone considering starting a casual blog, I would | not use an editor and defintiely not editors. Seems like | a weird gate to keep. | vorpalhex wrote: | One misspelling, mixed metaphor, missing contraction. | | 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. | cestith wrote: | I see a typo. | | 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. | corrral wrote: | Editors are expensive and publishers don't really provide | that service to authors, anymore. You're expected to have | that all taken care of before you submit, even to | publications that _barely_ pay (or even some that don 't | pay at all). | leephillips wrote: | I make most of my income from writing. My experience is | the opposite of this. | | https://lee-phillips.org/whypay/ | vorpalhex wrote: | As a heads up, this is not loading for me. Your other | pages seem fine, and I'm not getting a 404, just an empty | page. Doesn't seem to be adblock or pihole. | leephillips wrote: | Thanks for the heads up. It's fixed now. | corrral wrote: | Page is blank for me and I couldn't find a version though | your site's search. | | 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. | leephillips wrote: | Sorry about that. I don't know how it happened, but it's | fixed now. | | 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. | corrral wrote: | > Sorry about that. I don't know how it happened, but | it's fixed now. | | 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. | leephillips wrote: | Hmm. I had in mind non-fiction, as we were discussing | editing. I can't imagine a fiction writer wanting his or | her creations to be touched by an editor. But I accept | your report that such people exist. | halostatue wrote: | A lot of fiction writers don't, but desperately need such | editing. | | 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. | vorpalhex wrote: | Editors are expensive. There's also a reason most | publishers who have stopped using them have experienced a | major decline. | | Skilled labor is expensive. Editors are skilled labor. | Those who use them will benefit from that labor. | corrral wrote: | Yes, editors are _wonderful_ and ought to be paid well | (even if authors aren 't...) but authors who can't afford | editors (i.e. _all_ the ones trying to break in to | writing but who don 't have substantial financial | backing) benefit greatly from tools that help them do | their own editing more efficiently. | leephillips wrote: | I don't believe it (but am willing to consider actual | evidence, if any exists). Spellcheckers, sure. But until | we get an actual AI with general intelligence and | cultural awareness sufficient to understand the nuances | of human language, even "grammar checking" can not be | mechanized. | | 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. | vorpalhex wrote: | > 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. | | 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. | corrral wrote: | Sure, maybe, but the better automated tools get, the | higher standards will be before submissions are | considered. I bet slush-pile readers were a lot more | tolerant of the occasional tranpsosed letter before spell | check existed, for instance. Now if there's even _one_ | misspelling in a piece it looks like you 're not trying | at all, since you should have seen the red-squiggle, and | into the rejections you go. So it will become (already is | becoming) for brevity, clear wording, avoiding | repetition, et c. | | 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. :-) | alehlopeh wrote: | I don't think "writing better" is even a question, so what are | you expecting out of an answer? Whatever it is, this article | doesn't claim to have it. | | TFA is explicitly targeting technical writing. | Semiapies wrote: | And specifically certain prose issues in technical writing. | | It's like writing is a complex activity, and just _one_ of | its sub-tasks is editing prose. | capableweb wrote: | I don't think Vale aims to bring someone that already knows | English into mainstream-author territory of writing, but rather | help with basic/medium errors that everyday writers do. Or even | help people who maybe don't write that often. | stingraycharles wrote: | This seems to be an overly negative take on the article. There | are many different qualities of good writing, and this happens | to automate one of them. | triyambakam wrote: | Tab9 is an ML powered completion engine that works for code and | prose. It won't help you write better but it is very good at | suggesting word I was about to use next. | gnuvince wrote: | A post about writing means that I need to plug a couple talks by | Larry McEnerney. [1,2] | | 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 | Semiapies wrote: | Only if you consider it worthwhile to spam with links about | agile development in discussions of linters. | | Writing, like programming, is a task that involves work at | multiple levels. | user3939382 wrote: | I just learned that my IDE, PhpStorm from Jetbrains, comes | bundled with a plugin called Grazie which wraps vale. So you may | have been using this and not even realize it. | henning wrote: | > Vale requires to have a .vale.ini config file | | 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. | lijogdfljk wrote: | This is neat, any other projects similar? Notably ones that work | perhaps with more of an LSP-like API? | | 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 | guessmyname wrote: | > _This is neat, any other projects similar? Notably ones that | work perhaps with more of an LSP-like API?_ | | https://valentjn.github.io/ltex/ | jcoder wrote: | This seems interesting, but given that the recommendations in the | very first screenshot are >50% "wrong" ("HOW" is not an acronym, | "tap" makes no sense in this context), I can only imagine that | using this tool would be a huge distraction while writing. | leephillips wrote: | In fact, _all_ the recommendations in the screenshot are wrong | or useless. This is the example they chose to showcase the | awesomeness of this software? Amazing. | skrebbel wrote: | It has been demonstrated that you're entirely out of tap if | you can't imagine Home Office Weekly this could be useful. | nmilo wrote: | Avoid second-person pronouns such as "you're". | ryanklee wrote: | Yeah, this is not good at all. | | 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. | [deleted] | aidenn0 wrote: | They have rules loaded that are primarily for writing technical | documentation. (I assume the tap/touch is from the Google | rules). Most technical documentaition style guides will | recommend avoiding first person, but that makes zero sense for | e.g. a blog post. Assuming ALL CAPS words are likely to be | acronyms is also reasonable in such a context. | | 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. | leephillips wrote: | "Most technical [documentation] style guides will recommend | avoiding first person" | | Not even true. They recommend against first person singular. | cbsks wrote: | Google recommends avoiding first person: | https://developers.google.com/style/person | nathias wrote: | I had a linter for text, it kept coloring 'black' as offensive so | I uninstalled it. | adamgordonbell wrote: | They don't mention that you can write the rules yourself and also | pick and choose from existing rules from GitHub. | | 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... | | [3]: https://github.com/errata-ai/vale/issues/356 | blameitonme wrote: | Openly, last commit: 13 months ago :( | hsbauauvhabzb wrote: | I've always been hesitant to use a service which ships thing's | I write back to home base. Instead I used Microsoft word, which | turns out does similar. | kgarten wrote: | It seems openly is just a folder with rules on your hard | drive. Vale is also offline ... don't really understand your | comment. | | 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 ... | hsbauauvhabzb wrote: | Sorry see my post direct in parent. My statement was poorly | worded. | hsbauauvhabzb wrote: | It's too late to edit my original post but this wasn't meant | as an accusation of vale, it was actually intended as praise | for vale the tool given most others are basically keyloggers. | | Very poorly worded on my part. | dijit wrote: | Scathing accusation. Is there a citation? | | I won't use another office product from them if so. | | Seriously. | AlanYx wrote: | You can see Grammarly's statement on the matter here: | https://support.grammarly.com/hc/en- | us/articles/360003816032... | | 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. | bachmeier wrote: | > 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. | andrewflnr wrote: | Ah, so not related to Vale the programming language, | https://vale.dev/, which IMO is much more interesting. | LionTamer wrote: | Just discovered the Vale programming language for the first | time thanks to your link - looks pretty interesting. I've been | meaning to learn a new language that is (a) simple (or if not | simple, at least elegant enough to make the lack of simplicity | worthwhile) (b) type-safe & performant. I was between Nim & Zig | but might need to give Vale a shot. | nagisa wrote: | I tried running vale with the good-writing plugin on one of my | blog posts. I won't claim I produce great literary works, but a | fair bit of warnings it output were false positives. Even | conjugates such as "write-only" would trigger its weasel word | trigger for "only". | | 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. | lyjackal wrote: | regex based prose linting seems rife with opportunities to | write buggy regexes ___________________________________________________________________ (page generated 2022-06-17 23:00 UTC)