DOCUMENTATION CHECKLIST

A comprehensive checklist for all the stages in the documentation

development l ife cycle

Raghunath Soman

DOCUMENTATION CHECKLIST P A G E | 1

DOCUMENTATION CHECKLIST Requirements Gathering Every documentation project starts with information gathering. Interviewing the subject matter

experts is the chief source of information and it is imperative that a technical writer asks the

right questions to the appropriate SMEs.

Here are some questions that one can ask, irrespective of the type of application, domain or the

project.

Interaction with Project Manager

Client name Good way to start the discussion. Who’s the client? From where

they are? Their Web site?

Product name: Sounds basic, eh? Well, the project name and the name of the

application you will be documenting need not always be the

same. Also, sometimes, product names need to be spelled in a

specific way due to trademark purposes.

Release date and

documentation deadline:

Again, these two need not be (and, preferably, should not be)

the same. For bigger projects, it is advisable to set deliverable

date at least a week prior to the release date. This gives you

time to check up context sensitive help. In some cases, the

documentation is delivered after the product release. In this

case too, you need to be clear about the deadlines.

Documentation suite: What are the documents to be submitted? A typical

documentation suite would consist of installation guide, user

manual and a technical reference manual.

Deliverable format: Are the documents needed in PDF format? CHM help? Will the

customer also need the source files?

DOCUMENTATION CHECKLIST P A G E | 2

Documentation scope: What is the expected depth of content in the documents?

Should it be very descriptive, or just to-the-point? Contrary to

the popular belief that user documentation shouldn't contain

jargon, it is necessary to use precise industrial terminology. The

documentation scope largely depends upon the target

audience. See the next point.

Target audience: Who will be the end users of the system? What are the

assumptions about the skill level?

Point of contact and

communication channels:

Usually you will interact with the project manager, but she might

choose to appoint the team lead or the QA lead as your single

point of contact. Ask what would be the medium of

communication with the team lead and team members; will it be

e-mail, Skype or face-to-face interactions?

Content management: Does the team use a content management system? VSS? SVN?

Be sure to ask about version control method.

Reference documents: Ask about any available documentation about the product:

design documents, understanding documents, etc.

Access to servers, Mailing

list, etc.

You will also need access to various machines, servers. Get your

name added to the project mailing list.

Client communication: Are there any weekly meetings? Will you be involved in client

communication?

Interaction with Dev /QA Team Leads

In large projects, the project manager is likely to delegate the task of documentation

communication to either the technical lead or the QA lead. Here are some of the important

details you need to get from these people:

Application overview: This is a bird’s eye view of the application and the domain. Ask

about the purpose of the application, how exactly it helps the

user to accomplish a particular task.

System overview: Each application consists of a number of components. Ask

about how the individual modules interact with each other.

Does the application use a database? Does it have a web-

component?

DOCUMENTATION CHECKLIST P A G E | 3

System configuration: Inquire about the minimum and recommended hardware and

software components necessary to run the application. How

much RAM is sufficient? What service packs are required?

Names of people and

modules:

On the people side, get the names of people in team and the

modules they will be working on.

Time slot: Rather than disturbing technical lead or QA lead every 10

minutes, have a time-slot in which you can get a bunch of

questions cleared in one go. In a big project, ask for one hour

every week; in a smaller project, ask for half hour every day.

Interaction with Developers and QA

As the documentation proceeds, you will be interacting with the individual members of the

team: programmers and quality analysts. Apart from the questions specific to the application,

here are some general queries that you can ask:

How the modules are

linked:

How does component A interact with B? And how both of them

relate to module C?

Process workflow: Ask about a complete iteration of the process workflow; what

are the inputs to the system how the system processes those

inputs and what it generates as the output. Using flowcharts,

sequence flow diagrams greatly helps.

Bug fixes: Apart from change requests (usually from the customer), the

main cause of any change in the product is bug fixes. QA

identify a bug, developers fix it; sometimes making significant

changes either in the functionality or the user interface. The best

way to keep up is to get access to the bug tracker for the

project. In large projects, the bugs will be added in a bug-

tracking system; In small projects, the team may make do with

Excel sheets shared and updated by the team. Whatever the

bug-tracker, you must have at least read-access to it.

Troubleshooting: While using the application, you are likely to come across

confusing workflows or screens. Put yourself in place of the user,

and try to identify the steps you will need to implement for a

work-around. Troubleshooting tips are an important part of

documentation.

DOCUMENTATION CHECKLIST P A G E | 4

Interaction with Networking

In small projects, the team should be able provide you with all the details, including related to

network. However, in big projects, try to get your answers directly from system administrators.

Network topology: What is the network topology: is it star, bus, or a

composite?

System-specific requirements: Inquire about any specific dependencies about the

product. For example in Linux, it is good to have a list of

RPM dependencies.

Network requirements: Ask about administrator privileges, bandwidth

requirements, firewall settings, and so on.

Network topology: What is the network topology: is it star, bus, or a

composite?

System-specific requirements: Inquire about any specific dependencies about the

product. For example in Linux, it is good to have a list of

RPM dependencies.

Network requirements: Ask about administrator privileges, bandwidth

requirements, firewall settings, and so on.

Interaction with Client

It is always a good practice to be directly interacting with the customer: it relieves the project

manager of communication, and resolves many misunderstandings. Here are some questions

best answered by the customer.

Document suite

Document structure and templates

Point of contact and communication channels

Status reporting frequency

DOCUMENTATION CHECKLIST P A G E | 5

Analysis and Planning

Define the purpose of the

document and the key

information it needs to convey

Establish the purpose of a document. Be specific with

your objectives i.e. “Why does the reader need this

information, and what do they need to do with it?”

Concentrate on "Why" and "What"

Define the audience and their

level of technical understanding

Recognize the audience, based on:

Level of technical knowledge

Level of information they require

Based on the level of interest in the subject

Determine the level of detail

necessary for the document

Determine:

The scope of the document

The supporting information to include

The research required

The contribution from subject matter experts

Organize the data Develop:

A rough outline of the topics to be covered

The audience for that topic

The key points for the topic

The data required to support these points

Working with a team of

authors?

Identify the primary contributors for documentation, the

editor, the SME, the style guide to be followed.

Meet deadlines Define the deadlines clearly with the consent of the stake

holders

DOCUMENTATION CHECKLIST P A G E | 6

Documentation General writing Present Tense, Active Voice

Simple Sentences

Gender Neutrality

Spell out Abbreviations and Acronyms in first instance of usage

Use list items for enhancing readability

Provide descriptive titles for figures and tables

Use the cross-reference wisely

Avoid redundancy like usage of same word twice in a sentence

or stating the same idea in multiple sentences of a paragraph

Refer style guide as per the client requirement

Formatting elements Ensure that the cover page in the document has the correct

Version number of the product

Ensure that the cover page in the document has the correct

Version number of the document

Ensure that the cover page in the book has the updated “Last

updated date”

Ensure that the Book title is like: (Style: Font, color, case,

indentation)

Ensure that the book has different Even and Odd page as per

the header and footer are concerned

Ensure that the Toc is indented like: (Style)

Ensure that the table heading has this shading pattern: (Style)

Ensure that the Heading 1 is like: (Style: Font, color, case,

indentation, Numbered or not)

Ensure Heading 2 is like: (Style: Font, color, case, indentation,

Numbered or not)

Ensure Heading 3 is like: (Style: Font, color, case, indentation,

Numbered or not)

Ensure the application of First level bulleted list

Ensure the application of second level bulleted list: (Style: Shape

of the bullet, indentation)

Ensure the application of third level bulleted

Ensure that the correct application of first level numbered list

Ensure that the correct application of second level numbered list

Ensure that the Images are uniformly aligned (have a uniform

image indentation for all the documents)

Ensure that each image has a particular resolution (As per

requirement)

Ensure that each image has a border

Ensure each image has a title

DOCUMENTATION CHECKLIST P A G E | 7

Ensure that the heading for the procedure topics starts with verb

in a gerund form.

Ensure that the body text is: (Style: Font, size)

Ensure that the table header text is: (Style: Font, size)

Ensure that the table body text is: (Style: Font, size)

Ensure that the codes, properties, attributes, paths are: (Style:

font, size)

