1 minute read

Writing good documentation is such an underrated skill, to that extent so is writing ReadME files, ReadME files can be an awesome addition to your project. They give you an opportunity to document all sorts of stuff. For me, a good project should come along with a good ReadME file. The file should outline everything that is necessary for me to interact with the project. Like how to run the unit/integration test, the project’s architecture, any terminology, the roadmap for the project, and the most important piece, examples on how to use the project.

Whenever I begin a new project I try to make a good effort to include a good ReadME file. I like having the project’s documentation live with the project’s code, not some external site, with this approach documentation is versioned, given that more than likely the code will be managed by some version of control system, git being the most popular these days. This starts the idea that documenation should be treated the same way we treat code.

Always write documentation as if the guy who ends up 
maintaining your code will be a violent psychopath 
who knows where you live.

That is my twist to the famous quote. To that extend, writing good documentation can sometimes come down to having good tools. In the case of ReadME files one good tool at your disposal is readme.so, this tool was created by Katherine Peterson, it helps you scaffold a ReadMe file from the ground up. Additionally, you could also explore some of the most popular projects on Github to see how they each approach creating a ReadMe file.

Tags:

Updated: