A beginner’s guide to writing documentation
Note
This is a write up of a Presentation . Please provide feedback to @ericholscher. You can view the source on GitHub.
Camera pans from stage left.It shows a text editor, open to a blank page.A person hunched in front, head to desk.
The scene above is well known to everyone who writes for a living; the mixed emotions of a blank page. Full of excitement, fresh with a new beginning. Yet also full of despair, where do you even start?
I am here to stop this scene from playing out.
This is a guide to documenting your first project. The first time is always the hardest, and I hope this guide will get you started down the righteous path. At the end, you should have a project that is ready for public release.
Feel free to read this document straight through, or simply use it as a reference.
Why write docs
You will be using your code in 6 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.
You want people to use your code
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.
There are a small number of people who will source dive and use any code out there. That is a vanishingly small number of people, compared to people who will use your code when properly documented. If you really love your project, document it, and let other people use it.
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.
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 allows 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.
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.
Version controlled plain text
As programmers we live in a world of plain text. Our documentation tooling should be no exception. We want tools that turn plain text into pretty HTML. We also have some of the best tooling available for tracking changes to files. Why would we forgo using those tools when writing documentation? This workflow is powerful, and familiar to developers.