Ensure that the list items are having serial comma if the list has

more than two items

Ensure that each lead in line introducing a list or numbered

items ends with a colon (:)

Ensure that the each numbered lists are ending with (a period or

no period)

Ensure that the each bulleted lists are ending with (a period or

no period)

Employ ethical

principles

Avoid language that attempts to evade responsibility

Avoid language that could possibly mislead readers

Do not de-emphasize or suppress important information

Do not emphasize misleading or incorrect information.

Treat others fairly and respectfully.

Give credit where it is

due

Use footnotes, endnotes, and bibliographies to acknowledge where

you found particular bits of information.

Document Review

DOCUMENT REVIEW CHECKLIST

Project Name: Project Code:

Document Name: Document Number:

Reviewed By: Reviewed Date:

Presentation

Document has a cover page with title (product name, document type), team name, date,

version number, status (draft, ready for review, approved).

Document has been subjected to the project's Quality Assurance procedures.

Document has been entered into the project's Configuration Management system.

All open issues are clearly marked as such.

The relationships to prerequisite documents are explicitly stated.

The presentation is consistent with other documents in the same suite.

DOCUMENTATION CHECKLIST P A G E | 8

The terminology is used consistently, both within a document and across documents. (One

term for one thing. Each term refers to only one thing, each thing is referred to by only one

term.)

The section of Definitions, acronyms, and abbreviations is exhaustive and complete. (Possibly

include reference from this section to main text for details.)

Duplication of information is avoided. Do a cross-reference, rather than copy.

The references to other material are:

Complete: No missing references, e.g. to Interface Control Document.

Precise: Including author(s), title, publisher, year, and for journals also volume/number.

Generally accessible and durable: Not to a webpage that is likely to disappear soon.

The document structure is consistent with format and content specified in the project plan.

Electronic spell check has been completed.

Each page been visually inspected for correct page numbers.

Each page has been visually inspected for correct spacing.

Each page has been visually inspected for accurate headers and footers.

Each page has been visually inspected for correct margins (left and right, top and bottom).

Each page has been visually inspected for appropriate page breaks (no headings or

subheadings at the end of a page without following text).

The footnotes or endnotes numbered in sequence.

Table of Contents

Each section of the document that should appear in the Table of Contents, does appear.

The sequence of numbers in the Table of Contents is correct.

The indentation of the Table of Contents is correct.

The format of each entry in the Table of Contents is correct (for example, level two

entries appear in accordance with the formatting standards for level two entries).

Appendices are identified in sequence by letter or number.

Body of Document

The writing style and grammar are of high quality.

The document uses consistent tense.

The language is appropriate for the audience.

Sentences use simple structures - there are no complex and confusing sentences.

The transitions from one section to another are smooth.

Unnecessary information and words are eliminated.

Each acronym or abbreviation is introduced the first time it is used.

The document adheres to any other special items defined in the project's standards for

readability.

DOCUMENTATION CHECKLIST P A G E | 9

Consistency

Internal cross-references within the document are accurate.

References to other existing documents are valid.

The material is consistent with other existing documents.

The material is consistent with the basic principles in the documentation suite.

Content

In addition to the below checkpoints, use a supplementary checklist tailored to the specific

content of the deliverable.

The document satisfies the defined goals and objectives.

The potential impact on future deliverables has been considered.

The material appears to be technically accurate.

The material appears to be feasible.

The material appears to provide the customer with the best solution.

Informative tips, risks, and warnings have been mentioned, where appropriate.

Review Guidelines

Provide "facilitative" as opposed to "summative" evaluations. Do not make comments

such as "This is wrong!" or "Missing a step." Provide the correction wherever possible.

Avoid "appropriating" colleagues' texts and simplifying colleagues' roles

Play the role of the writer's intended audience.

Encourage colleagues to view revision as an opportunity to clarify and discover one's

meaning.

Accessibility

1.1

Text alternatives: Provide text alternatives for all non-text content so that it can be

changed into other forms people need, such as large print, Braille, speech, symbols or

simpler language.

1.1a Text alternatives. All non-text content that is presented to the user has a text alternative

that serves the equivalent purpose.

