software documentation - an overview
DESCRIPTION
what is software documentation all about.TRANSCRIPT
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