This document provides recommendations for documenting a README file for open source projects at Wizeline. It outlines two paths to follow. The first one suggests you to do a checklist of things you need to consider before writing your README. Once you have identified the main points to address, you can follow the second pathway and start writing down your README using a sample template. Feel free to choose the pathway that best suits your needs. Let's get started!
-
Pathway 1 - README Checklist
Refer to the README Checklist from Daniel D. Beck to start outlining your README file. -
Pathway 2 - README Template
Use the following template as a guide to include the information you gathered from your checklist. Bear in mind that you can personalize it, so feel free to skip sections.
Tell your audience your project’s name
Write down the author(s) of the project
Include one sentence that quickly describes the purpose of the code in this repository.
Include a screenshot of the primary user’s interface of the project
Add some of the following badges to make your README more beautiful
- Workflow Statuses
- Issues
- Release version
- Discord and social media
- License(s)
- Introduction
- Local Installation
- Tests
- Deployment
- Contributing
- Versioning
- Licenses
- Getting Help
- Documentation
- Contributors
Include one paragraph briefly describing the story behind your project and what is in it for your main audience. Focus on the why and the what for instead of the what and how. If you need to add more details, consider including an additional source of information such as a Wiki.
[Optional] Include a table that briefly describes the primary folders and files located in the root folder of the project
Include step-by-step instructions for how to install the project locally
Describe things you need to install on your system before you follow the rest of the instructions. You can include links to external resources.
Include instructions on how to install the project’s services on your computer for the first time. You can break this section up into subsections to be more specific. For example: setting up the database, starting the backend service, or configuring the environment variables.
Explain how the following tests work:
- end-to-end tests
- linting
- security tests
Add required information to understand how to deploy the project.
Mention all required credentials, tokens, and other sensitive artifacts developers need to know to deploy the code. Explain the process of acquiring these.
Tell your audience how they can contribute to your project. Create a CONTRIBUTING.md file that defines the following guidelines:
- Why contributing
- Coding conventions
- Branching model
- Reviewing process
Explain the versioning pattern this project follows.
Describe the terms and conditions to use your project and name its licenses
Include communication channels (Slack, Discord, etc.) in case your audience needs assistance.
Refer to any additional information such as internal or external links your audience can consult such as FAQs, tutorials, videos, etc. Tell your audience where to go if they need to know more about the project.
Include a list of all contributors