Documentation Standards Deliverable Template (generic)

From DocWiki

This Deliverable Template is used to describe a sample of the CIS/SemGov methodology, typically at the task level. More templates are now being added as this DocWiki gets filled out. We welcome you to assist in this effort.

Deliverable templates are illustrative as opposed to fully representative. Please help add examples to this template that are representative of the proposed output.

Contents 1 Overview 2 Example Documentation Standards 2.1 Introduction 2.1.1 Purpose 2.1.2 Scope 2.1.3 Overview 2.2 Documentation Standards Objectives 2.3 Documentation Standards 2.4 Cover Page 2.5 Version Control Box 2.6 Table of Contents 2.7 Table of Figures 2.8 Introduction Section 2.9 Numbering Format 2.10 Headers 2.11 Footers 2.12 Approvals Box 2.13 Summary 3 Example Document Template 3.1 Introduction 3.2 Purpose 3.3 Scope 3.4 References 3.5 Overview 3.5.1 Sample Section 3.6 Sample Subsection 1 3.7 Sample Subsection 2 3.8 Sample Subsection 3 3.8.1 Sample Second-level Subsection 1 3.8.2 Sample Second-level Subsection 2

Overview

Documentation Standards are set for the creation and maintenance of corporate information. Standards can be set up enterprise wide or within a function or department. The scope of documentation standardization should include three important components: first, document creation, processes and templates, and second, document naming conventions and third, document folder structures. All of these components are designed to enable people to find high quality information quickly.

Documentation Standards include:

• Documentation Templates
• Document Naming Conventions
• Shared Drive Configuration and Folder Structures
• Security Groups

Example Documentation Standards

Listed below is an example of documentation standards that can be followed for a project:

Introduction

The Documentation Standards document contains current best practices and requirements for documentation. The information contained in this document applies specifically to the Example environment.

Purpose

The Documentation Standards document is intended to serve as a reference to identify documentation standards for ABC Company.

Scope

The Documentation Standards document describes documentation standards to be used by ABC Company.

Overview

The Documentation Standards document is organized into three major sections.

1. The Introduction section describes the purpose, scope and objectives of this document.

2. The Documentation Standards Objectives section describes reasons for employing documentation standards.

3. The Documentation Standards section describes the documentation standards to be used by ABC Company.

4. The Summary section summarizes the documentation standards described in the Documentation Standards section.

5. Appendix A shows an example document following the documentation standards.

Documentation Standards Objectives

Documentation standards are required to provide a consistent format for reference materials. By employing a common documentation format, readers will save time by not needing to adjust to a different format for each document.

Documentation Standards

Each document must have the following items:

Cover Page

The cover page shall include the following information:

• Organization Name
• Project Title (i.e. "Business Center")
• Document Title (i.e. "Accessibility Standards")
• Document Version (i.e. "Version 1.0")

Version Control Box

The second page of each document shall contain a revision history to track versions. The revision history must contain the following information:

• Date (i.e. "08/11/2004")
• Version (i.e. "1.0")
• Description (i.e. "Document created.")
• Author (i.e. "John Smith")

Each item in the revision history must be changed accordingly as the document is modified. For example, the document version number might change from "1.0" to "1.1" while the author remains the same.

The version number in the document must align with the version number in the version control system. As the version changes within the document, the version must also be updated in the version control system.

Table of Contents

The third page of each document must contain the table of contents.

Table of Figures

After the table of contents, a table of contents listing figures, including graphics and diagrams, and tables. This is to be included only if needed.

Introduction Section

The first section of the document, directly after the table of contents, must be titled "Introduction." The Introduction section must include the following subsections:

• Purpose - state the objectives of the document
• Scope - state the boundaries of the content contained within the document
• References - provide links or references to external documents (This may be omitted if there are no references.)
• Overview - list and summarize each of the sections (not including subsections) of the document

The numbering format of the Introduction section must be as follows:

1. Introduction

1.1 Purpose

1.2 Scope

1.3 References (if needed)

1.4 Overview

Numbering Format

The linear numbering scheme must be used. Here is an example of the numbering scheme to four levels deep:

1. Introduction

1.1 Purpose

1.2 Scope

1.3 References

1.4 Overview

2. Next Section

2.1 Subsection

2.2 Subsection

2.2.1 Third level (Second-level Subsection)

2.2.2 Third level (Second-level Subsection)

2.2.2.1 Fourth level (Third-level Subsection)

2.2.2.2 Fourth level (Third-level Subsection)

2.2.3 Third level (Second-level Subsection)

2.2.4 Third level (Second-level Subsection)

3. Next Section

3.1 Subsection

3.2 Subsection

3.3 Subsection

Headers

A header shall be on all pages from the second page to the last page of the document. The header shall include the following information:

• Project Title (i.e. "Business Center ")
• Document Title (i.e. "Accessibility Standards")
• Document Version (i.e. "Version 1.0")
• Date (i.e. "08/11/2004")
• Document Number (i.e. "AB001")

Footers

A footer shall be included on all pages from the second page to the last page of the document. The header shall include the following information:

• "Confidential" (if needed)
• Organization Name (i.e. " Office of Administration")
• Page Number (i.e. "Page 2")

Approvals Box

If needed, the last page shall contain a sign-off box, which includes the following information:

• Date (i.e. "08/11/2004")
• Version (i.e. "1.0")
• Approver (i.e. "John Smith")
• Approver Title (i.e. "Project Manager")

Sign-offs may occur at each revision level or at the completion of the document.

Summary

Documentation should have the following elements:

• Cover Page
• Version Control Box
• Table of Contents
• Table of Figures
• Introduction Section
• Linear Numbering Format
• Headers
• Footers
• Approvals Box

---

Example Document Template

Revision History

Date	Version	Description	Author
8/11/2004	1.0	Created	Author Name

Table of Contents

Table of Figures

Introduction

Purpose

[The purpose of this document.]

Scope

[A brief description of the scope of this document; what Project(s) it is associated with and anything else that is affected or influenced by this document.]

References

[This subsection provides a complete list of all documents referenced elsewhere in this document. Identify each document by title, report number (if applicable), date, and publishing organization. Specify the sources from which the references can be obtained. This information may be provided by reference to an appendix or to another document.]

Overview

[This subsection describes what the rest of this document contains and explains how the document is organized.]

Sample Section

[This is a sample section to show how the linear numbering is formatted. In addition, this sample section provides subsections with sample figures to populate the Table of Figures.]

Sample Subsection 1

[This is a sample subsection to show how the linear numbering is formatted. In addition, this sample subsection provides sample figures to populate the Table of Figures.]

Figure 2.1 Mathematical equation

Figure 2.2 Two-circle diagram showing intersection

Sample Subsection 2

[This is a sample subsection to show how the linear numbering is formatted. In addition, this sample subsection provides sample figures to populate the Table of Figures.]

Sample Subsection 3

[This is a sample subsection to show how the linear numbering is formatted. In addition, this sample subsection provides a second-level subsection with sample figures to populate the Table of Figures.]

Sample Second-level Subsection 1

[This is a sample second-level subsection to show how the linear numbering is formatted. In addition, this sample second-level subsection provides sample figures to populate the Table of Figures.]

Sample Second-level Subsection 2

[This is a sample second-level subsection to show how the linear numbering is formatted.]