This quality review checklist provides a comprehensive framework for evaluating documentation and tutorials to ensure they are focused on tasks, well-organized, and clearly written in an engaging style, while maintaining accessibility and impartiality.
You can also use this checklist as a helpful tool for generating new topics that adhere to the same high-quality criteria.
Review Checklist for DITA Topics
Short description
- Is there a short description?
- Does the short description summarize what to expect in the rest of the topic?
- Is it no longer than two sentences?
- Does it just repeat the topic title or does it contain useful information?
đź’ˇ The short description text works like a thumbnail for the whole topic when you see it as a link preview or in search results.
Best Practices for Writing Short Descriptions | SAP Help Portal
SearchEngine Optimization for User Assistance (int.sap)
Introductory paragraph that explains why the content matters
- Does it reflect the use case for this topic?
- Does it mention why and when someone would want or need to read this topic?
- Does it provide context for the action?
- Are introductory paragraphs used to establish the audience and explain why they should care about the topic?
- Does it provide unique information and not repeat the title?
Communicating with Your Audience: Who Are Your Target Groups? | SAP Help Portal
Be task-oriented
- Does it focus on the tasks the users are trying to achieve with the tool?
- Does it consider how the user got there?
- Are the topic types used to best support the content?
- Is there a <concept> topic that explains the needs and context of the <task> topics to support them?
- Does the guide use <reference> topics appropriately?
Best Practices for Writing Task Topics | SAP Help Portal
Best Practices for Writing Concept Topics | SAP Help Portal
Best Practices for Writing Reference Topics | SAP Help Portal
Break complex topics/tasks into simple steps
- Can larger topics be broken down into smaller subtopics?
- Are there separate topics for large subsections?
- Is the main topic used as an overview that links to these smaller topics?
❌ Don't hide tasks in huge concept topics.
Use visuals to speed up understanding
- Is complex information presented in a graphic or a video to make it easier for the user to understand?
- Do the screenshots add value?
- Do the screenshots only show the details that are necessary?
đź’ˇ Humans are undoubtedly visual beings. We process visuals 60,000 times faster than text. Visual content is way easier to understand, faster to absorb, and plays a huge role in helping users understand how to perform certain tasks.
Multimedia and Graphics: Overview | SAP Help Portal
Follow SAP writing styles
Good writing follows basic principles such as simplicity, precision, conciseness, active voice (“you”), and logical sequence.
- Do the texts follow SAP styles, including the principles of Brand Voice?
- Is the text easy to read?
- Have the correct approved names been used?
- Does it use active voice?
- Is the user addressed directly with “you”?
- Does the text use standard formulations, such as the recommended ways to introduce lists?
- Does it sound like something a real person would say?
- Is the tone friendly and conversational?
- Does the text use content reuse methods whenever possible, such as variables for product names, content key references (conkey refs), or profiling?
Style and Wording: Practical Issues and Principles | SAP Help Portal
About the SAP Style Guide for Technical Communication | SAP Help Portal
SAP's Tone of Voice and Writing Style (Brand Voice) | SAP Help Portal
People-Centric Language and Communication
Conversational Tone and Casual Phrasing | SAP Help Portal
Reuse Options in the IXIASOFT CCMS
Follow BTP-specific guidelines
Review the BTP-specific guidelines. For certain types of content, there are templates available to make creating documentation easier.
- Have you used the BTP-specific guidelines?
- Have you used the available templates for creating specific guides, such as the Service Guide Template?
Overview - Product Specifics- Writing Guidelines (frontify.com)
Overview - Deliverables - Writing Guidelines (frontify.com)
Communicate in a way that is free of stereotypes and empower people of all abilities
- Does the text use the third person in the plural to avoid gender-specific pronouns? (“they”, “their”, “them”)?
- Does the text use “choose” instead of “click” or “tap”?
- Does the text refer to a person’s role? (reader, employee, customer, or client, for example)
- Does it use the second person (“you”)?
Writing Accessible Documentation
Bias-Free Language and Communication | SAP Help Portal
Accessibility | SAP Help Portal
SAP Accessibility Standard - Accessibility - Wiki@SAP (int.sap)
Making Content Usable for Everyone (Accessibility To Dos) | SAP Help Portal
Revamp and revise
Continuously review, update, and polish your documentation to make it the ultimate go-to resource.
✔️Use Acrolinx to check your topic
✔️Make sure that all of your topics are reviewed by another person. Set up peer editing in your team or use our language editing services.
Using Acrolinx | SAP Help Portal
Language Editing - Support - Writing Guidelines
Review Checklist for Tutorials
Title and description
- Is the title specific? Does it help the user to differentiate this tutorial from others?
- Does the title consist of no more than 8 words?
- Is the description no longer than 20 words?
- Is the description an expansion of the title? Does it start with a repetition of the title and then add more information?
- Does the description explain the greater context?
✔️ Carefully read through the Style Guide for SAP Tutorials to learn more about formatting and style of tutorials.
Style Guide for SAP Tutorials
“You Will Learn” paragraph and details that explain why the content matters
- Does the “You Will Learn” section list general tasks and skills that the user will learn in this tutorial?
- Does it provide context for the action?
- Besides the “You Will Learn” paragraph, are there details provided about additional prerequisites or more context?
- Is it unique and does not repeat the description?
Style Guide for SAP Tutorials
Communicating with Your Audience: Who Are Your Target Groups? | SAP Help Portal
Is it task-oriented?
- Does it focus on the tasks the users try to achieve with the tool?
- Does it consider how the user got there?
- Does it consider what the user is trying to do?
- Does it provide everything the user needs to know to achieve their tasks?
- Does it provide information or links to other tutorials or to documentation?
- Does it only describe what is needed?
Break complex topics/tasks into simple steps
- Can the topic be broken down into smaller chunks?
- Are there separate tutorials for separate tasks?
❌ Don't cram too much information and too many steps into one tutorial.
Use Visuals to Speed Up Understanding
- Was complex information presented in a graphic or video to make it easier for the user to understand?
- Do the screenshots add value?
- Do the screenshots only show the details that are necessary?
đź’ˇ Humans are undoubtedly visual beings. We process visuals 60,000 times faster than text. Visual content is way easier to understand, faster to absorb, and plays a huge role in helping users understand how to perform certain tasks.
SUI Graphics Guidelines
Added-value Checklist for Screenshots
Multimedia and Graphics: Overview | SAP Help Portal
Follow SAP Writing Styles
Good writing follows basic principles such as simplicity, precision, conciseness, active voice (“you”), and logical sequence.
- Do the texts follow SAP styles, including the principles of Brand Voice?
- Is the text easy to read?
- Have the correct approved names been used?
- Does it use active voice?
- Is the user addressed directly with “you”?
- Does it sound like something a real person would say?
- Is the tone friendly and conversational?
Style and Wording: Practical Issues and Principles | SAP Help Portal
About the SAP Style Guide for Technical Communication | SAP Help Portal
SAP's Tone of Voice and Writing Style (Brand Voice) | SAP Help Portal
Conversational Tone and Casual Phrasing | SAP Help Portal
Communicate in a way that is free of stereotypes and empower people of all abilities
- Does the text use the third person in the plural? (“they”, “their”, “them”)?
- Does the text use “choose” instead of “click” or “tap”?
- Does the text refer to a person’s role? (reader, employee, customer, or client, for example)
- Does it use the second person (“you”)?
Example: “If you have the appropriate rights, you can set other user’s passwords.”
Writing Accessible Documentation
Bias-Free Language and Communication | SAP Help Portal
Referring to the User Interface – Beware of Click Level | SAP Help Portal
Accessibility | SAP Help Portal
SAP Accessibility Standard - Accessibility - Wiki@SAP (int.sap)
Making Content Usable for Everyone (Accessibility To Dos) | SAP Help Portal
Revamp & Revise
Continuously review, update, and polish your tutorials to make sure they are always up to date and relevant.
✔️Use a spellchecker
✔️If you do not have first-language proficiency in English, ask for language editing.
Language Editing - Support - Writing Guidelines (frontify.com)