Documentation 101: Writing Documentation That Anyone Can Use

It is time for that dreaded topic: documentation. Everyone needs it at some point, but most people hate creating it.

Often, it’s because they lack the time, tools, references, or knowledge to do it properly. So, let’s have a chat about the different documentation types and formats, the different ways to create it, and the process that goes into creating good, usable documentation.

Documentation types

There are many types of documentation that we use in our daily lives. There are tutorials for learning how things are done, how-to guides that help solve problems, technical references that document a completed process, and reference guides that basically act as a type of cheat sheet.

Below is a quick cheat chart of the different documentation types:

All these types of documentation are used in every type of business today, but for the sake of not losing everyone to a long-winded book, I am going to discuss these in general terms instead of a focused business-by-business case.

Tutorials & How-To Guides

These are very similar, but also very different. As I stated above, tutorials are used for learning how things are done, whereas a how-to guide is for solving a problem. In my world, I may use a tutorial to learn how to code out the latest email layout. Then, I would use a how-to guide to build the email program to send out the email created from the tutorial.

Both types of documentation are simple, step-by-step walk-throughs that will take someone from the very beginning (e.g., starting the software, logging in, etc.) to the very end of a process. Each one should include screenshots or examples of the steps and processes. You’ll typically find tutorials and how-to guides in document or video format (or a combination of the two).

Technical Specs & Reference Guides

These are also very similar in function, but have different applications. Both types go into much greater detail than a tutorial or how-to guide; however, technical specs (also referred to as technical references) list out all the details of a project in a line-by-line fashion, whereas reference guides are more like a cheat sheet document — think Brand Guidelines, tip guides, or even Notes.

Documentation formats

There are three basic formats, or styles, for documentation: ISO, Video, and Step-by-Step. All three have their challenges, applications, and champions. Personally, I prefer step-by-step documentation. That’s because I don’t want any room for ambiguity. (I also absolutely hate being in front of a camera.) I want users of my documentation to be able to pick it up and follow it to the end, successfully, without ever having done the process or accessing the system/software before. I’ve found that step-by-step documentation is the surest way to achieve that goal.

ISO Documentation

ISO documentation lends itself well to technical references with paragraph style discussion accompanied by charts, tables, and graphs. It is widely used in industries where their documentation must be certified in order to meet stringent ISO standards. If you would like to dig into the world of ISO, check out ISO.org.

I personally do not care for ISO documentation. I have often found it vague, open for interpretation, and, in some cases, overwhelming. Now, don’t get me wrong. This could just be my experience. It’s possible that not all ISO documentation is written in such an ambiguous style. The people who put together the ISO documentation I’ve come across may not have known how to write documentation in the first place. We have all been there.

Video Documentation

Again, I do not like being in front of a camera, so this is not my cup of tea. That said, video documentation is a great resource for visual learners. Users can start, stop, follow along with, and pause a video, as needed, while watching a process occur. However, there are some downsides to video documentation:

• Users must take their own notes and be able to read those notes later (or keep referring back to the video).
• Users must have an electronic device to even watch the documentation (no power, no video — hope the video topic isn’t about turning the power back on!).
• If that video is in the cloud or online, ample bandwidth is required for viewing.

Need information on software or want to learn more on creating video documentation? Google “video documentation” and dive in.

Example: How to Document a Process With Video

Step-by-Step Documentation

This one is my forte. I love this type of documentation as it leaves nothing up for discussion. It literally tells a user what to do, how to do it, and when to do it. (And isn’t that the point?)

Step-by-step documentation is a mix of paragraphs and outline format with screenshots and examples mixed in. It is also the most flexible type of documentation with regard to format. It can be created as slides in PowerPoint, video, basic documents (Word, Excel, etc.), or even a combination thereof. Not to mention that both visual and textual learners at all levels of experience (from beginner to expert) can learn and work from step-by-step documentation.

Example: This step-by-step documentation takes users
through the process of creating a new logo in Adobe Photoshop.

How to approach writing documentation

While I cannot speak to the ISO and Video documentation formats specifically, the steps I am going to review here should generally pertain to all formats.

To start, you’ll need:

• Your topic
• Your tools (blank document or document template, screen capture software, etc.) open and ready
• Any reference materials that may exist (intake doc, etc.)

Include the following:

• Access information (login/password if shared, URLs, etc.)
• Brief paragraph on the process
• Numbered steps with sub numbers (general outline format)
• Fine details (screen/tab names, specific details, etc.)
• Screenshots and relevant examples within the steps
• Small steps that you believe others should already know (remember, you are writing documentation so that ANYONE can pick it up and perform the process)

The easiest approach

The best and easiest way to write documentation, of any kind, is if you already know the process. In this case, you can document the process while actually going through it for a project. It may take a bit longer to do the actual project, but it makes writing the documentation and collecting the screenshots much easier. It also assures that all steps are included, few items are missed, and everything is in the correct order.

A more difficult, but not impossible approach

Eventually, you will be asked to document a process that you have never done before and may only vaguely understand. This can be done, but will be a bit more difficult and will take more work. In this case, start as you would for the easy way — but don’t worry about order or completeness. Go into this knowing and understanding that this will have many revisions and not be a quick process.

1. Document the steps you know. Fill in the information that is known by doing a brain/skill dump.
2. Attempt the process with the information you have. This will allow you to start seeing an order to the information you have and any holes that may exist in the information.
   1. Take notes during this step and include anything that may need to be moved or updated.
   2. Make a note of any questions you have and if there are potential steps missing.
3. Merge your notes into the documentation and make any changes you discovered.
4. Ask questions and/or research similar processes by others.
5. Merge the new information into your documentation.
6. Repeat steps 2-6 until you have functional documentation that anyone can use.
7. Have someone perform the process with the documentation to identify any holes/gaps.

5 quick tips for writing effective documentation

1. Do NOT go into a documentation project thinking it will be done in a few hours. Good documentation takes time and revisions.
2. Write your documentation as if the CEO may need to perform the process.
3. Include a “Changes” page at the top of the doc, directly after the index, that includes the date of the change and the information for the update. This way, if you don’t have time to implement the updates within your documentation, at a minimum the changes:
   • Are listed for others to know about
   • Won’t get lost or forgotten
   • Can be added in later
4. If you find yourself rushing to complete a documentation project, set it aside and take a break or come back to it the next day. Rushing will introduce missed or inaccurate steps, which, depending on what the process is for, could cost a company a lot of time and money.
5. MANAGERS: Give your staff the time needed — not the time you think it should take — to produce the quality documentation you are expecting. If you don’t, your customer service team will hear about it.

Some final thoughts

Remember, documentation is neither a quick nor easy process. It takes work, time, patience, and often many revisions. Documentation is also NOT a do it once and done thing. You should always strive to keep your documentation up to date and accurate, so invest the time and energy into writing good documentation that anyone can use.

In the end, remember…

may help you, but

is the real goal of documentation.

Good luck and keep practicing those documentation skills!

Lori Mann is an expert in web and email design and deployment. As an Implementation Architect, she uses her advanced knowledge of HTML, XHTML, CSS, PHP, and MySQL to build and deploy emails, landing pages, forms/SmartForms, and microsites in requesters’ Eloqua and Marketo systems. Lori also helps requesters make the most of their marketing programs through sophisticated email template development, script authoring for automated form input, and rigorous quality assurance testing.

The post Documentation 101: Writing Documentation That Anyone Can Use appeared first on DemandGen.