Writing Tools by Pete O'Shea
So you’re convinced. Maybe it was enduring the latest tirade of a customer or colleague burned by botched work because a coworker didn’t know how to do a job properly. Maybe it was dealing with the fallout from an employee who transgressed a tacit company rule that they didn’t even know existed because, well, it wasn’t actually written down anywhere. Maybe it was hours spent troubleshooting a fault with a company system, half of which was wasted just figuring out how the system was configured in the first place because nobody bothered to document the initial setup. Maybe it was the realization that if you wrote down the steps to that job that only you seem to know how to do, you could stop being the bottleneck, delegate the work, and get on with more important things. Maybe it was just previously reading my pithy proverb, “If it’s not documented, it’s not done“. Whatever the reason, you’ve decided it’s finally time to start doing things right and writing some documentation. But where to start? Documenting can feel like a tedious chore. Extra work. Maybe even overwhelming. Until it’s done. Then it’s liberating!

Just Start

The most important thing is to just start: Open up a new document and start writing the first steps to that onerous procedure the next time you’re doing it. It can be sloppy and incomplete the first time. When you perform the procedure the next time, you can fill in a few more steps. The time after that, you can add in details. The time after that, you can add in exceptions. After that, edit for clarity. After several passes, you’ll be able to hand the documentation off for testing to see if it makes sense to someone else. Then when you know it’s understandable, you can easily delegate the whole process because it’s clearly documented.Documenting as you go may add a few minutes to each execution of the procedure, but that time can be returned many times over through delegation and eliminated rework. Who knows, you may find the process of documenting a procedure reveals hidden efficiencies to be exploited in eliminating or combining steps.

Having something written down and shared is the most important thing. Format, style, presentation, and everything else are secondary considerations. If you’re like me, though, you want to have more of a plan in place, a clear end goal to strive for, even if it takes a while to get there. Granted, given the things that I am interested in writing about, it is unlikely that you are like me, but for the sake of the remainder of this article, let’s assume that you’re looking for a little more guidance than “just do it”.

A Policy Policy

To that end, I’ve gathered best practices I’ve learned over the years and compiled them into the following example policy on, well, writing policies! Actually, the policy is a bit broader than that. Since so many of its guidelines apply equally to other types of organizational documentation, this sample policy covers writing policies, procedures, as well as system setup documentation. Just consider those additional inclusions free bonuses.

Why a policy? I chose this form because it’s self-describing and self-illustrating, serving as an example of the guidelines it promulgates.

Next time, the Procedure Procedure!

Documentation Policy

Description

This policy establishes the types of documentation that must be maintained and sets forth guidelines for the production of such documentation.

Context

Rationale

In promulgating consistent, best practices standards for the creation and distribution of organizational documentation, this policy aims to increase organizational efficiency and effectiveness and enable the pursuit of high standards of quality by improving employee communication and coordination, increasing productivity through process improvement and reduction in organizational bottlenecks, and reducing productivity losses (as well as employee and customer frustration) due to avoidable error and associated rework.

Related

  • Electronic Document Filing System Policy
  • Style Guide

Audience

All employees of {Organization Name}

Definitions

None.

Policy

All (1) established policies, (2) important reoccurring processes & related procedures, (3) important system installation & configuration parameters, shall be documented and maintained by the respective organizational owner and promptly published to all relevant stakeholders under the terms outlined in this policy.

Documentation Types

Policies

Structure

Regardless of precise format, policies should contain the following:

  • Title: A concise, descriptive name ending with the word “Policy”.
  • Description: A concise summary of the contents.
  • Context: A section containing the following two subsections identifying the context answering the “why” for the policy.
    • Rationale: A concise statement of the motivation for adopting the policy.
    • Related: Links to documents containing related (1) statements of guiding values and principles, (2) parent or sibling policies.
  • Audience: The stakeholders to whom the policy applies.
  • Definitions: Definitions of important words or concepts used in the policy.
  • Policy: Statement of rules or guidelines to be followed, divided into sections as appropriate, outline numbered when appropriate.
  • Resources: Bullet list of links to useful related background material.
  • Control: See the Shared Document Control section.
Format(s)

Recommended format(s):

  • Policy template

Procedures

Structure

Regardless of precise format, procedures should contain the following:

  • Title: A concise, present-tense action verb phrase naming the procedure.
    • Examples:
      • Onboard New Employee,
      • Conduct Employee Exit Interview.
  • Description: A concise summary of the contents.
  • Context: A section containing the following two subsections identifying the context answering the “why” for the procedure.
    • Rationale: A concise statement of the motivation for executing the procedure.
    • Related: Links to documents containing related
      • strategic objectives,
      • project charters,
      • Policies,
      • parent or sibling procedures.
  • Audience: A list of the role(s) or position(s) responsible for executing the procedure.
  • Definitions: Definitions of important words or concepts used in the procedure.
  • Procedure: Step-by-step instructions for completing the procedure, divided into sections as appropriate for ease, produced according to the constraints laid out in the Style Guide section if written.
  • Resources: Bullet list of links to related background material useful to executing the procedure, including internal documents or Internet sites.
  • Control: See the Document Control section.
Format(s)

Recommended format(s) should be appropriate to the procedure and audience, but may include:

  • Step-By-Step Outline,
  • Step-By-Step Table,
  • Checklist,
  • Slide deck,
  • Flowchart,
  • Screencast,
  • Video tutorial.

System Configurations

Structure

