Managed Services

Software Documentation

Process and Standards An overview

This document is the property of Emerio GlobeSoft Pte Ltd. Its content is confidential. Reproduction of the material contained herein, in part or full in any form by anyone, without the written permission of Emerio GlobeSoft Pte Ltd. is prohibited Product names used are for identification purposes only. All trademarks and registered trademarks are the property of their respective owners.

Emerio GlobeSoft Pte. Ltd.

Emerio House, 50 Ubi Crescent #01-05 Ubi Tech Park Singapore 408568 Tel: (+65) 6349 2999 Fax: (+65) 6349 2966 http://www.emeriocorp.com Company & GST Registration No: 199706876W Confidential, Copyright 2012 Emerio Singapore

Confidential

Managed Services

Table of Contents
1 Software Documentation An Overview 1.1 1.2 2 Document Purpose Document Scope 3 3 3 4 4 4 7 7 9 11 11 11 15 15 16 18 18 18 19 19 19 19

Introduction 2.1 2.2 Process Document Product Document

Documentation 3.1 3.2 Document Development Life Cycle (DDLC) Document Structure

3.2.1 Document Process 3.3 Document Format and writing style

3.3.1 Document Components 3.4 3.5 3.6 4 Documentation Standards Publish Customer feedback form Publish Handover document

Product Documentation 4.1 Classifications of Product Documentation

4.1.1 Requirements document 4.1.2 Architecture/Design document 4.1.3 Technical document 4.1.4 End User document 4.1.5 Marketing document

Confidential

Managed Services

1 Software Documentation An Overview

1.1 Document Purpose
All software projects require documentation and a proportion of software process costs is incurred in producing the documentation. Documentation errors and omissions can lead to errors by end-users which may disrupt the system and add up to the associated costs. Hence documentation acts as a system information repository for all user roles. The purpose of this document is to explain the various facets of software documentation, what are the important areas that need to be documented for a formal release of a software application, the topics that go into each document, how is it structured to create a professional level document.

1.2 Document Scope

This document is divided into the following sections: Section 1: Introduction This section gives an overview of the classifications in software documentation Section 2: Documentation This section gives details on DDLC, document structure, document process, format and related information on documentation Section 3: Product Documentation This section explains product documentation in detail.

Confidential

Managed Services

2 Introduction
Software documentation can be broadly classified into the following two types:

2.1 Process Document

These documents record the process of development and maintenance. This document is created for successful management of a software product. Following are the categories of process documents: a) Plans, estimates and schedules These are documents produced by the managers which are used to predict and control the software process b) Reports: These documents report how resources were used during the process of development c) Standards: These documents set out how the process is to be implemented. Should it be developed from a organizational/national/international perspective? d) Working Papers: Technical communication documents in a project. It includes interim versions of the product documentation, describe implementation strategies and set out the identified problems. The rationale for design decisions is recorded here. e) Memos, mail messages: These documents record the details of everyday communication between the managers and development engineers.

2.2 Product Document

This document evolves with the development of the software product. There are two main categories of product document: System Documentation and User Documentation 1. System Documentation: Describes how the system works but not how to operate it. The following documents fall under the purview of System Documentation. Requirements Spec Architectural Design Detailed Design Commented Source Code (Including output such as Java Doc) Test Plans (Including Test Cases) Bug list

Confidential

Managed Services

2. User Documentation: There are two main types: End User Document and System Administrator Document. End users use the software to assist some tasks. For example; they will be interested to know as to how the software can help them. System Administrators are responsible for managing the software used by end-users. For example; a network manager. The system installation document is intended for system administrators.

Types and functions of documentation User documentation 1. System overview 2. Installation guide 3. Beginner's guide / tutorial 4. Reference guide Provides general description of system functions Describes how to set up the system, customize it to local needs, and configure it to particular hardware and other software systems Provides simple explanations of how to start using the system Provides in-depth description of each system facility and how it can be used

