README

The first thing everyone sees in your product directory is README - an introduction of the product to a user. Make it thorough but simple, add every important information, and keep it updated.

What Is a README

A README is a text file that introduces a product to a user. It contains information that explains why the product is useful. It also ensures that the user knows how to use the product. A README file is usually the first thing the user sees in the directory of the product. It is most commonly written in a Markdown, which is a lightweight markup language with plain text format (for more information, see Wikipedia: Markdown).

A README file typically includes (at least) some of the following sections:

• Name
• Description What does the product do? Why is the product useful?
• Badges Badges contain metadata that show that the project is taken care of.
• Visuals Sometimes it is useful to add some screenshots or videos.
• Installation instructions How to install the product?
• Operating instructions How to use the product? Provide examples.
• Support/troubleshooting Where can the user get help with the product?
• Roadmap Ideas for future releases.
• Contributing Are you open to contributions? In what conditions?
• Authors and acknowledgment Who maintains and contributes to the project? Acknowledge the authors and maintainers.
• Copyright and licensing information
• Known bugs
• Changelog (for developers) A changelog is a record of all the major changes made to the product.

Why You Might Want the README

README contains all the important information about your product. It answers the basic questions users may have and provides them with the information where to find more answers. A good README ensures that the other team members, product users, stakeholders, and others are able to understand what is your product about. A great README makes your product exceptional and gets the users’ attention. Without a README people do not have a chance to understand your product, no matter how great it is.

Issues the README Solves

• Poor code quality
• "Not my problem" mentality
• Meaningless work
• Unhappy clients
• Toxic Team Culture
• Knowledge hoarding

How to Implement the README

1. Start writing the README before you publish your product. README should be the first file you create.
2. Put it in the top level directory.
3. It is recommended to use Markdown language. Keep the format simple.
4. Make it thorough but simple. Use short sentences and paragraphs but do not miss any important information.
5. Keep it updated.
6. Use examples.
7. Link to other places if the data is too large or sensitive to keep it in README.

Common Pitfalls of the README

• It is not being updated regularly.
• It is too short or too long.
• The maintainer is not mentioned - the support is missing.
• It is not part of the depository and, therefore, difficult to find. Developers are used to looking for README in the root.

Resources for the README

• Github: About READMEs
• Github: Making READMEs Readable
• Github: awesome-readme: A curated list of awesome READMEs
• Computer Hope: README file
• Danny Guo: Make a README
• Medium: A Beginners Guide to writing a Kickass README
• Reinteractive: On the Importance of a README