Regardless of precise format, system configurations should contain the following:

  • Title: Descriptive title for document including system name (Manufacturer/Publisher/Service Provider + Hardware Model/Software Title/Service Name) + specific setup steps described.
  • Description: A concise summary of the contents.
  • Context: A section containing the following two subsections identifying the context answering the “why” for the policy.
    • Rationale: A concise description of the purpose of the system, its primary users, the particular topic of the documentation, any major “gotchas”.
    • Related: Links to documents containing related
      • configuration documentation,
      • policies,
      • procedures.
  • Audience: The role(s) or position(s) responsible for maintaining the system.
  • Definitions: Definitions of important words or concepts used in the procedure.
  • Configuration: Step-by-step instructions outlining the actions taken (setup) to install/configure the system.
  • Resources: Bullet list of links to related background material useful to the configuration information, including internal documents and manufacturer/publisher/provider information.
  • Control: See the Document Control section.
Format(s)

Recommended format should be selected as appropriate to the contents, but may include:

  • Manufacturer/Publisher/Provider manuals/materials,
  • Step-By-Step Outline,
  • Step-By-Step Table,
  • Slide deck,
  • Diagram,
  • Screen capture,
  • Setup video.

Document Control Section

All documentation should have a Control section with the following content.

Responsibility

A responsibility matrix recording responsibility for writing, reviewing, approving, and receiving the documentation serving as the basis for assigning access permissions and notifying stakeholders of changes, coded as follows:

  • (R)esponsible: The one position charged with creating and maintaining the documentation, which should typically be the position responsible for enforcing the policy, executing the procedure, or maintaining the system, as appropriate.
  • (A)pprove: Zero or more positions charged with approving changes to the documentation, which should be those immediately accountable for the policy, procedure, or system configuration, as appropriate.
  • (C)onsult: Zero or more positions from whom input must be solicited during drafting.
  • (I)nform: Zero or more positions who should have access to the documentation and be informed of all updates.

Revisions

A table with the following contents documenting revisions to the documentation and, if required, approvals for those revisions.

  • Date Revised: The completion date of the current revision.
  • Author: Name(s) of those person(s) who wrote the current draft, in Last name, First order, separated by semicolons.
  • Description: Optional concise narrative of changes made in the current revision.
  • Approver(s): For documents requiring change approval, the name(s) of the person(s) approving the revision in Last name, First order. For non change-controlled documents, “Not Applicable”.
  • Date Approved: Date the draft was approved, if applicable, otherwise, “Not Applicable”.
  • Date Next Review: Date the document should be reviewed by the Responsible position for updates or sunset.

Document Distribution

The position responsible for the documentation must promptly distribute new, modified, or revoked policies to all stakeholders to whom the policy applies, as recorded in the Control section of the document structure. Documentation should be stored per the Shared Filing System Policy.

Documentation Style Guide

General Writing

  • Write for clarity & readability, employing accepted grammar & spelling.
  • Unless otherwise noted in this document, follow the { organizational style guide | Chicago Manual of Style | APA }
  • Dates: Use the ISO 8601 YYYY-MM-DD format when specifying dates in order to enable chronological document sorting and to avoid confusion between American and European date orders.
  • Time: Use 24-hour time notation with time zone reference when specifying times to enable chronological document sorting and avoid confusion.

Procedure Writing

  • Write procedures with enough context and specificity to allow an individual with the qualifications for the position but no prior experience with the procedure in question to be able to complete the procedure unaided.
  • Exclude all sensitive information such as passwords, substituting an appropriate descriptive placeholder and/or instructions for securely looking up the sensitive information.
  • Break long procedures down into logical sections, naming each section descriptively.
  • Outline indent as appropriate to visually show hierarchical relationship of substeps to steps, identifying sequential action steps using legal numbering.
  • Indent step explanations/clarifications to using bullets as appropriate.
  • Keep step descriptions concise to promote readability.
  • Describe each step on same outline level at the same logical level of activity.
  • Describe steps starting with a present-tense action verb phrase identifying the action to be performed, providing any useful context/explanation/clarifications in closing clauses or indented bullet points.
  • Embed screen shots, tables, diagrams, screen captures, and videos for added clarity.
  • Use ampersands to conserve space in step descriptions.

Typographic Conventions

General
  • Bold: Section headings
  • Italics: emphasis within a paragraph, especially when introducing new words.
Graphical User Interface (GUI) Formatting

When specifying components of graphic user interfaces in written descriptions, employ the following typographic conventions to promote clarity:

  • Button/Hyperlink: Boldface & underline pressable GUI element, such as a button or hyperlink.
  • Menu: Boldface the name of any pull-down or pop-up menu or menu item, separating items in hierarchical menu with the greater than (>) character.
  • Filename: Underline the (path) name of any file, folder, or URL.
  • “Prompt”: Place in double quotes any computer prompt, including dialog box or window text
  • User Input: Italicize any text the user should enter.
  • Other Element: Boldface and italicize the name of any other GUI element referenced, such as tab control, accordion, etc.

Resources

Control

Responsibility

Position / Organizational Unit
Responsible
Approve
Consult
Inform

Revisions

Date Revised Author(s) Date Approved Approver(s) Date Next Review

A Procedure Procedure

If that policy statement seems too onerous or abstract to be helpful, fear not. In the next article, I’ll continue the “Documenting in Detail” theme but take it down to a more practical level by presenting a procedure for writing procedures, which will also fill in some missing links in the Documentation Policy by furnishing a few documentation format templates.

How would you improve this sample documentation policy?
Tag TaskTrain on LinkedIn, Facebook, Instagram, or Twitter to let us know!

Sign Up
  for our TaskTrain Dispatch newsletter to get notified when our next article goes live.

Recent Posts