Docs site edit checklist

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.

Title

Check that:

• The doc's title effectively describes the contents.
• Procedural doc titles use active verbs; for example, Install not Installing.

Introduction

Check that:

• 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.

Headings (H2s)

Check that:

• 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 ing verb form.

Text

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

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.

Structure

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.