Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Also helpful is the Checklist for Plain English[1]. The gist is "less is more;" fewer words are easier to understand than many words, short sections are easier to understand than long sections, and familiar words are easier to understand than something you looked up in a thesaurus.

Of course, these guides are only helpful if you already understand what you're trying to convey; that's the real secret of writing well. Figuring out the correct sequence to walk a reader from "I don't know anything about this topic" to "I understand this topic" is more art than science, and to do so well takes years of practice.

[1]: https://plainlanguage.gov/resources/checklists/checklist/



There are some utilities out there that will give your writing a education grade level (such as the Hemingway Editor: http://www.hemingwayapp.com/). In the case of technical documentation, you want to aim for the lowest grade level you can. Your technical words and descriptions of systems will necessarily push the grade level higher. Every non-technical phrase would ideally be written as simply as possible.


I've taken some technical texts I've written in the past and run them through the xkcd simplifier - it identifies words that are not in the 1000 most common English words (? something like that).

https://xkcd.com/simplewriter/

I keep the words that truly add value to the project, and replace all the others with more simple ways of saying whatever I am trying to say. Usually in the process I lose a few lines of text (occasionally I can a few bullet points instead). It's a pretty good experience to go through (for example, this post fails. A lot.)


It would be nice to have something like this with common words used in programming contexts added to it. Maybe as a VSCode plugin or something.


Couldn’t agree more with that checklist. I’ve used Hemingwayapp.com to help simplify my prose in the past, which seems to enforce similar rules. I’d imagine grammarly is similar but don’t have personal experience with it




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: