Things I've learned about writing good READMEs

Things I've learned about writing good READMEs

The intent is clear: "This is important information for the user to read before proceeding." Let's explore together what constitutes "important information" in this modern age.

How to craft a well designed README.

The README is probably the most ubiquitous note in modern software development. The very name signals a call to action and gives people a path to go down when seeing a new project for the first time.

The article goes over a light history of READMEs and then some best practices for writing them. Some highlights include brevity (keep it short), cognitive funnelling (go from broad to specific), and have examples.

I think of READMEs as the most widely applied usage of the Amoeba pattern - the documentation for most projects start off as a single README note and gradually expand outwards as needed depending on how the project grows.

Its fun to think about how READMEs might look when moved up several level, say for an entire field. What is the README of science? What is the README of your life?


Backlinks