Documentation Strategies

The magic of a project really happens in the final days of implementation – this is where ideas come to fruition. When the documentation stage of the project is reached, gathering the accumulated knowledge of a project can prove to be a chore for some consultants.  Oftentimes a bulleted list of “issues encountered” are all that remains of the many notes taken during a successfully completed project.  What should serve as knowledge transfer and lasting hallmark of the team’s accomplishments is instead a cryptic grocery list of what was fixed along the way. The documentation of a project is what remains with a client long after a consultant has moved on (it acts as a lasting footprint). With a few simple considerations you can provide your client a truly valuable knowledge base.

Logic and Pictures:

The common adage that a picture is worth a thousand words holds even greater weight when used in technical documentation. A single screenshot of an application’s interface can save time in troubleshooting as well as aiding in the recreation of settings if the work of the project ever needed to be recreated.

When considering the information that you include in your documentation, think of how the document would be interpreted if someone with no experience of the project needed to recreate the project from the ground up.  Ask yourself the following questions:

  1. Is your logic clear on the page?
  2. Are your directions concise and intelligible?
  3. Does your screenshot show all pertinent information of the action described?

Assumptions are Fruitless:

Documenting the technical aspects of a project is a careful practice of transferring knowledge in a clear and concise manner. You want to avoid inundating the audience with so much technical jargon that the reader gets lost. Acronyms and technical concepts should be explained briefly when first introduced into the document. Assuming that your audience has the same amount of technical knowledge or experience limits your document to a select few. The goal of any document is to convey information, so make sure that your document is readable and informative for every technical level. A client shouldn’t have to guess at what you are writing about, it should be clear.

Formatting and Navigation:

Sometimes finding a solution within an entire document is like finding a needle in the middle of a hay stack. If you have followed the strategies listed in the previous sections, your document will soon grow past a few brief pages, and as a result, the ability to navigating the document to retrieve information will prove to be a useful. Remember consistency in formatting will allow the document to function efficiently and creates a more streamlined look to your document.

Useful Formatting Tips:

  1. Using consistent headings and subheadings – This provides quick navigation to a document. It creates sections rather than separating by paragraph or page.
  2.  Table of contents – Allows you to quickly access a section with a push of a mouse allows the reader to have a clear lay of the land.
  3. Save file as PDF or “read only” – If you want to limit alterations to your document save the document as this file type.

Also during this point in the creation process, please review documentation guidelines required by your department or client.

Testing and Humanization:

Finally, read through your document and test the steps that you have illustrated as if you were a new user recreating the tasks listed. In my experience, physically going through each step allows for the opportunity to discover which steps need further explanation.

If you can walk through each step with clear understanding and no additional information is needed, then you can then review the document for tone. Even though the document’s goal is to detail a complex technical process, the tone of the document can have personality that is more human. There is no need to write like a robot just because we are talking about networking and terabytes, we want our audience to be comfortable with the information provided to them.

At the end of the day you can see just how crucial documentation is. It prevents numerous questions and most importantly gives all parties a roadmap to what you built. Take pride in creating exceptional documentation that captures the magic and intricacies of your work.