README - Gateway to Your Code¶
Main point
Write a README, because no one can read your mind (at least not yet 😀).
The Why¶
Is it your favorite book? ;)
- Documentation forces you to prove that you understand how the application works and that you can explain it to the World. Your docs become your ultimate rubber duck!
- By bringing the essential knowledge about the project in a structured manner, README serves as a lantern for all of the programmers from the future - including the future YOU!
- We should be honest with ourselves and accept that over time code becomes more and more alien. In fact, dreadful legacy code is simply anything we’re not writing right now. And README helps with legacy code A LOT!
- We have all been there. So out of sheer respect to our countless hours lost trying to figure things out from the source, we should do our best to save the pain for the programmers to come.
- If you are not convinced yet, bear in mind that writing docs is a discovery journey into the very depths of your app. And this usually results in finding most surprising bugs in most surprising places! :D
Content¶
There is no obvious consensus regarding what README should contain. However, it seems that a good one should at least answer the questions below (provided they are applicable):
Project:
- What is it about?
- Why is it needed?
- How does it solve the problem?
Application/Library:
- How to build, install & test that it works?
- How to use it?
- How to deploy?
How to contribute to the repo?
If you want to get inspired, Make a README and Awesome README are fantastic sites to dig.
Format¶
The recommended format of README is Markdown. This lightweight markup language is simple, powerful and popular, making it a perfect choice for most of the projects.
A viable alternative is reStructuredText. However, it is far more advanced than Markdown, which for README might be an overkill.