As a fellow developer, I have spent my share in writing and reading documentation. Since documentation is the foundation for good developer experience, here are a few things that you should consider while writing it.
Where to start?
A great and efficient way of documenting your project starts from README. Oftentimes, developers while creating their projects either skip the README by writing the names of the projects or sometimes they just include how to run their project. Now is the time to fill those READMEs.
How to start?
Ever heard of the quote “If you can't explain it simply, you don't understand it well enough." Maintain a simple template that is understandable by everyone.
Now your project may be an implementation of a platform(clone), a package or a plugin. Start with what the project is about and what it does, what problem it solves and add some project features if any. List down the requirements and the installation guide. Here's an example.
# Project description
A short descripton on what your project is about
# Features (Optional)
Project features
# Requirements
# Backend and frontend requirements if project has frontend
Backend
- Python 3.6+
Frontend
- Angular v10
# Installation guide
Step by step installation guide
# Code examples
Code block of api endpoints, functionality, class or methods
# FAQ (Optional)
# Contribution guidelines (Optional)
# License
Your installation guide must include steps from cloning the repository to running the project. If you are using a virtual environment, make sure you add it to the requirements and the installation guide. Here's an example of an installation guide from one of my projects on GitHub.
# Installation
- Clone the repository and enter the root directory
```
git clone ...
cd...
```
- Create a virtual environment and activate it
```
virtualenv venv
source venv/bin/activate
```
You can check the whole code here.
API Documentation
If your project has API integrated, you might want to add that to the documentation. Swagger and Redoc are some of the open-source tools to achieve interactive API documentation for your project which I prefer integrating into my projects
Optional
Additionally, inserting a small code example can also be helpful to users. It can be a code block of functionality or model creation. Although the heading is called optional, you can consider it as a part of your readme template. Requests, the HTTP library for Python can be a good example of this.
Next steps
If your project is open source, make sure you add the contribution guidelines. An issue tracker and an FAQ section can be added as well. Algorithms/Python is a great example that has detailed contribution guidelines. For further reading, check out this post on how to maintain an open-source project.
Conclusion
In short, your documentation should have a
User guide [requirements, installation, code example]
Community guide [Support, FAQ section]
API documentation/guide [Api endpoints and schema]
Contributor's guide [contribution guidelines]