Like going to the dentist, writing documentation for software is important. And much like going to the dentist, no one wants to do it unless they have to. It’s like pulling teeth (pun intended) trying to find the time and motivation to record the inner workings of an application that you and your team are working on hour after hour, day in and day out with nary an end in sight. “I’ll start on it next week,” you say. “I have plenty of time.”
Fast forward 3 sprints, 2 phases, 1 work order. Bug tickets are multiplying like cockroaches. That tricky feature got trickier, and that scope creep got creepier. Speaking of that tricky feature, how does it do x again? How do I configure y and z? Where did I write down those recall codes?!?
You could cue the mushroom cloud, or you could do what I did: stop procrastinating and learn to love the documentation!
Incorporating documentation into your workflow is a hard sell, but consider this:
Treating documentation less like an undesirable chore and more like an intrinsic part of your development life cycle will ensure that everyone is on the same page (pun also intended) about how your product functions.
Remember that documentation need not be the next War and Peace in quality or breadth of subject. Write simply and clearly with a consistent voice, and make the most effort where it will provide the most impact. Otherwise this can be one of those rare occasions in software development when just enough is perfectly fine.
Having a dedicated documentation specialist on a project is a luxury, but expecting only developers to write their own user documentation is a big ask and not practical for a budget’s bottom line.
Instead, spread the wealth. Resources like project managers, product owners, or QA specialists are already very familiar with the audience and the usability of your software and can speak on business value.
Leave the technical specifications, like API documentation, to the developers. If you work collaboratively and delegate writing tasks appropriately, then each team member can comfortably write about what they know.
There are a bevy of documentation tools at your disposal. Figure out if you need the documentation to be public (hosted) or private (internal) and learn the basics of markdown. Using a tool consistently will minimize guesswork when looking for specific documentation.
With these tools at your fingertips, you're well on your way to learning to love documentation.
Don't have the bandwidth to tackle documentation internally? Let us know how we can help.
Jessica graduated from Temple University with a degree in Architecture, but her affinity for computer-aided design led her to a career in graphic design, creating print advertisements for The Yellowbook and The Philadelphia Inquirer.
View the discussion thread.
Tell us about your project