17 ms·
Vale.sh – A Linter for Prose
- nmstoker 3y agoDoes this actually work well in practice? The rules seem like they would be incredibly brittle and not necessarily able to deal with countless variations that are seem in English.
- kstrauser 3y agoBut what is it? Is this like Grammarly? Maybe LanguageTool? I paged through most of the docs and I’m still not entirely sure what this does or why I might want to use it.
- NeutralForest 3y agoYeah not clear at all tbh
- awoimbee 3y agoLooks like grammarly but open source, with custom rules and easy to add to CI. 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?).
- tester457 3y agoIt needs a better landing page
- Modified3019 3y agoDefinitely. Though they apparently weren't very happy with someone bringing it up: https://github.com/errata-ai/vale.sh/issues/46 https://github.com/errata-ai/vale.sh/issues/46
- kstrauser 3y agoThe wording of that issue could come across as overly aggressive. The submitter should test it with a linter.
- deleted 3y ago[deleted]
- jamilton 3y agoWhat's unclear about it? My impression from the window screenshot alone is you choose rule docs and a text doc, and it tells you what parts of the text doc violate parts of the rule docs . It could be used to help make sure writing (likely for some corporate or technical purpose) follows a set style guide. Organizations already often follow formal style guides in their writing, I don't know if they have their own similar tools to automatically check if their style is being adhered to. So like Grammarly, but you bring your own rules.
- XCSme 3y agoMy understanding is that it is like LanguageTool, but where you can define your own rules using some YAML file (?).
- hackerfake 3y agoI don't get what exactly this is and couldn't find an explanation
- notamy 3y agoSince there’s a few confused comments, and I was(/am?) confused too, I think this is pretty literally what the title says. I think a good metaphor would be "eslint but for written text instead of code."
- kstrauser 3y ago"Linter" is broad. Turns out it has the feature I most hoped for, language server protocol support, but it wasn't mentioned until far down into the integration docs. 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.
- h1fra 3y agoFor those wondering it's a tool like eslint or prettier (or any code formatter) but for actual text. It checks the formatting, the style, the words themselves and the formulation. 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.
- mushufasa 3y agoI love writing my own thoughts and essays in Vim, and often have the problem that when I export the text to a proper word processor to send to someone, the spelling and grammar is messed up. This is despite running the built-in vim spellcheck. So I'm interested to see if this will help, and I'm excited to try it out!
- jasonjmcghee 3y agoAs there's a theme in comments here - I'm surprised people are so confused by the landing page. Between "a linter for prose" and the screenshot at the top of the page, I found it quite clear what the use case and point of the tool was. Personally interested where the confusion is- maybe unfamiliarity with "linting" or "prose"?
- hhh 3y agoI found it clear when I looked at the site, but never thought about prose being used in this way. I didn't know the actual definition though, and after googling it's clear.
- dmarchand90 3y agoI think it's the lack of examples. Also, because this is very cutting edge, I'd like to know a bit of the technology behind it to know the strengths and limits. E.g. is it based on hard Coded grammar and thus a bit stiff and dumb? Or is it llm based and therefore with data control issues? 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
- playingalong 3y agoThe name linter is not widespread in its use as some think. In some ecosystems it's just called "static analysis tools" or something. I came to learn the tool "linter" after having exposure to a few tools of this kind, several years into the programming career.
- layer8 3y agoIt’s the lack of examples (I actually browsed the site for 2–3 minutes for some and didn’t find any), and that the screenshot doesn’t show the input prose text that the output applies to. 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.
- zerojames 3y agoI saw Vale earlier today. The tool helps you comply with technical style guides like those by Microsoft and Google, and the out-of-the-box Vale rules (the extent of the Vale rules I am unsure; I got way more suggestions when installing the Microsoft and Google extensions). 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.
- hddqsb 3y agoThe built-in rules only include spelling according to the docs: https://vale.sh/docs/topics/styles/#built-in-style https://vale.sh/docs/topics/styles/#built-in-style
- j7ake 3y agoThis is one step closer for me to type more prose in vim!
- LucasOe 3y agoI always struggle with keeping my writing clear and concise, maybe because English isn't my native tongue, so this looks like an incredibly helpful tool to me. Does Vale.sh have the ability to check the prose used in comments? Using this for doc comments would be useful for writing better documentation. The example only shows it being used for markdown files.
- mhitza 3y agoVery interesting! Just the other day I've tried proselint for the first time, and became annoyed that I'd have to hack something together to only have it lint over the text in my markdown file. It doesn't ignore code blocks, as it just supports text, as is not aware of any file format. 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?
- skydhash 3y agoI have the premium option and it’s nice. I use it primarily as a spellchecking tool. And it sometimes detect when I use the wrong style (English is my third language).
- Kiro 3y ago> (, , and ) What is this?
- lgas 3y agoAre you using a text only browser? They are ([apple icon], [windows icon], and [linux icon]).
- pjot 3y agoMy favorite is a tool called write-good https://github.com/btford/write-good https://github.com/btford/write-good
- xwowsersx 3y agoJust curious, how exactly you're using this? You'll write stuff in a file and run `write-good stuff-i-wrote.md` and then look through the suggestions and modify as needed?
- pjot 3y agoYep!
- cratermoon 3y agoThere's a 'write good' style available for Vale: https://github.com/errata-ai/write-good/blob/master/README.md https://github.com/errata-ai/write-good/blob/master/README.m...
- antiframe 3y agoI'm curious what "native" means in write-good's description: "Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too." It appears to require a node server.
- xwowsersx 3y agoThis looks great! 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.
- tommica 3y agoYeah, it's a good use case for it. I also use it to translate messages for me in languages that I am weak in, and I really like it's ability to summarize things.
- Aurornis 3y agoI tried this with mixed results. I’d spend so much time prompting, rerunning it, proofreading, and making minor changes that I wasn’t really coming up with a more efficient workflow. Rewriting the text myself a couple times produces more concise results after. 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.
- jskherman 3y agoI got introduced to https://goblin.tools https://goblin.tools on the Fediverse and found it handy ever since for some of the usual things I ask ChatGPT. On it, there's the "Formalizer" for this use case, and "Magic To Do" to help break down tasks (and there's the option to generate time estimates too).
- xwowsersx 3y agoOh neat, thanks for sharing!
- jackthetab 3y agoNope, you're not the only one. I do the exact thing, including saying "Rewrite the following, don't make it too formal". I think the results are excellent.
- satvikpendem 3y agoI don't really understand this, what is a linter for prose? Like Grammarly? Is it an end-user product or for a programmatic interface? If the former, why are there "integrations?" What does it mean to integrate this into Kong, for example? Does it work through VSCode? 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.
- deleted 3y ago[deleted]
- playingalong 3y agoWhen is my IT department gonna approve it for use at work?
- vinckr 3y agoI wrote a blogpost how I use Vale and how you can do it too - https://vinckr.com/blog/open-source-stylecheck/ https://vinckr.com/blog/open-source-stylecheck/
- lindig 3y agoLinks are unreadable in that blog post on iOS/Safari.
- cratermoon 3y agoMore helpfully, the background for <code> tags is #302b5f, a very dark desaturated blue and the font color is #262626, very dark gray (mostly black)
- mooreds 3y agoHave 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/DocsDevREADME.md 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.
- block_dagger 3y agoIn 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!
- mgaunard 3y agoAcronyms and abbreviations are different things though.
- tomjakubowski 3y agoA 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"
- cpeterso 3y ago
- jrm4 3y agoI'm trying to figure out why I instinctively hate this. 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.
- petesergeant 3y agoThis is for when three different people on your marketing team decide to come up with “opensource”, “open source”, and “open-source” respectively when writing whitepapers.
- CharlesW 3y agoTo "yes, and" this, it gets even worse — employees often mess up their own company, technology, and people names. This seems like a useful tool for helping alert writers to potentially embarrassing and/or brand-damaging gaffes.
- bayindirh 3y agoI think iA Writer does this well. It has a "mark fillers" setting which crosses out cliches, fillers and other things which dilute the sentences. It's just a finger pointing at "you might want to reconsider this", and if it's indeed something I don't want there, I take it out, otherwise leave it in. 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 https://blog.bayindirh.io
- ggoo 3y ago> I strive to write with a very neutral tone, and without any strong words, so it really helps me. Curious, why? I would think this would make your writing more "boring", which would make it less likely for people to pay attention to.
- deleted 3y ago[deleted]
- ushakov 3y agoOther interesting projects in the space: - nlprule: https://github.com/bminixhofer/nlprule https://github.com/bminixhofer/nlprule - prosemd: https://github.com/kitten/prosemd-lsp https://github.com/kitten/prosemd-lsp - cargo spellcheck: https://github.com/drahnr/cargo-spellcheck https://github.com/drahnr/cargo-spellcheck - typosaur: https://typosaur.com https://typosaur.com
- andatki 3y agoI’ve been editing my Markdown files with it and wrote about it here: https://andyatkinson.com/blog/2023/05/26/better-writing-vale https://andyatkinson.com/blog/2023/05/26/better-writing-vale
- dang 3y agoRelated. Others? Vale.sh: open-source linter for prose - https://news.ycombinator.com/item?id=31782688 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 https://news.ycombinator.com/item?id=30479010 - Feb 2022 (1 comment)
- armchairhacker 3y agoThis seems like a tool I'll be using, and this is an almost meaningless criticism, but why the name? There's already the Vale programming language (https://vale.dev/ 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.
- microflash 3y agoI've been using Vale for several years now to steer my writing style. It is easy to customize and simple to work with. The only issue that I faced is that many available styles have too corporatey rules, which is why I'm maintaining my own style for personal writing.
- darkhorse13 3y agoVale is awesome. I used it to proof-read my documentation for Halfmoon: https://www.gethalfmoon.com/docs/ https://www.gethalfmoon.com/docs/