Skip to main content Link Menu Expand (external link) Document Search Copy Copied

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.