1.1b

Non-text content. A descriptive label is provided for time-based media, including live

audio-only and live video-only content. Non-text content that is used to confirm that

content is being accessed by a person rather than a computer is available in different

forms to accommodate multiple disabilities.

1.1c Image maps. Client-side image maps are used and alternative text is provided for image

map hot spots. Equivalent text links are provided if a server-side image map is used.

DOCUMENTATION CHECKLIST P A G E | 10

1.2 Time-based media: Provide alternatives for time-based media.

1.2a Captions. Captions are provided for prerecorded audio content in synchronized media,

except when the media is a media alternative for text and is clearly labeled as such.

1.2b

Audio and video (prerecorded). An alternative for time-based media or audio description

of the prerecorded video content is provided for synchronized media, except when the

media is a media alternative for text and is clearly labeled as such.

1.2c Live multimedia. Captions are provided for live multimedia.

Captions (Live). Captions are provided for all live audio content in synchronized media.

1.3 Adaptable: Create content that can be presented in different ways without losing

information or structure.

1.3a Information and relationships. Information, structure, and relationships conveyed

through presentation can be programmatically determined or are available in text.

1.3b Meaningful sequence. When the sequence in which content is presented affects its

meaning, a correct reading sequence can be programmatically determined.

1.3b Forms. Form element labels can be programmatically determined.

1.3d Tables. Table cells and relationships between cells can be programmatically determined.

1.3e Cascading style sheets. Documents are readable without requiring style sheets.

1.3f

Sensory characteristics. Instructions provided for understanding and operating content

do not rely solely on sensory characteristics of components such as shape, size, visual

location, orientation, or sound.

1.4 Distinguishable: Make it easier for users to see and hear content including separating

foreground from background.

1.4a Use of color. Color is not used as the only visual means of conveying information,

indicating an action, prompting a response, or distinguishing a visual element.

AA1.4.3

Contrast (Minimum). The visual presentation of text and images of text has a contrast

ratio of at least 4.5:1, except for large print and images of large print, which must have a

contrast ratio of 3:1. Text or images of text that are part of an inactive user interface

component, that are pure decoration, that are not visible to anyone, or that are part of a

picture that contains significant other visual content, have no contrast requirement. Text

that is part of a logo or brand name has no minimum contrast requirement.

AA1.4.4 Resize text. Text (but not images of text) can be resized without assistive technology up

to 200 percent without loss of content or functionality.

AA1.4.5

Images of Text. Use text to convey information rather than images. An image of text may

be used if it is essential to the information being conveyed or if the image of text can be

visually customized to the user's requirements.

2.1 Keyboard Accessible: Make all functionality available from a keyboard.

2.1a

Keyboard. All functionality of the content is operable through a keyboard interface

without requiring specific timings for individual keystrokes, except where the underlying

function requires input that depends on the path of the user's movement and not just

the endpoints.

2.1b Scripts. Scripts are keyboard accessible. If the content affected by scripting is not

accessible, an alternative is provided.

DOCUMENTATION CHECKLIST P A G E | 11

2.1c

Applets, plug-ins, and non-HTML content. A link is provided to a directly accessible

applet, plug-in or other application. Alternate content is provided for those applets,

plug-ins or other applications that are not directly accessible.

2.1d

No keyboard trap. If keyboard focus can be moved to a component of the page using a

keyboard interface, then focus can be moved away from that component using only a

keyboard interface, and, if it requires more than unmodified arrow or tab keys, the user is

advised of the method for moving focus away.

2.2 Enough Time. Provide users enough time to read and use content.

2.2a Adjust time response. The user is allowed to turn off, adjust or extend all time limits that

are not a real-time, essential or 20 hour exception.

2.2b Pause, stop, and hide. The user is allowed to pause, stop, or hide moving, blinking,

scrolling, or auto-updating information unless it is an essential part of an activity.

2.3

Flashing Content or below threshold. Documents do not contain anything that flashes

more than two times in any one second period, or the flash is below the general flash

and red flash thresholds.

2.4 Navigable: Help users navigate, find content, and determine where they are.

2.4a Navigational features. A mechanism is available to bypass blocks of content that are

