It is the elephant in the room, the monster in the corner, the darkness waiting to claim your job. It sneaks up on you quietly, stealthily, like a lion waiting to pounce. It is endless, varied, impossible to predict and harder to defend against. Everyone has encountered it, battled it, even defeated it on lucky occasions. And yet, no one notices when the outcome is positive, only when you lose and the monster devours you. What is this scum, this plague upon the earth and your career?

It is the writing of technical documentation, and it only becomes something to be afraid of if you are doing it wrong.

A bookshelf, desk, and floor covered in various documentation manuals, looking disheveled and out of order. Photo by Iopensa, used under license

Writing Documentation Sucks

Writing documentation is probably one of the most boring jobs a developer has to do on a regular basis. Most of the time, we're just regurgitating what we already know in a semi-readable format so people with less experience in this particular system than us can read it and complain that we didn't know what we are doing. They may not be wrong, but still.

Writing documentation sucks. But why does it suck?

  • It's not creative in the least. Software development is ultimately a creative profession; we are asked to design solutions to complex problems using software and given quite a bit of leeway in how exactly to do this. We are free to be creative in our code. Documentation allows us none of that freedom, as by the time we can write the documentation the creative part of the job (designing and writing the software itself) is over and done with.
  • It's very likely to change in the future. It's rare that we have a project where we're actually, truly done when we start writing the documentation. Software is malleable, and so the documentation must be as well. Which means that we could easily end up writing the same set of documentation multiple times just because the code changed.
  • It's often a time-sink, and one that could easily be mistaken to have little tangible benefit. If anyone's ever complained about "not being given enough time to write coherent docs" then they're falling into this trap, which is often placed and set by poor management hoping to shave a few hours off the already-slipping schedule.
  • It's just not fun. Nobody likes writing docs.

And yet... And yet we have to do it. There's no excuse not to.

Do It Anyway

When faced with the prospect of writing documentation for my code, I do what any self-respecting programmer would: I stall for time. I complain that the code isn't done yet, that we don't have all the requirements, that the users will never read the docs. Very often I'm right about some of those things, and I wield them as an excuse sword so I can put off the not-creative, not-quick, not-fun task of writing documentation.

But that's all they are: excuses. And my propensity to stall will just cause this pent-up work to become bigger, more imposing, more intimidating. All the excuses in the world, no matter how I use them, will not save me from writing documentation.

If you've ever been that person pounding on your keyboard because the incomplete, haphazard documentation for this piece of software you're trying to use is doing nothing but killing your brain cells out of frustration, you already have all the justification you need to write good docs. Writing good documentation saves developers (often yourself) from this pain.

So, if it's not enjoyable but it's critical to have, can we make writing documentation, if not fun exactly, at least easier to manage? Of course. Here's how I accomplish that:

  1. If you want other people to use and understand your code (hint: you do) then be clear, be concise, don't be clever. People need to be able to read your documentation and understand it without having to ask questions or make assumptions. This is a tricky thing to do reliably, and experience will help you get better at it.
  2. Write the docs at the same time as the corresponding code. This way it won't get put off until you can't avoid it anymore. Technical debt applies to all aspects of software development, including documentation
  3. Automate what you can. There are lots of little things you can do to speed up the actual writing part of documentation. NuGet packages like Web API Help Page, Visual Studio shortcuts like ///, even documentation generators like GhostDoc can speed up this process. (Here's hoping StackOverflow's Documentation expansion takes off).
  4. If you do it for no other reason, write the docs because you will probably end up using your code in 6 months and will need to help yourself remember what problem you were actually trying to solve.

Documentation sucks. Do it anyway. Other developers, and even the future you, will thank you for it. Not out loud, of course. But we will be thankful.

Need to express how much your documentation sucks, or want to share how good your team has made it? Share in the comments!

Happy Coding Writing!