Writing good and detailed documentation
Last two weeks I've been writing documentation for Lever programming language. I am not done yet but maybe I will never be.
I have been terrible at writing. What I write tend to be short. Even that comes out painfully slow. And then people don't read what I write.
During the last two weeks my writing skills have improved most they have had on the period I've kept this blog - From 3½ years these two weeks taught me the most about literature.
If you have open source projects that require documentation, and you feel like you can't make documentation that would serve its purpose, you may be interested to read on. The main takeaway I have to offer is this:
Details are fun.
Background
I don't claim I'd be professional at writing. I'm an amateur who thinks he just figured out how to write properly. Do not try to imitate my results. Instead copy the process of getting there.
There are countless blog posts where I haven't written down enough details. You won't understand what they say or not gain anything from reading them. Oh I can myself read them. They bring me the memories that let me fill in the details from the abyss. They keep doing that even if I forgot long time ago that I wrote them. It's easy to not see flaws in your writing.
I have fears about writing details. When you work on something for very long, the details of that work ingrain and become part of you. They may describe you and have become things you find uncomfortable to write about. They constantly try to hide when they would be revealed.
I've always felt uncomfort and incertainty about writing even the short posts I've written. Writing in detail is even more tedious. Beware comfort though. When you're comfortable writing it may mean you're not telling out enough details. Details are uncomfortable to write down.
At worst it's like ripping out pieces of your inner self and gluing them to paper. Writing hurts.
Blurry painting analogy
But details are fun. They feed the people who read your text and give it the meaning.
I found it helpful to think this in terms of paintings. Undetailed text is like a blurry painting. It may be so blurred that others can't tell it apart from a flat painted wall. You as the painter may see the blue ocean there, with foaming, cold water, clouds on tufts, seagull on the sky with thick fethery cloth that holds water, with orange beak and disparaging eyes. Your audiences see a blue painted cloth.
The painting analogy is quite good. Like in paintings, details make the text matter. They give the work personality, context, esteem and value. Just in the same way as they do in an image. Same way the details in text have higher frequency in signal processing terms, and they require larger resolution to display properly. Detailed texts are longer, but they remain or even become worthwhile to read.
Garbage
Anyone who has read matriculation essays know that it's possible to write many pages by writing just plain garbage. Writing detailed text isn't same as writing garbage.
It's surprisingly easy to avoid writing garbage. Simply don't favor long texts over short ones.
Instead of that favor details as they are fun.
In case you're a highschool student and haven't written your matriculation essay yet. Please write garbage. Make it grammatically correct, as long as you can and prepare for good scores from teachers.
Writing plan
To make it easier for yourself to come up with details. You may like to follow some kind of writing plan, such as:
- Preface with what led you to create it
- Tell what it offered you
- Write down some use cases you have for it
Choice of writing plan depends on what you're writing. To make it further easy you may want to imagine the person who you're writing for. Imagine what she would be interested to hear. Put her ask the questions she would never ask, and answer to them by writing the answers down.
No survivors
Write down even the few short things you realise. You need to get them out to make room for more questions and answers to surface.
Leave no survivors. Write down both shit and great thoughts. Remember that details try to hide from the writer. Your preconception of what's great to write and what's not is a fantastic cover for details. Blow it to smithereens!
Iterate
While details are fun. Iteration is the soul of good writing. This sentence was rewritten and restructured four times before you could have seen it.
Rewriting doesn't only mean deleting your work and starting again from scratch. It's radical but it often doesn't improve your results if you're short on writing to start with.
Rewriting is to read your text, then depending on what improves the text:
- Move sentences around
- Move things in sentences around
- Move things across sentences
- Writing new sentence to replace clumsily written sentence
- Removing words and sentences that are or become useless during writing
Each action you do during rewriting should improve your text. I do not need to tell how doing anything of this improves your text. You will learn how different things change the text by experience.
Lever-rage
To start writing Lever's documentation, I made a list of every source file in Lever's runtime. Then I started to go through that list. For every file...
- I made a section into internal_documentation.txt and opened the source file side by side.
- I wrote down what I remembered about the file.
- I wrote down what the contents in file do, how does it interact with other things.
- I wrote down what led me to do it.
- I wrote down what the approach I picked offered me.
- I wrote down which use cases it had.
- I wrote down how some things in this file didn't match with the remaining features in my language.
Then I iterated.
After that I did the same thing on higher level and rewrote my README. I derived usecases and examples from the files I had read. This way nothing is invented. The whole documentation is accurate and clear.
Once I wrote about MenuetOS. I was so inspired that I wrote some compiler code with the intent to imitate the binary-structure isomorphism MenuetOS holds.
The whole MenuetOS source code follows the format where it writes down into a binary machine code. The code does not divert execution flow without a reason. Everything is clearly describing pieces the kernel builds up from. It is really easy to follow where it goes and what happens, even if it's been written in assembly! The awe of that propels me forward even today.
But MenuetOS doesn't hold lots of documentation about its functionality.
Benefits of writing documentation
Lever's documentation became a description of how each piece works, why does they matter and where does each feature come from.
While I was working documentation:
- I discovered several bugs.
- I got tons of cues for improving the code.
- I truly appreciated the value of what I have written. It made me happy.
To continue keeping the documentation updated I tend to rewrite it at times. But some day I'll have to do this again. I will be going through the files. I will write and rewrite.
Every time it'll get better.