Why write the docs
You will be using your code in 6 months
You all know why!!!
If only I had written down why I had done this, life would be much simpler.
– someone
Documentation allows you to transfer the why behind code. Much in the same way code comments explain the why, and not the how, documentation serves the same purpose.
You want people to use your code
You released your code into world, and thought that others might use it. However, people need to figure out why and how to use your code, before they decide to use it.
- If people don’t know how to install it, they won’t use it.
- If people don’t know how to use it, they won’t use it.
- …
There are only a small group of people who will dive into your code and use any code out there. So, Document your project.
You want people to help out
Only if you have documented your project, others will be willing to help you improve the code or documentation.
You want your code to be better
It’s really easy to have an idea in your head that sounds perfect, but the act of putting words to paper requires a distillation of thought that may not be so easy.
Writing documentation improves the design of you code. Writing down the design decisions allows you to think about them in a more formalized way. It also allows people to contribute code that follows your original intentions.
You want to be a better writer
Writing is a useful skill to have as a programmer.
Writing becomes easier over time. If you don’t write for a time, it is a lot harder to start writing again. Keeping your projects documented will keep you writing at a reasonable cadence.
README
The first step in documentation should go into your README. It is the first interaction that most users will have with your project. So having a solid README will serve your project well.
Start your project with a README
What to write
- What problem your projects solves
- A small code example
- A link to your code & issue tracker
- Frequently Asked Questions (FAQ)
- How to get support
- Information for people who want to contribute back
- Installation instructions
- Usage
- License
Template
Project
***
**Project** will solve your proble of where to start with documentation, by providing a basic explanation of how to do it easily.
Look how easy it is to use:
```
import project
# Ger your stuff done
project.do_stuff()
```
***
Features
- Be awesome
- Make things fater
***
Installation
Install **project** by running:
`install project`
***
Contribute
- Issue: github.com/xxx
- Source code: github.com/xxx
***
Support
If you are having issues, please let us know.
[email protected]
***
License
The license