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:
- 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
- Start writing the README before you publish your product. README should be the first file you create.
- Put it in the top level directory.
- It is recommended to use Markdown language. Keep the format simple.
- Make it thorough but simple. Use short sentences and paragraphs but do not miss any important information.
- Keep it updated.
- Use examples.
- 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
Want to write for DXKB?
Feel free to contribute. People from DXKB community will be more than happy.
Software documentation explains how the product works or how to use it. Different types of software documentation are created through the whole product development lifecycle.Read more
License in Repository
Every product should be covered by a license. It is your creative work, you own it and you should decide what other people can or cannot do with it.Read more
In an Agile environment, teamwork is divided into small pieces called User Stories. It helps with sprint planning. They are written in a basic language.Read more
Documentation testing is a process of improving your existing documentation through feedback. Understanding how to get feedback is crucial for building good documentation and positive developer experience.Read more
Operations Logbook allows you to collect, store, and share data in real time and dig your historical data easily. Record every incident and every important event related to your project.Read more