repeated on multiple Documents.

2.4b Navigate to main content. Methods are provided for skipping over navigation links to

get to the main content of the page.

2.4c Frames. A title and an accessible frame source are provided for each frame.

2.4d Page titles. Documents have titles that describe topic or purpose.

2.4e

Focus order. If a Document can be navigated sequentially and the navigation sequences

affect meaning or operation, focusable components receive focus in an order that

preserves meaning and operability.

2.4f

Link purpose. The purpose of each link can be determined from the link text alone or

from the link text together with its programmatically determined link context, except

where the purpose of the link would be ambiguous to users in general.

AA2.4.5 Multiple Ways. More than one way is available to locate a Document within a set of

Documents except where the Document is the result of, or a step in, a process.

AA2.4.6 Headings and Labels. Headings and labels describe topic or purpose.

AA2.4.7

Focus Visible. Any keyboard operable user interface has a mode of operation where the

keyboard focus indicator is visible.

3.1 Readable: Make text content readable and understandable.

3.1a Language of page. The default human language of each Document can be

programmatically determined.

AA3.1.2

Language of Parts. The human language of each passage or phrase in the content can be

programmatically determined except for proper names, technical terms, words of

indeterminate language, and words or phrases that have become part of the vernacular

of the immediately surrounding text.

DOCUMENTATION CHECKLIST P A G E | 12

3.2 Predictable. Make Documents appear and operate in predictable ways.

3.2a On focus. When any component receives focus, it does not initiate a change of context.

3.2b On input. Changing the setting of UI component does not automatically cause a change

of context unless the user has been advised of the behavior before using component.

AA3.2.3

Consistent Navigation. Navigational mechanisms that are repeated on multiple

Documents within a set of Documents occur in the same relative order each time they

are repeated, unless a change is initiated by the user.

AA3.2.4 Consistent Identification. Components that have the same functionality within a set of

Documents are identified consistently.

3.3 Input Assistance: Help users avoid and correct mistakes.

3.3a Error identification. If an input error is automatically detected, the item that is in error is

identified and the error is described to the user in text.

3.3b Labels or instructions. Provided when content requires user input.

AA3.3.3

Error Suggestion. If an input error is automatically detected and suggestions for

correction are known, then the suggestions are provided to the user, unless it would

jeopardize the security or purpose of the content.

AA3.3.4

Error Prevention (Legal, Financial, Data). Documents used for legal commitments or

financial transactions, that modify or delete user-controllable data in a data storage

system, or submit user test responses must 1) allow the user to reverse the submission,

OR 2) be checked for input errors and provide the user with the ability to correct input

before submission, OR 3) allow the user to review, confirm and correct information

before finalizing the submission.

4.1 Compatible: Maximize compatibility with current and future user agents, including

assistive technologies.

4.1a

Parsing: In content implemented using markup languages, elements have complete start

and end tags, are nested according to their specifications, do not contain duplicate

attributes, and any IDs are unique, except where the specifications allow these features.

4.1b

Name, role, value: For all user interface components (including but not limited to: form

elements, links and components generated by scripts), the name and role can be

programmatically determined; states, properties, and values that can be set by the user

can be programmatically set; and notification of changes to these items is available to

user agents, including assistive technologies.

4.2 Ensure that content is accessible or provide an accessible alternative.

4.2a Text-only page: If accessibility cannot be accomplished in any other way, a text-only

page with equivalent information or functionality is provided.

4.2b

Accessibility-supported technologies only: Use accessibility supported technologies. Any

information or functionality that is implemented in technologies that are not accessibility

supported must also be available via technologies that are accessibility supported.

DOCUMENTATION CHECKLIST P A G E | 13

Additional Comments and Recommendations

Section: Page:

Comments:

Disposition of Review Items

Recommendations Accepted as Given:

Recommendations Accepted With Modifications:

Recommendation Rejected with Explanation:

Comments:

Approvals

Team Leader:

Project Manager (or designate):

Date Closed:

References ByteSpace

TechWhirl

Tom Verhoeff

Toolbox.com

Michaels and Associates Learning Solutions

IBM Accessibility / Documentation Checklist

-End of Document-