5. Enhancement booklet / Contains a summary of new features release notes 6. Quick reference card 7. System administration System documentation 1. System rationale Describes the objectives of the entire system Serves as a factual lookup Provides information on services such as networking, security, and upgrading

2. Requirements Provides information on the exact requirements for the system as agreed analysis / specification between the stakeholders (user, client, customer, developer). 3. Specification / design 4. Implementation 5. System test plan
Confidential

Provides description: (i) of how the system requirements are implemented (ii) of how the system is decomposed into a set of interacting program units (iii) the function of each program unit Provide description of: (i) how the detailed system is expressed in some formal programming language (ii) program actions in the form of intraprogram comments Provides a description of how program units are tested individually and how the whole system is tested after integration
5

Managed Services

6. Acceptance test plan Describes the tests the system must pass before the users accept it 7. Data dictionaries Contains descriptions of all terms that relate to the software system in question

Requirement Specification: This document portrays and describes what the customer has asked for in a form of technical document to actually define what the product will do. Functional Specification: It is the document giving a good volume of information about the functioning of the product. This document is for the customer before any development starts. Design Specification: This document is written after the client has approved the Functional Specification. It gives images and the look and feel, the color scheme, fonts etc about the product in form of document.

Confidential

Managed Services

3 Documentation
3.1 Document Development Life Cycle (DDLC)
The DDLC has the following main phases like the SDLC: Project Start-up - This phase involves defining the scope of the project along with the standards to be followed throughout the project. It also includes identifying key personnel responsible for providing, reviewing, and approving document content. Define roll in requirements, understand specifications and design Plan Establish the documentation requirements for a project, prepare cost estimates, scope the document with appropriate details, understand the relationship to other projects, allocate resources (hardware and people), timelines and arrive at a project plan Develop Gather information, write, capture graphics, terminology, check for correct terms for UI labels, check messages, integrate help topics with code Review check for technical accuracy of the content and adhere to the style guide or standards and guidelines Package Prepare the final output in the required format as identified in the Define stage Maintain Update the documentation based on software upgrades

Confidential

Managed Services

Project Start-up Define Requirements

Plan contents, resources and work plans

Develop - Gather information, capture graphics

Review review and validate content

Content Okay

No

Yes

Publish Documentation

Maintain Update and maintain

Confidential

Managed Services

3.2 Document Structure

The document structure has a major impact on readability and usability. It is the way in which the material in the document is organized into chapters, sections, sub-sections etc. Document structures should be designed in such a way that the different parts are as independent which allows each part to be read as a single item and reduces problems of cross-referencing when changes are made. Following are the suggested components to be used in a software user document Component Identification Data Table of Contents List of Illustrations Introduction Using the documentation Procedures Software comments Error messages and problem resolution Glossary References Index Description Title and identifier that uniquely identifies the document Chapter/section numbers names and page

Figure numbers and titles Purpose of the document and a brief summary of the contents Suggests how to use the documentation effectively How to use the software to complete the tasks that it is designed to support Description of each of the commands supporting the software Description of errors and how to recover from these errors Definitions of specialized terms used References or links to other supporting documents A list of key terms and the pages where these are referenced

a. Cover Page on all documents - All documents should include a cover page which identifies the project, the document, author, date of production, type of
Confidential 9

Managed Services

document, intended recipients of the document, key words for retrieving the document and a copyright notice.

Software Documentation
Setting Standards Title: Project: Setting Standards SD/01/2011

Document Identifier: SD/WD/2011 Document type: Process Document Version: 0.1 Author: Inspected: Distribution: Internal Confidentiality: Internal Process Date: 8 November 2011 AXXXXX Approved:

Keywords: standards, document process This document is the property of XXX Ltd. Its content is confidential.
Confidential, Copyright 2012 XXXX

Sample Cover Page b. Divide Documents into sections and sub-sections Long documents should be divided into chapters, and each chapter should be structured into sections and sub-sections. c. Contents page Include a contents page that lists these chapters, sections and sub-sections. d. Numbering Scheme: A consistent numbering scheme for chapters, sections and sub-sections should be defined
Confidential 10

