Checklist for Documenters
-
To develop high-quality documentation, we must adhere to certain standards. As a result, we use a checklist to guarantee that all document quality parameters are met.
-
Documenters must utilize this checklist after editing content and do a self-check. In some circumstances (when creating a lengthy document), a peer review can also help to avoid the most trivial errors.
-
A pull request should not be sent for review without self-check or peer review.
The checklist below will cover basic quality characteristics:
Accuracy
-
Is all the information documented correct and error-free?
-
Have you meticulously checked the content for any inaccuracies, typographical errors, or misleading statements?
-
Have you cross-checked facts, figures, and data against reliable sources?
-
Is all the information presented based on verified and trustworthy references?
-
Are software UI elements (button names, menu items, labels) documented correctly?
Clarity and Readability
-
Is the language clear, concise, and free of jargon?
-
Is active voice used throughout the document?
-
Is the grammar, spelling, and punctuation correct?
-
Are sentences well-structured and easy to understand?
-
Are appropriate headings and subheadings used for better readability?
-
Used bullet points or numbered lists wherever required to enhance readability?
-
Are software features explained with examples?
Consistency
-
Is approved terminology used in the document? (Refer to inTerm)
-
Are the same terms and definitions used consistently to avoid confusion?
-
Does the document adhere to a uniform writing style and tone that aligns with its purpose and audience?
-
Are abbreviations and acronyms defined the first time they appear?
-
Are all figures and tables labeled consistently?
-
Are software UI elements (button names, menu items, labels) named consistently?
Usability
-
Are diagrams, charts, and images relevant and well-integrated?
-
Are cross references working correctly?
-
Is cross reference easy to navigate between topics or pages?
-
Are the navigation buttons and page-wise TOC working properly?
Localization
-
Are the sentences, words and verbs easy to translate?
-
Translation IDs (Anchor points) for heading and subheadings created wherever required?