When you're creating a new doc, there's a lot to keep track of. You can use this checklist to make sure you've done everything.
- The doc's title effectively describes the contents.
- Procedural doc titles use active verbs; for example,
- The introduction leads with an outcome and provides an overview of how to get there, so customers are confident they've found the right doc.
- It provides a short, readable overview of the doc's contents.
- Heading names are concise, yet provide information that helps readers to skim or skip to the section they want.
- Procedural H2s use active verbs, not the
Check that the text:
- Optimizes for easier translation: Avoid idioms, slang, specific cultural references, etc.
- Tells a good story: Promotes the platform (other New Relic products, alerting, etc.). Includes examples and use cases, identifies personas, explains not only what it is or how to use it but why it matters.
- Includes hyperlinks in UI paths.
- Has no typos.
Procedures use active voice and focus on steps ("do this"). Avoid burying tips or extra details in the steps.
- If the procedure includes prerequisites or background information, that information appears before (not buried inside) the ordered list of procedures.
- If a procedure or step branches, it splits the options so they are clearly visible as bullets, collapsers, etc.
- If the procedure says what not to do, it also describes what to do instead.
Example: What not to do and what to do instead
Do not monitor your own applications from the partnership owner account. Instead, create an account within the partnership, and monitor apps from that account.
The original tech writer or docs site contributor is the best judge of whether the draft doc is complete. However, in your peer edit, make notes if you have unanswered questions that aren't addressed within the doc or its cross references.
Check that the overall doc:
Readers can see at a glance what the doc is about and what to do. It's obvious what parts they can read and what parts they can skip.
The doc avoids excessive use of callouts, long sentences, or long paragraphs.
For screenshots and images, check that:
Levels of detail
The doc uses H2s, H3s, bullets, tables, and clamshells to organize complex levels of information.