Managed Services

e. Warnings, cautions and note should be displayed in a consistent format that is easily distinguishable from ordinary text or instructional steps. f. Documentation formats for user entered commands shall be different from the variables selected by the user g. Index - Add an index if there is lot of detailed, reference information. A comprehensive index helps to find information easily. h. Glossary If a document is intended for a wide spectrum of readers with different levels of vocabularies, a glossary should be added to define the technical terms and acronyms used in the document.

3.2.1 Document Process

Drafting, checking, revising and re-drafting is an iterative process which should be continued until a document of acceptable quality is produced. The quality level will depend on the document type and the readers of the document.
Document Process
Draft

Peer Reviews

Revise

Check

3.3 Document Format and writing style

3.3.1 Document Components

3.3.1.1

Writing Content Defining the Audience Information Design

Writing Content:-

The GRAPE approach and The Style guide are the two key aspects while writing content.
3.3.1.1.1
Confidential

Defining the GRAPE approach:

11

Managed Services

G Grammatically correct sentences R Readable A Accurate P Presentable E - Editable

3.3.1.1.1.1 Titles and subtitles:

Use Gerunds for example, Creating a user account

3.3.1.1.1.2 Spacing:

One space after any punctuation No spaces on either side of the hyphen(for compound nouns) Leave a single space after a period

3.3.1.1.1.3 Parentheses:

Use a period in parentheses for complete sentences only. For example, Enter your password (This is created by your administrator). Use parentheses when you introduce an acronym; for example, MS (Managed Services) division.

3.3.1.1.1.4 Writing numbers:

Spell out numbers one through ten; Indicate digits if greater than ten. For example; this manual has three chapters and 13 appendices. Fractions must be spelt with hyphens. For example; one-third Hyphenate numbers greater than 20 and less than 100. For example; Twentyseven Spell the number if at the start of the sentence. For example; Thirty-five participants participated in the event

3.3.1.1.1.5 Voice

Use the Active voice when providing the user with instructions. Use the Passive voice when describing a feature or a concept.

For example; Active Voice: You need to enter a valid password to sign in to the application. Passive Voice: The invoice number will be auto generated by the system
3.3.1.1.1.6 Presentation:

Presentation includes the following:

Confidential 12

Managed Services

Page Setup Applying styles Formatting text and paragraphs Applying tabs Using tables Graphics and workflows Tables
Style Guide

3.3.1.1.2

A style guide defines quality standards for writing, ensures consistency and acts as a base for quality checks. It provides guidelines for: Defining the audience Designing and analyzing information Planning the content of the document Defining and using the appropriate terms Writing for a specific audience (non-native readers, global language) Writing content for specific sections of the document (indexes, references)

3.3.1.1.2.1 Styles

A style is a predefined set of formatting rules with a given name. Styles are applied for consistency, for better readability and for quick and effective editing. Styles used should be listed. Create a template if necessary. Always use styles as defined in the template or create a new one if required and add it to the quick list
3.3.1.1.2.2 Applying Styles to Paragraphs

Styles are applied to paragraphs. A paragraph should not exceed seven sentences or seven chunks of information. Never insert a blank line always use space before and after paragraph formatting
3.3.1.1.2.3 Multilevel numbering for Headings

Set the multilevel numbering for all the headings and apply the numbering to all headings in the document. This will help the user to navigate easily between topics and sub-topics.
3.3.1.1.2.4 Default Style Name

The default style name applied to text when you create a new file is Normal.
Confidential 13

Managed Services

3.3.1.1.2.5 Itemize facts:

It is usually clearer to present facts in a list rather than a sentence. Use textual highlighting (italics or underlining) for emphasis.
3.3.1.1.2.6 Graphics

Basic rules when working with graphics:

3.3.1.2

Capture with valid data Capture the screen in context Describe the captured screen Label the captured screen Pictures or screen shots should never be float over text
Defining the audience

The audience includes users who will use the documentation to understand information, complete a task and help customers complete their task. Documentation is based on user roles. Following are some of the user roles:
3.3.1.3

