Loading...
 

General documentation writing concepts, including structure, mechanics and language.

Structure

  • Descriptive Title – The title should be descriptive and include common search terms based on the subject of the document.
  • Introduction – A summary of the procedure, including context of the procedure, a high level purpose of the process and the technology involved.
  • Prerequisites – What needs to be in place before starting the procedure? What is needed to allow the procedure to be completed without disrupting the flow of the procedure?
  • Procedure – Document all steps needed to complete the procedure.

Mechanics

Mechanics can help with the readers’ understanding of the document.

  • Screenshots – Screens provide visual ques and context for steps of the process. Use tight screenshots, only including the part of the screen that is focus of the step or process. Do not capture the whole screen.
  • Related Assets – If a step or process is related to another asset (document, configuration, password, user, etc.) include a link to that other asset. This provides both context to the process and allows for quick access to the other asset. Relationships are bi-directional, meaning that a user can move between assets, from a process to a configuration, or from a configuration to a related process. For example, Creating an Active Directory User, linking the steps of the process to an organization AD server, provides information on where to create the user, and when viewing a server knowledge of what services / functions that server provides.
  • Bold Text – Use Bold Text to form onscreen buttons or text to help differentiate them from the rest of the text in a given step or procedure. This allows for text to be skimmed, and a user can quickly find links, text, or buttons that are needed for a process.
  • Italicized Text – Use Italicized Text for examples to also help differentiate them from the rest of the text.

Language

  • Audience – Who will be reading the document? Knowing your audience will help determine if and what jargon, acronyms or slang can / should be used.
  • Assumptions – Document assumptions should be added to the Prerequisites section of the document.
  • Brief – Keeps the steps short, clear and precise.
  • Avoid Time-Sensitive Information – Use job roles instead of an individual’s name, for example.

Reference