Table of contents
- What code documentation is.
- Why write docs.
- Best practices for writing documentation.
- Tools for documentation.
- Software documentation hosting options.
Camera pans stage left.
It shows a text editor, open to a blank page.
A person hunched in front, head to a desk.
The scene above is well known to everyone who writes for a living.
The mixed emotions of a blank page, Full of excitement and fresh with a new beginning,
Yet so full of despair.
where do you even start?
I am here to stop this scene from playing out.
This is a guide to document your first project. The first time is always the hardest, and I hope
this guide will get you started down the righteous path.
In the end, you should have a project that is ready for public release.
What code documentation is
Code documentation is a text that accompanies software code to explain what your code is doing, why it's written the way it is, and/or how to use it.
Why write docs
1) You will be using your code in six months
Code that you wrote 6 months ago is often indistinguishable from code that someone else has written. You will look upon a file with a fond sense of remembrance. Then a sneaking feeling of foreboding, knowing that someone less experienced, less wise, had written it.
As you go through this selfless act of untangling things that were obvious or clever months ago, you will start to empathize with your users. If only I had written down why I had done this. Life would be so much simpler. 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.
2) You want people to use your code and give you credit
You have written a piece of code and released it into the world. You have done this because you think that others might find it useful. However, people need to understand why your code might be useful for them before they decide to use it. Documentation tells people that this project is for them.
If people don’t know why your project exists,
they won’t use it.
If people can’t figure out how to install your code,
they won’t use it.
If people can’t figure out how to use your code,
they won’t use it.
3) You want to learn self-determination
There is a magical feeling that happens when you release your code. It comes in a variety of ways, but it always hits you the same. Someone is using my code?! A mix of terror and excitement.
I made something of value!
What if it breaks?!
I am a real open-source developer!
Oh god, someone else is using my code...
Writing good documentation will help alleviate some of these fears. A lot of this fear comes from putting something into the world. My favorite quote about this is something along these lines:
Fear is what happens when you’re doing something important.
If you are doing work that isn’t scary,
it isn’t improving you or the world.
Congrats on being afraid! It means you’re doing something important.
4) Others will be encouraged to contribute to your code
5) You want people to help out
Open source is this magical thing, right? You release code, and the code gnomes come and make it better for you.
Not quite.
There are lots of ways that open source is amazing, but it doesn’t exist outside the laws of physics. You have to put work in, to get work out.
You only get contributions after you have put in a lot of work.
You only get contributions after you have users.
You only get contributions after you have documentation.
Documentation also provides a platform for your first contributions. A lot of people have never contributed before, and documentation changes are a lot less scary than code changes. If you don’t have documentation, you will miss out on a whole class of contributors.
6) 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 your code. Talking through your API and design decisions on paper allow you to think about them in a more formalized way. A nice side effect is that it allows people to contribute code that follows your original intentions as well.
7) You want to be a better writer
Writing documentation is a different form of writing than most people have experience with. Technical writing is an art that doesn’t come naturally. Writing documentation will start you down the road to being a better technical writer, which is a useful skill to have as a programmer.
Writing also becomes easier over time. If you don’t write for many months, it is a lot harder to start writing again. Keeping your projects documented will keep you writing at a reasonable cadence.
Starting simple is the best way to achieve actual results. I will present a well-paved path to walk down, and after you have the basic idea, you can expand your scope. The tools should be powerful and easy to use. This removes obstacles to actually putting words on the page.
#Best practice for writing documentation
1) Include a README file that contains:
- A brief description of the project.
- Installation of instructions
- A short example/ tutorial.
An example of a README file.
2) A link to your code & issue tracker
People like to browse the code sometimes. They might be interested in filing bugs against the code for issues they’ve found. Make it really easy for people who want to contribute back to the project in any way possible. I think the Python Guide does a good job with the link to the code portion.
3) Write API documentation.
- What function can do.
- What are the function's parameters or arguments are.
- What a function returns.
4) Document your code.
An example of code documentation.
5) Apply coding conventions such as file organization, comments, naming conventions, programming practices, etc.
6) Include information for contributors.
7) Include citation informations.
8) Include licensing information.
1) Python
2) R
3) C++
- BoostBook
- Quickbook
- Ghostdoc
4) JAVA
5) Ruby
software documentation hosting options
1) GitHub
2) ReadTheDocs