End users who enter data Administrators who set up user accounts Consultants who install the software Developers Testers Managers Team members
Information Design

Information design is structuring the information to enable the user access and interpret information when required. Basic rules of Information Design What is the subject/context? Who, why, when and how will the content be used? Structuring content Terminology
Grouping the information

3.3.1.3.1

Information is grouped into two categories:

Confidential 14

Managed Services

i. ii.

General documents This includes Minutes of the meeting, status reports of tasks planned/completed, achievements, escalations etc Product/Process/solution documents This includes user manuals, installation manuals, Process manuals, product related documents.
Key reasons why product documentation is used:

3.3.1.3.2

To understand specifications and design To get an introduction to the product/solution To understand conceptual information For example, Features and System Landscapes To understand pre-requisites To install, set up or configure the product To understand dependencies on other systems To start or complete tasks

3.4 Documentation Standards

Documentation standards act as a basis for document quality assurance. Documents produced according to appropriate standards have a consistence appearance, structure and quality. The document structure standards should specify the conventions used for page numbering, page header and footer, section and sub-section numbering. Document presentation standards define a house style for documents and contribute to document consistency. They include the definition of fonts and styles used in the document, use of logos and company names, use of color to highlight document structure etc. Document standards should apply to all project documents and to the initial drafts of user documentation.

3.5 Publish Customer feedback form

This feedback form is with reference to User Documentation (User Manuals and online help). Please check the appropriate box related to the question Reference Document: Product Name & Version: Date:

Confidential

15

Managed Services

Please check the appropriate box corresponding to the question Yes Was the structure and organization of the content clear? Did you find sufficient navigation points to guide you? Did you find any inconsistencies in conventions used? Was the text enough and up-to-date? Was the text cross-referenced across the document and other manuals? (if any) Was the indexing appropriate to locate information easily? Did the glossary contain concise definitions? Did the document address all levels of users? No

Additional comments section: (Use this section to add more comments or comments relating to the above questions)

Reviewer Details: Name: Company: Phone: Email:

3.6 Publish Handover document

This document describes the handover of all the relevant details of a documentation project. The document details the responsibilities during the project

Confidential

16

Managed Services

Confidential

17

Managed Services

4 Product Documentation
4.1 Classifications of Product Documentation
The product documentation which includes system documentation and user documentation can be divided into five major types. The system documentation includes the following components: The requirements document A document describing the system architecture A description of the architecture of each program For each component in the system, a description of its functionality and interfaces Program source code listings with appropriate comments to explain complex sections of code and provide a rationale for the coding method used. Validation documents to describe how each program is validated and how it relates to the requirements System maintenance guide which describes known problems with the system, which parts of the system are hardware and software dependent

User document includes the following components: Functional Description to give a description of the services provided Installation Document gives information on how to install the system Introductory Manual to help the user to get started with the system Reference Manual details all system facilities System Administrators Guide describes how to operate and maintain the system

4.1.1 Requirements document

This document specifies what the software can do or does. To be precise, this document is the foundation for what shall be or has been implemented. The requirement includes the following: i. ii. Business Requirements It contains what the system must do and contains the actual requirements, the stakeholder list, estimated cost, resources, team roles and so on. Functional Requirements How the system must accomplish the requirements. The details have to be explained in physical terms. For example, the UI layout and requirements need to be given to the development team.
18

Confidential

Managed Services

iii.

System Requirements This includes the Software characteristics and requirements, hardware characteristics and requirements, user requirements, input-output requirements, communication requirements, usability requirements etc

4.1.2 Architecture/Design document

This document gives an overview of the software and proceeds to include relations to an environment and construction principles to be used in design of software components.

4.1.3 Technical document

This document includes documentation of code, algorithms, interfaces and APIs

4.1.4 End User document

Manuals for the end-user, system administrators and support staff are included in the end-user documentation.

4.1.5 Marketing document

This document includes the technical brochures, marketing document (analysis of the market demand) and web content.

Confidential

19