They say that when we meet someone for the first time, that initial impression is the most important one. The same applies to a project code repository. A well-written README is crucial not only for current developers but also for future ones. It introduces the project and provides step-by-step instructions that allow quick setup and contribution.
It should contain every aspect that the developer needs to know and that cannot be received directly from the code. These include development dos and don’ts, full deployment instructions, external integration descriptions, and so on. This post will guide you through creating a powerful, beautiful and legible README file for your project.
A nice introduction for well-prepared project documentation can be found on github guides: https://guides.github.com/features/wikis/. This states that “README should contain only the necessary information for developers to get started using and contributing to the project”.
With this in mind, let's introduce a list of components and best practices we follow at Codest for creating project documentation.
- Project title: this is a must-have for every README.
- Status badges: if you use any external code quality measurements, automated testing or other tools, the beginning of the document is a good place to show others if they work.
- Description: include a few sentences about the project to quickly describe the main purpose and what it does.
A contents list can be useful for long documentation files, but if your README is quite concise then it is not necessary.
- About section: this should be a more detailed description of the project – it may include information about users, their roles, some more-confusing cases, and screenshots, etc.
- Mockups: a place for links to UI/UX mockup resources if there are any.
- Requirements: prerequisites that must be fulfilled before starting an application setup, e.g. external tools installation.
- Setup: a step-by-step instruction to follow to get the project up and running.
- Settings: describe where local settings are stored and provide instructions on how to receive your own settings.
- Local configuration: if there are some cases for local setup, this is a good place for an explanation.
This section is an ideal place for instructions such as feature development, bugfixes, hotfixes, common features, testing, style guides, code organisation, other development tools used in the project (e.g., guards or dockers), and so on. Don’t forget to mention all the rules that every team member should know.
Provide clear step-by-step instructions for each environment and everything that is “good to know” while making the deployment.
- API documentation
- Changelog
- External resources: a place for all sort of links that may be helpful.
- Application stack: a list of the application stack that we use in the project – may contain a short description and the name of the provider.
It’s debatable whether it’s necessary to show current project team members (github provides the full list of contributors by default) but it’s always nice if you see your name as one of the authors of a project. If you do this, keep it as up-to-date as possible.
Remember: each project is unique and so is its documentation. There is no one great solution for writing a README. Just follow the general tips, and the most important thing is to always remember about refactoring, which also connects to the README. It is always a good idea to look at the document as a whole and rethink it if something needs to be displayed in a different way.
One more thing: “instructions” are key so write them a lot. Thank you!
Read more:
