• /
  • Log in
  • Free account

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.

Doc structure

Comments

Complete

Check that the overall doc:

  • Is complete, but stays on topic.
  • Includes useful cross references, hyperlinks, and other suggestions to enhance the information, especially for SEO.

Skimmable

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.

Visually clean

The doc avoids excessive use of callouts, long sentences, or long paragraphs.

Useful images

For screenshots and images, check that:

  • Full size images always have captions to explain their relevance.

  • UI paths in captions always have hyperlinks.

  • Cropped images clearly show their relevance, with or without captions.

    In addition, make sure that screenshots and images follow the Docs site's security guidelines, and that no private information related to customers or New Relic is displayed.

Levels of detail

The doc uses H2s, H3s, bullets, tables, and clamshells to organize complex levels of information.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.