You are here:

The Case for Writing Your Own Documentation

Posted Dec 28, 2015 02:50 PM
Documentation is important when planning, implementing and improving upon a technology project. Unfortunately, both process and technical documentation tend to get pushed to the side by organizations. We provide a compelling case for why you should write your own documentation, how you can use it for maximum benefit, and helpful tools to get you started.

In almost any project, whether it’s online technology or otherwise, the task of generating documentation is much maligned.

It’s understandable why this is. Documentation is time-consuming and often underappreciated. But if you reframe what the purpose of documentation is, you can turn a boring chore into an important part of the success of your new project. Did you know documentation can be used as a project management tool? How about a new staff onboarding resource and user adoption tool?

Two Flavors of Documentation

First off, let’s understand that there are two kinds of documentation. First, there is process documentation, which is sometimes called “end-user documentation.” This is where you record all of the context for why you are performing a given task, who is responsible for it within your organization, what the next steps are, what naming conventions you expect to be used, and so on. In other words, it’s how you would explain to a new employee how something should be done. You should already be familiar with this kind of information and context. This is the main reason why asking a consultant to write your documentation for you is often not the best choice to make.

Second, there is technical documentation, also known as “reference material.” This is where you would find information such as the datatype of a new database field, narrative description of what a piece of programming is doing in your environment, how to select a new image for your homepage banner, etc.

Technical documentation should be written by the person (or persons) who created these customizations in the first place. But you need the process documentation alongside the technical documentation to provide a complete picture. For example, we could record that we created a checkbox field in your database called “Do Not Solicit” and that when that box is checked, “Do Not Mail” is also automatically checked. That’s the technical side. You as the client need to record why you would check that box in the first place. What circumstances is it appropriate to check “Do Not Solicit?” Does that also mean these people should not get your newsletter?

Useful in Project Management

If you get in the habit of writing documentation early in the lifecycle of a project, you can use it as a project management (PM) tool. A big part of PM is keeping track of various decisions and why those decisions got made – as well as what is going to be built now versus later.

For example, let’s say that even before you start collaborating with a web developer, you work with your project lead to determine how your website’s new homepage is going to function. There’s a lot of detail to capture, including: how many images should go in the carousel? How long between each slide? Are we providing navigation buttons? What dimensions do the images need to be? How do we capture and display photo credits? And so on and so on.

You should record all of these decisions as if they’re the documentation for the final product. Of course things are going to change over time, but you will have a single place to keep track of the functionality you’re building so at the end of the project you’ll already have most of the documentation done! Not only that, but it will be very accurate and up-to-date.

A Living Document

Documentation, like art, is never truly finished. It can only be abandoned. But don’t do that! Some of the most interesting work happens after a project is completed and the consultants have moved on to other work.

You have a new shiny object at your organization, such as a new website or enhancements to a database. However, it’s still pretty fresh - and you’re going to keep improving that new item on your own. Your understanding of it will change and deepen over time and you may also change how you use it. Your business processes might change. All of these things should be reflected in the documentation resources you’ve been curating back when you were actively working on this project to begin with. Documentation should be seen as a living document that is consistently updated over time as your organization grows and develops.

To summarize, we recommend you:

  • Own the process documentation yourself - and don’t ask a consultant to do it for you!
  • Let the consultant handle the technical documentation.
  • Start writing the documentation early. Don’t wait until the end of the project to document. You should include documentation in each iterative cycle of your project.
  • Use documentation as a way to record shared understanding, i.e. project management.
  • Know that you will need to revise it often.
  • Keep revising it after the project is finished.
Tools for Success

There are a host of tools available to you to help with documentation. Here a few of the most common ones to consider:

  1. Screensteps - A great tool for generating documentation such as screenshots. You can produce PDFs or Word files and even utilize Screensteps web hosting to make it accessible online.
  2. Google Docs - A great way to collaborate with others and disseminate documents to your staff. Many organizations use Google Docs for all kinds of file sharing.
  3. Your Website - Your website CMS probably supports private documents that are only accessible to logged in users. You can create a “hidden” section of your site for staff to use.
  4. Jing Video - Video is a powerful way to explain process documentation to someone. Jing is a free tool you can use to capture up to 5 minutes of video of whatever is happening on your computer screen. You can save your videos in a library and share them with hyperlinks.