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

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.




Consider applying for YC's Winter 2026 batch! Applications are open till Nov 10

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

Search: