Written Instructions image by https://www.pexels.com/@markus-winkler-1430818/

Document Like You Don’t Know the Subject

(Feature image credit: Markus Winkler)

“All books are just the same letters in a different order”. -Unknown

I know I originally heard this (paraphrased) quote from a comedian.  I thought it was Stephen Wright, though I was unable to find this attributed to any comedian on Google. The closest attribution I could find is to the author Cornelia Funke: https://quotefancy.com/quote/1197597/Cornelia-Funke-Weren-t-all-books-ultimately-related-After-all-the-same-letters-filled.

Point being (my regular reader knows I wander off point often, and hopefully entertainingly so), I think that many people tasked with writing documentation think that all the information is right where they found it, and that anyone else can do the same research and come up with the same understanding. To counter that view, I point you to the news and whatever thing people are doing or saying in large enough numbers to be noticed while the vast majority realize that nothing could be further from the truth.

The thing about documentation, the numbers are generally the opposite, in that only a few understand the need to be specific, explicit, and concise.

The trick that has always worked for me is to write the content, then follow the content as if I had no previous understanding of the topic.

When possible, I prefer to go one better and find someone who really does have no understanding and ask them to follow the content. My greatest success with that method is when I created a 20-page document (with lots of screenshots) that walked developers through the sequence of steps to become productive in working with an enterprise J2EE application with authentication and external system integration. The goal was for new developers to complete the process in under 30 minutes with no assistance. My final test of the documentation was when I gave it to our visual designer who completed the process in 40 minutes with no help other than the document.

At the least, I always try to get at least one consumer of the documentation to go through it and provide feedback. When possible, publish the documentation to a platform that encourages feedback. Even better if peers are allowed to edit and revise on their own.

Finally, when comments are edits are made, it is best if the platform provides an alert mechanism so that the content owner can review the changes or comments.

© Scott S. Nelson

One way to keep documentation fresh

Documentation should always have some built-in capability to receive comments and the comments should generate alerts to the content owners.

This process can vary greatly. In some contexts, readers can be allowed to edit the content. Or only some users. Those edits should still trigger alerts to the content owners for review.

Documentation often becomes stale because there is no easy way to communicate changes. Capturing improvements or updates at the time the document is used is the next best thing from when the content needs revision because what it describes has changed.

Bonus approach

For software documentation (especially for enterprise applications), if you use any kind of ticketing or kanban-style stories, include “Create/Revise Documentation” as a standard part of the Acceptance Criteria in your template.

© Scott S. Nelson

If it is not written down, it does not exist

I can’t find a solid attribution to the title of this post, I only know it isn’t me. But I wish it were. I read it first in a Tom Clancy novel and they were talking about the stock market. I don’t say it nearly enough, and I’m talking about IT documentation.

Say what you want about “self-documenting”. Until that becomes a solid feature of an “AI” product, self-documenting isn’t. If you don’t believe me, find some code or configuration file you wrote 3 years ago and haven’t looked at since and tell me what it does and why. Yes, there will be a small percentage of cases where this will be perfectly clear, and to those few I say “now hand it to someone you have never met and see if they get the same information””. That percentage drops drastically.

Here are some of my thoughts on documentation that I hope will inspire you to create more and help you to make it as useful as possible with the least effort necessary.

Identify Customer-Required Documents at the Start of the Project

Customers often do not look for documentation gaps until near the time when they expect them to be completed. Ask for their specific documentation requirements up front. They may later want to expand that list, and acquiring the list at the beginning and publishing the list for customer review early in the project will allow for better prioritization when the project is nearing the end.

Start Documentation Early

Many initially successful projects can later be viewed as poorly delivered when proper documentation for enhancements and maintenance is incomplete or non-existent. Begin your documentation as early as possible with a full outline and then fill it in the details as time permits. This helps to reduce the project wrap-up stress in starting documentation from scratch at the 11th hours.

Use Technical Deliverable Templates

Templates help to standardize documents for easier reference and provide reminders of sections to include and approaches for presenting specific topics.

Start from a Blank Template

While it is tempting to start from an existing document, this  can result in bad data being left in and verifications of details between designs being properly verified. One example is a project that had scheduled jobs that ended up overlapping because the team kept creating new documents from the existing documents and leaving the schedule table unverified.

Write Instructional Material with the “Eye of the Beginner”

There are few things more frustrating to someone trying to accomplish a specific task according to instructions to get stuck because their current results don’t match the instructions. Who they blame for this is often more of a reflection on their temperament than the instructions, and in IT it is fair to say that most of the time it is the fault of the instruction. Other than true technical writers (there are many in tech writing roles who are really either copywriters or editors and not true technical writers), most people who write documentation do so from the perspective of having already accomplished the task. While being able to do the task can be very useful in writing documentation, knowing how to look at the task through the eyes of someone who does not is the key to being a good technical writer. Follow the steps of your own documentation exactly from the point of view of having never done it before (VMs are great for this), and revise your documentation every time you find a missing step or a concept that is only clear with experience of having already accomplished the step or task. If you have a hard time doing that, have people with no understanding of your subject follow your documentation (without you present!) and provide feedback.

Avoid Unspecified Nouns

Unspecified nouns are words such as this, that, they, and it.  The use of unspecified nouns can be confusing if there is more than one possible interpretation. While you, as the communicator, may only see one meaning for what is referred to by the unspecified noun, a reader or listener may not.

For example, “they may not understand the purpose of the link” is clearer as “stakeholders may not understand the purpose of the link” or “users may not understand the purpose of the link”, both of which may have different meanings.

While it may seem excessive and repetitive to do so, repeat the name of the thing you are talking about rather than assuming that everyone will know what this is meant by that.

Note, this has nothing to do with use of preferred pronouns. I was using they and them for years and wish I had contact information for the teachers and editors who kept insisting I use he and his when referring to an unspecified actor or reader so  I could send them an I-told-you-so emoji.

Validate Guide Documents

The value of a guide is that people should be able to use the guide to complete the tasks it describes without assistance. First validate it yourself by following your document exactly as you have written it. Then have someone that will be a consumer of the document go through and follow the guide, having them make notes with Track Changes turned on. Bonus points for getting someone that has little understanding of the supporting technologies to do the validation.

A Picture Should Be Worth a Thousand Words

Screen shots should be used when they enhance understanding, allowing fewer words to describe the full details. They are not a replacement for all descriptions. At a minimum they should have a caption.

When values need to be entered in a screen shot, always include the values as text so that readers can copy/paste the values. Command line entries should use a style indicating they are commands rather than a screen shot showing the command, again to facilitate copy/paste and also because:

Screen Shot with Text Example

Is not clearer than:

Type this here

Update the Document Reference Links as You Work

Throughout the project you will need to find information online relevant to the solution. In addition to maintaining your own reference bookmarks, whenever you find a URL particularly useful to the solution add it to the Reference Links section of the project documentation. If you do not own the document, send the links to the team member that does for inclusion.

Share Your Knowledge Regularly

Hopefully your employer and/or client have a Knowledge Management system. At a minimum, the following milestones should be a reminder to contribute to this shared knowledge base:

  • Completion of a project
  • Completion of a key deliverable
  • Solving a difficult issue

If you find it difficult to remember to make KM contributions following these events, set a regular reminder (weekly if not daily) to think about your activities and accomplishments and if there is something that is worth sharing, then do so.

© Scott S. Nelson

My Pinned Wiki Post Template

If you use this, please link to this blog post.

This is our Wiki

There are many like it, but this one is ours.

Our wiki is our guide. We support our wiki through comments and additions.

Without updates, our wiki will become outdated. Team members will become frustrated when information is missing or no longer correct. Being a good team member includes being a contributor to the wiki.

That cool reference you found that you will always remember? One day, when you need it most, you will forget it.

That awesome solution to a code or design issue that is perfectly clear and understandable now will look like a foreign language in 2 years (months, weeks, sometimes even hours). Add an explanation to the wiki.

When in doubt if something should be added to the wiki, add it. It can always be deleted later.

This is your wiki. Keep it clean but not too lean.

The Architect
(A serious parody of The Rifleman’s Creed )

(“Obligatory WIki Photo” by cogdogblog is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/?ref=openverse.)

© Scott S. Nelson

Provide Document Feedback for Efficiency

(Featured image “Collaborative documentation editing” by 4nitsirk is licensed under CC BY-SA 2.0.)

When providing document reviews with comments or track changes, most people start writing their comments as they read through. This is perfectly natural and recommended, as capturing your thoughts immediately is the best way to ensure they aren’t forgotten. That said…

As you read through the document, some of your comments made earlier may be addressed later in the document. If you think the content should be moved, this is a good time to point that out, referring back to your earlier comment. If not, take the time to move the comment to the appropriate point, or revise it accordingly.

Short-term memory varies between person to person and even context to context. A comment provide early in the doc is likely to be remembered and reference back when it discovered at the end that it was not necessary if the review is done in a single sitting or as part of a very focused project. Then again, someone stopping by to say “hi” or an IM popping up immediately after writing a comment can pop the memory out of the short term queue and only invoke vague familiarity if the concept is addressed later. Because of this unplanned and unschedulable variation in memory reliability, I suggest re-reading through all comments prior to submitting them. It will (hopefully) catch those forgotten inputs that should be revised in the context of the entire document so that the sent input is concise.

The value of concise input is two fold: It makes it easier for the person receiving the feedback to apply it where needed, and it avoids the frustration of seeing comments from a review that the author knows are not valid because they are addressed later on.

© Scott S. Nelson