Documenting in Detail: A Policy Perspective

Documenting in Detail: A Policy Perspective

Image Credit: Writing Tools by Pete O'Shea, from Flickr <https://www.flickr.com/photos/peteoshea/5600161625>

At TaskTrain, we’re dedicated to delivering the benefits of detailed documentation. Our focus is on integrating procedural documentation into everyday workflow in order to increase efficiency and eliminate productivity losses from avoidable errors and wasteful rework, but we recognize that standard operating procedures are only one type of essential institutional documentation. Organizations also benefit from clear policy statements and system configuration documentation, as well as many other types, from project charters to work records to strategic plans. Since many of the same best practices apply to more than one kind of documentation, we’re sharing a sample documentation policy applicable to writing policies, procedures, as well as system setup documentation. Why share these best practices in a policy? Because it’s self-describing and self-illustrating, serving as an example of the guidelines it promulgates. Please feel free to adapt and adopt in your organization!

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
  • 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, 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 future articles, we’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.

A version of this article also appears on our founder’s blog.

By |2018-03-06T20:07:10+00:00November 18th, 2015|Uncategorized|0 Comments

Leave A Comment