Easy to use
Easy to use
| Criteria | Checklist |
|---|---|
| Task orientation | ☐ Write for the intended audience ☐ Present information from the users’ point of view ☐ Focus on users’ goals ☐ Indicate a practical reason for information ☐ Provide clear, step-by-step instructions |
| Accuracy | ☐ Research before you write ☐ Verify the information that you write ☐ Keep information current ☐ Keep information about a subject consistent ☐ Use spell checkers, grammar checkers, link checkers |
| Completeness | ☐ Fix things in the UI (if there is one) ☐ Apply a pattern for disclosing information ☐ Cover all relevant subjects (and only those) ☐ Cover each topic only in as much detail as users need |
Easy to understand
Easy to understand
| Criteria | Checklist |
|---|---|
| Clarity | ☐ Focus on the meaning ☐ Eliminate wordiness ☐ Write coherently ☐ Avoid ambiguity ☐ Use technical terms consistently |
| Concreteness | ☐ Consider the skill level and needs of users ☐ Use elements that fit in the information type ☐ Elements should be focused, realistic and up to date ☐ Use scenarios to illustrate tasks and provide an overview ☐ Make code examples easy to use ☐ Set the context for examples and scenarios ☐ Use similies and analogies to relate unfamiliar to familiar ☐ Use specific language |
| Style | ☐ Use active voice ☐ Use the right tone ☐ Avoid gender and cultural bias ☐ Spell terms consistently and correctly ☐ Use proper capitalization ☐ Use consistent and correct punctuation ☐ Apply consistent highlighting ☐ Make elements in parallel ☐ Apply templates and reuse snippets/elements ☐ Use consistent mark-up tagging |
Easy to find
Easy to find
| Criteria | Checklist |
|---|---|
| Organization | ☐ Put information where users expect it ☐ Arrange elements to facilitate navigation ☐ Reveal how elements fit together ☐ Emphasize main points; make secondary points subordinate |
| Retrievability | ☐ Optimize for searching and browsing ☐ Guide users through information ☐ Link appropriately ☐ Provide a helpful entry point |
| Visual effectiveness | ☐ Apply visual design practices to textual elements ☐ Use graphics that are meaningful and appropriate ☐ Apply a consistent visual style ☐ Use visual elements to help users find what they need ☐ Ensure that visual elements are accessible to all users |
rules/cognite-styleguide.md in the repository (canonical) or the style guide summary.
Before you request review, work through this checklist together with the style guide.