Our five questions form the core of how our Tech Docs team thinks about writing excellent technical documentation. Informally, we call these our 5Qs.
Anyone can contribute to our docs site. We want you to feel confident and proud that your contributions provide valuable content and quality. We also want our readers to trust and easily use the information in our docs. To help you plan, write, and edit excellent docs, ask yourself the questions in this doc.
There's really only 1Q
The 5Qs exist to help answer one question. Whenever you write a doc, ask yourself:
What problem are we trying to solve?
It's critical you know what you're trying to do and why that goal matters to your readers. Asking the five questions (and the sub-questions!) will help you ensure you're building the right thing.
5Qs and sub-questions
Each of the five questions includes sub-questions to help guide your thinking.
Think about who your audience is and the level of complexity they need.
End users' point of view
Ask yourself:
Audience
Do you know who is reading your document (dev/ops teams, support personnel, non-technical staff, etc.)?
Can you articulate what this thing is (feature, procedure) and why it matters to our customers?
For conceptual info, did you interview multiple stakeholders?
Testing
Put yourself in the user's shoes. For example:
Did you use the thing on your own?
Did you watch a subject matter expert use the thing?
If you can't do it on your own or observe, did you send the draft to at least three SMEs?
Before publishing
Did you compare the final version of your text against the thing you're writing about?
Think about where this information belongs.
Where does this information belong?
Ask yourself:
What problem are you trying to solve?
Is text always the best answer?
Does this doc need to exist at all?
For example:
Are we duplicating content from somewhere else in the docs site?
Are we duplicating content already in the UI?
Could customers have a better experience if we modified the UI design or copy instead of creating a doc?
Think about what the content is and what you can do to make the information easy to skim to find information.
Can users skim to find information?
Ask yourself:
Title and headings
Does the title accurately represent what's in the doc?
Do the headings accurately represent what's in the doc?
Do the title and headings use words the way your readers do?
Do the title and headings avoid New Relic jargon?
Structure
Does the overall structure of the doc help readers find what they're looking for?
Is the doc trying to address too many topics?
When you glance at the doc, do you see short paragraphs, short sentences, and other visual aids? Or do you see a dense wall of text?
Introduction
Does the intro give a concise synopsis of what's in the doc?
Does the intro give readers an alternate path if they're in the wrong place?
Think about how to present the information visually.
Presentation of information
Ask yourself:
Visual formats
Did you use visual formats appropriately?
Would a screenshot make any of the information easier to understand?
Does your image caption clearly explain what matters so that the user does not necessarily even need to read the surrounding text?
Would a diagram make any of the information easier to understand?
Is there a video we could embed to make things clearer? Can step-by-step UI procedures be replaced with a "show me" video?
Procedures
Are your procedures well-structured?
Do step-by-step UI procedures even need to be documented?
Did you limit the procedural text to action steps and omit detailed explanatory text or edge cases?
If detailed explanations need to enhance a procedure, have you organized the info in a way that expert users can skip the details?
Text flow
Read your draft more than once.
Is the documentation direct and to the point?
Did you use bullets, tables, or clamshells to improve flow?
Think about why the information matters and why readers will trust and use it. For tips to make it easier for users to read, understand, and use documentation, go to plainlanguage.gov.
Also, if you are a New Relic employee, we encourage you to review the corporate brand guidelines. For more information, contact Marketing.
Effective language
Ask yourself:
Readers' point of view
Did you tell users why as well as how?
Can you articulate not only what this thing is (feature, procedure) and also why it matters to our customers?
Did you include useful examples or use cases?
Did you include information about relationships this feature has to other New Relic platform tools?
If not, try taking another pass at the prose. But don't chase the Flesch-Kincaid score in itself: we're not out to frustrate ourselves, but to write docs that are a pleasure to read.
Where to go from here
Did you offer readers a clear "next step" in each section?
If it is necessary to tell a user not to do something, did you also tell them what to do instead?