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 © 2023 Emerio Singapore

Confidential

Managed Services

Table of Contents

1 Software Documentation – An Overview 2

1.1 Document Purpose 2

1.2 Document Scope 2

2 Introduction 4

2.1 Process Document 4

2.2 Product Document 4

3 Documentation 6

3.1 Document Development Life Cycle (DDLC) 6

3.2 Document Structure 8

3.2.1 Document Process 9

3.3 Document Format and writing style 10

3.3.1 Document Components 10

3.4 Documentation Standards 13

3.5 Publish – Customer feedback form 14

3.6 Publish – Handover document 15

4 Product Documentation 16

4.1 Classifications of Product Documentation 16

4.1.1 Requirements document 16

4.1.2 Architecture/Design document 17

4.1.3 Technical document 17

4.1.4 End User document 17

4.1.5 Marketing document 17

Confidential 2

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 3

Managed Services

2 Introduction

Confidential 4

Managed Services

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

2.1Process 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 5

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 Provides general description of system functions

2. Installation guideDescribes how to set up the system, customize it to local needs, and configure it to particular hardware and other software systems

3. Beginner's guide / tutorial

Provides simple explanations of how to start using the system

4. Reference guideProvides in-depth description of each system facility and how it can be used

5. Enhancement booklet / release notes

Contains a summary of new features

6. Quick reference card Serves as a factual lookup

7. System administrationProvides information on services such as networking, security, and upgrading

System documentation

1. System rationale Describes the objectives of the entire system

2. Requirements analysis / specification

Provides information on the exact requirements for the system as agreed between the stakeholders (user, client, customer, developer).

3. Specification / designProvides 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

4. ImplementationProvide description of: (i) how the detailed system is expressed in some formal programming language (ii) program actions in the form of intra-program comments

5. System test planProvides a description of how program units are tested individually and how the whole system is tested after integration

6. Acceptance test plan Describes the tests the system must pass before the users accept it

Confidential 6

Managed Services

7. Data dictionariesContains 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 7

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 8

Managed Services

Confidential 9

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 Description

Identification Data Title and identifier that uniquely identifies the document

Table of Contents Chapter/section names and page numbers

List of Illustrations Figure numbers and titles

Introduction Purpose of the document and a brief summary of the contents

Using the documentation Suggests how to use the documentation effectively

Procedures How to use the software to complete the tasks that it is designed to support

Software comments Description of each of the commands supporting the software

Error messages and problem resolution Description of errors and how to recover from these errors

Glossary Definitions of specialized terms used

References References or links to other supporting documents

Index A list of key terms and the pages where these are referenced

Confidential 10

Managed Services

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 document, intended recipients of the document, key words for retrieving the document and a copyright notice.

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.

Confidential 11

Software DocumentationSetting Standards

Title: Setting Standards

Project: SD/01/2011

Document Identifier: SD/WD/2011

Document type: Process Document

Version: 0.1 Date: 8 November 2011

Author: AXXXXX

Inspected: Approved:

Distribution: Internal

Confidentiality: Internal Process

Keywords: standards, document process

This document is the property of XXX Ltd. Its content is confidential.

Confidential, Copyright © 2023 XXXX

Managed Services

d. Numbering Scheme: A consistent numbering scheme for chapters, sections and sub-sections should be defined

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.

3.3 Document Format and writing style

3.3.1 Document Components

Writing Content Defining the Audience Information Design

3.3.1.1 Writing Content:-

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

Confidential 12

Managed Services

3.3.1.1.1 Defining the GRAPE approach:

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; Twenty-

seven 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

Confidential 13

Managed Services

3.3.1.1.1.6 Presentation:

Presentation includes the following:

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

3.3.1.1.2 Style Guide

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

Confidential 14

Managed Services

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.

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:

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”

3.3.1.2 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:

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

3.3.1.3 Information Design

Information design is structuring the information to enable the user access and interpret information when required.

Confidential 15

Managed Services

Basic rules of Information Design What is the subject/context? Who, why, when and how will the content be used? Structuring content Terminology

3.3.1.3.1 Grouping the information

Information is grouped into two categories:

i. General documents – This includes Minutes of the meeting, status reports of tasks planned/completed, achievements, escalations etc

ii. Product/Process/solution documents – This includes user manuals, installation manuals, Process manuals, product related documents.

3.3.1.3.2 Key reasons why product documentation is used:

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.

Confidential 16

Managed Services

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:

Please check the appropriate box corresponding to the question

Yes No

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?

Confidential 17

Managed Services

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 18

Additional comments section:

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

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. 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.

ii. 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.

Confidential 19

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 20