When I was a child, I studied computer studies. We had to hand in coursework, which required writing some software and producing documentation. Owing to a combination of laziness, ambition, and general last minute panic, both my submissions for large project coursework ended up in a 48 hour continuous development effort, including writing a ton of documentation.
I would produce all sorts of user guides, data dictionaries and other code rewritten as documentation nonsense in a mad rush to submit the project.
I imagine that the documentation I wrote back then was appalling by my own current standards.
Rule One – Much We Write Is Pointless
Ironic to put this in a blog post, I know… but a lot of things people choose to write down as documentation are a waste of screen space. This can be:
- It’s overwritten and thus unreadable – c.f. the Harry Potter books which would be excellent if 30% of their actual size
- It states the flaming obvious
- It refers to low-level details that nobody cares about
- It takes great pains to explain surprising and bad technical decisions – a better solution is to fix them rather than document them
- It’s delivered in a place where nobody can find it – c.f. the Write Only Wiki
Our goal must be to get value of out documentation we write.
Rule Two – Teaching is Learning
Having just explained how writing can be a waste of time, let me look at some enormously positive experiences I’ve had on a recent project.
I’ve rebuilt a test library – System Stubs. Though the original library – System Lambda – was very good, it didn’t fit my use cases and the original author did not agree to extend its scope to do so. Given the author’s explicit permission, plus the MIT licence, a rewrite was an option, which I chose to take.
The original author of this library provided decent documentation both in terms of a
README and JavaDoc.
As I extended the library, I added to this documentation.
Towards the end of the project, I reviewed the documentation and also write a guest post about the project for Baeldung.
While documenting this, I made several discoveries about the software I’d been working on. This was because I was looking at the software from the outside. As a result of the exercise, I changed the software in a few ways.
Rule Three – Consume While Writing
As there is such a thing as write-only code – code that’s easy to produce, but impossible to understand – so there is a similar thing with documentation.
One recent discovery is that producing markdown format documentation can be a very one-way process. Something about the rendering of the plain-text markdown makes it less readable. Compare:
Clearly the first one has better shapes, colours, and visual cues. While writing and editing it, one needs to easily switch from producer to consumer. Does what I have written make sense?
While writing blog posts or documents, we’re used to having a WYSIWYG editor. Markdown is a poor cousin of that. TBH, many wikis are similarly awkward.
While some markdown editors allow you to see a preview pane next to the editor, Typora previews as you edit. It shows you minimal markdown characters on the word or block you’re presently editing, and essentially hides the markdown for everything else, rendering it for reading.
Suddenly you can see what your document actually says to someone else.
The right document is good. Write documentation.
Make sure your writing process comes with a good feedback loop. Be your own reader. Consider what you’ve had to write and whether the software should step up to make itself easier to understand.