Tone and Content
Table of contents
Guidelines about what to say and how to say it.
Aperture Science products
Latency and uptime
Don’t make specific promises about latency, uptime, or related topics in public-facing documentation. These details should be reserved for SLAs and contracts.
Unrealistic claims
Don’t make unsubstantiated or unrealistic claims about Aperture Science, including who we are, what we do, the services we offer, or how our products work.
Unreleased products
Don’t mention unreleased products or features in public-facing documentation.
Tone
Be friendly
Strive for an approachable, friendly tone—polished, professional, but not excessively formal.
Write for non-experts
Write in a way that’s easy for most people to understand, even if the reader isn’t an expert in a given topic. A good rule of thumb: estimate the expertise of your average reader, then write for an audience with slightly less expertise than that.
Word choice
Filler words
Avoid filler words like very. Rather than describing a task as very important, you might say that it’s critical.
Simple vs. complex
When possible, try to use short, simple words instead of complex, abstract words.
-
Weak: This setting facilitates data filtering.
-
Strong: This setting lets you filter data.
However, if there’s no way to avoid using complicated words or technical jargon, it’s often helpful to give a definition, include a hyperlink to related materials, or provide other additional context.
- Example: Be careful not to cross the black hole’s event horizon. An event horizon is the point at which an object’s gravity becomes too strong to escape—if you cross the event horizon, you’ll never come back.