Dr. Pagelove or: How I Learned to Stop Procrastinating and Love the Documentation

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!

Dr. Strangelove

 

Incorporating documentation into your workflow is a hard sell, but consider this:

  • Documentation saves time (and headaches) later in the process by providing a singular source of “truth” for the development team.
  • Writing documentation keeps teams focused on the big picture as well as the details.
  • Clients can reduce or eliminate the need for internal training.
  • A well-documented product lets users know that their experience is important to you.

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.

So who should be writing documentation?

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.

Dr. Strangelove
These guys know what I'm talking about. Look at all those documents!

Ways to ease the burden of documentation

  • Reuse existing documentation: User stories, test steps, and even behat scenarios can be recycled into instructional documentation. Business value can be pulled from a proposal or requirements document. Use the project plan to help shape the outline of your documentation.
  • Work iteratively: Start small, just make sure you start. 1: Go here. 2: Enter this value. 3: Hit Save, etc. Slowly build on the basic framework by noting prerequisites, permissions, edge cases, etc. (Pro tip: hold off on visuals like screenshots or diagrams till the end. Don’t waste time creating assets that will inevitably change throughout the course of development.)
  • Less is often more: Rely on bulleted lists and tables to maximize readability and save the exposition for that novel you always meant to write.
  • Write in real time: Write and revise documentation in tandem with development. You may not remember all the important minutiae 2-3 sprints from now.

Find the right documentation tool

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.

Hosted solutions:

  • GitBook: This open source documentation platform allows you to create shareable (or private) documents, or books, using familiar editing tools in a wysiwyg format. GitBook offers commenting functionality and the ability to review and accept changes to documents as needed.
  • Read the docs: Consider using this publically searchable documentation solution to maintain versioned documentation written in markdown syntax. Read the docs also pulls and publishes code from repositories for documentation with a more technical focus.
  • Confluence: If you are already using Jira, it may be a smart move to invest in a Confluence license. Confluence offers tons of formatting options, 3rd party integrations and team management features like calendars. If you can dream it, Confluence can probably do it (or offer a plugin that can do it).

Internal solutions:

  • Google docs: This is a tool that many of you may already be using. Google docs are perfect for a quick one pager on a feature, or a more comprehensive document. Fiddle with permissions on who can view and edit, or export as a PDF file to send to clients.
  • Dropbox Paper: Assign specific tasks, set due dates and link to stored client docs. Dropbox Paper provides flexible layouts that can include more than just text.

 

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.