writing-style-guide.md

Writing Style Guide

These are technical writing guidelines that should be used for Ably's developer documentation.

This guide does not cover the details of marking up content source. See the CONTRIBUTING.md guide for details on content formatting.

Some of the benefits of using this style guide are:

• Instructions are easier to read and understand.
• More professional feel to documentation.
• Documentation is easier to translate to multiple languages.

Paramount is technical accuracy, which overrides all else. In writing developer documentation technical writers and contributors should strive for:

• Technical accuracy
• Clarity
• Simplicity
• Consistency

Sometimes these objectives can conflict with each other, in which case the technical writer must use their experience and judgement to decide on the best approach.

NOTE: As with most guidelines these are suggestions. Technical writers and contributors should always use their best judgement given the specific circumstances.

Technical terms

It is important to be consistent with the use of technical terms. In order to provide consistency with technical terms, acronyms, and product names you should always refer to the Ably Glossary.

Use International English

The company standard is, as with most software companies, to use International English. This is defined as US spelling, with Americanisms removed.

The industry standard dictionary is Merriam Webster.

Use inclusive language

Use inclusive language. Google has written extensively and thoughtfully on this subject, so there is no point in duplicating that here. See the Google guide for details on writing inclusive language.

Empathy

Empathy for developers should always be a key factor in your writing.

Use present tense

Use present tense. It’s easier to read and translate.

Examples:

• Future: Command X will start the server.
• Present: Command X starts the server.

Use simple language

For technical writing the best approach is to be simple, direct and technically accurate. To achieve this objective use clear, simple, accurate, and directive language.

Avoid being overly casual in developer documentation as this can lead to a sense of lack of professionalism. However, a more casual writing style may be suitable for more relaxed pieces such as specific blog posts, but in developer documentation this is best avoided, as technical accuracy and clarity are paramount.

Other things to avoid:

• Avoid verbose writing styles.
• Avoid using attempts at humour in technical writing.
• Avoid being casual, especially at the cost of technical accuracy and precision.

Technical writing needs to be unapologetically accurate and precise, and use specific terminology wherever necessary to ensure that the correct and unambiguous meaning is conveyed.

Avoid fillers

It's sometimes easy to get overly enthusiastic in technical documentation, and this shows itself by liberal use of superlatives. It's best to avoid this in material targeted at developers.

Avoid filler words and superfluous adjectives such as 'really nice feature', 'it may be that', 'and that's it'.

Avoid subjective phrases

Avoid subjective phrases. "You can easily...". "It is simple to...". "It's as easy as that!"

Rather than say how simple it is to do something, show the developer through specific steps. Let the developer be the judge of whether something is simple or not.

Contractions

It's generally fine to use common contractions, as long as the intent is clear. Where there may be the possibility for confusion, be explicit, for example, use "it is" or "it has" if using "it's" could lead to confusion. One common error is to use "it's" in the belief that the apostrophe is required if used in a possessive manner. This is never the case. For example:

• Incorrect: "Ably persists it's data in memory for two minutes."
• Correct: "Ably persists its data in memory for two minutes."

Number words

For small numbers generally you write the number as a word:

• Avoid: "Ably persists messages in memory for 2 minutes."
• Better: "Ably persists messages in memory for two minutes."

Larger numbers can stay as numerals, or where precision is required.

Use active voice

In line with directing the developer succinctly, it is recommended to mostly use the active voice. In active voice the Subject Verbs the Object. Remember SVO.

Examples:

• Active voice: The man ate the apple.
• Passive voice: The apple was eaten by the man.
• Active voice: The client creates the connection.
• Passive voice: The connection is created by the client.
• Active voice: Ably provides an Asset Tracking SDK.
• Passive voice: An Asset Tracking SDK is provided by Ably.

Active voice is simpler, more direct, and easier to translate.

The principle here is you want to guide the developer succinctly and accurately, in the most direct way possible. If you drop into passive voice because it feels correct for the situation that's fine, but generally you want to keep things simple and use active voice.

Paragraph breaks

In technical writing, and especially blog posts, you can be more generous with your use of paragraph breaks, compared to a novel. Paragraph breaks make the text less overwhelming and easier to read. Generally, you want to avoid dense and cramped text because it's harder to read and digest. From the technical writer's perspective dense text is also harder to maintain.

Parentheses

Generally avoid long sentences that have embedded parentheses as this makes the text harder to read. You can break out the bracketed text into a new sentence or rewrite the text to not require brackets. Sometimes the bracketed material might be better off as a note or tip admonition.

Avoid vague and cautious language

Avoid words such as would, should, might, and maybe, as it does not inspire confidence to use such language.

Example:

• Avoid: When an inbound message arrives, you might receive it, or you might get an error, or something!
• Better: When an inbound message arrives, the message callback handler is invoked.
• Avoid: If you click the button, the alert box will probably be displayed.
• Better: When you click the Submit button, the alert box is displayed.

Use second person

You should use 'you' rather than 'we' when referring to the reader, especially in task-based material such as tutorials.

The reason for generally avoiding 'we' is that it can potentially create confusion - who exactly is 'we'?

Consider the following, for example:

• Avoid: We now configure the Time To Live (TTL).

Is that something Ably configures on the developer's behalf, or does the developer have to do it, and if so how?

It is always best to be explicit: if the developer needs to do something, tell them directly what they need to do and how.

Examples:

• Avoid: We now need to enter an API Key.
• Better: You now need to enter your API Key in the Create Application dialog.
• Avoid: We can now click the button to create your Ably account.
• Better: You can now click the button to create your Ably account.
• Best: Click the Create button to create your Ably account.

Use Ably rather than 'we' when referring to the company.

Example:

• Avoid: We also provide a Ruby SDK.
• Better: Ably also provides a Ruby SDK.

Avoid Latin phrases and abbreviations

Latin abbreviations can occasionally cause confusion if not used correctly. For example, people can get confused between the meaning of "i.e." and "e.g." (and sometimes use them as equivalent).

Examples:

• Use ‘for example’, instead of 'e.g.'
• Use 'that is' rather than 'i.e.'
• Use 'and so on' instead of 'etc.'.

Sometimes writers create variations of Latin abbreviations, such as 'eg', 'e.g', 'eg.' and so on. It's best, for various reasons, to avoid this. When automated spell checkers are run, these variations can stop the doc build. As stated previously, to avoid this possible inconsistency creeping in, avoid using Latin abbreviations altogether.

Avoid Latin phrases such as "quid pro quo", "ad nauseum", "vis-a-vis". They can also be less convenient to translate, and not everyone is familiar with their meaning.

Avoid slang

Avoid slang as this can slow down translation and be hard for some developers to interpret.

For example:

• Don't use overly dramatic words like 'crash' or 'implode', use 'error'.
• Use 'launch' or 'start' rather than 'fire up'.
• Bear in mind the reader's daily language may not be English.
• The mouse is clicked and the keyboard is pressed. Avoid terms such as 'hit', 'punch', or 'whack' when referring to the keyboard. Avoid: "Now punch in any key to continue."
• Avoid idiomatic language such as "You're good to go", "We'll run this by you", "You're all done".

Avoid words that are rarely used

Avoid unusual words that have a more commonly used equivalent, unless doing so would compromise clarity and accuracy.

Some words are less frequently used, but have a more commonly used alternative word or phrase.

Some example suggested replacements:

• Use 'while' or 'during which' rather than 'whilst'.
• Use 'therefore' rather than 'ergo'.
• Use 'compatible' rather than 'concordant'.
• Use 'with regard to' rather than 'apropos' (if 'apropos' is being used as a preposition).

The aim is to keep things simple, avoid possible confusion, and aid translation, while retaining accuracy of meaning.

Capitalization

Try to be consistent with capitalization of headings.

The guidance here is to use sentence case for most things, as per the Microsoft Style Guide.

There are some exceptions: for example, the names of products, the titles of stand-alone manuals or guides, whitepaper or article titles, and the titles of people, should use title case. If you do need to use title case, you can use one of the widely available tools.

So, unless there is a good reason not to, use sentence case (first letter is capitalized).

Heading forms

Use imperative form for headings.

The imperative form is direct and action-oriented, making it clear what the developer needs to do.

Examples:

• Imperative (preferred): Configure the API client
• Gerund (avoid): Configuring the API client
• Imperative (preferred): Install the SDK
• Gerund (avoid): Installing the SDK

The only exception is FAQ-style content where the heading is phrased as a question. In all other cases, use the imperative form.

Bulleted lists

This is an example of a bulleted list:

• Precede a list with a sentence and a colon, followed by a blank line.
• Terminate each sentence in a list with a full stop.
• Use bulleted lists for lists of items that have no particular order.
• Use numbered lists for ordered sequences, such as procedures, tasks, a series of specific steps, items that are being enumerated, and so on.

Note the following points:

• The list should always have a piece of text introducing the list followed by a colon, and then a blank line.
• Each sentence in the list is terminated by a full-stop (period).
• If each item in the list is a single word, a terminating period is not required.
• Do not use bold formatting for prefixes in bullet points (for example, avoid patterns like "Feature name: description"), as this is a common indicator of AI-generated content.

Codeblocks

When inserting example code in the text:

• Specify the coding language attribute where possible.
• Break the text before a codeblock with a colon, not a period (which is a hard stop in the mind of the reader, rather than a continuation).
• There should not be a space before the colon.
• Place a blank line after the colon and before the code block.
• All headings must be followed by introductory text. Never place a code block, list, or other content immediately after a heading without explanatory text first.
• For JavaScript and TypeScript code, prefer single quotes over double quotes for strings (excluding JSON, which must use double quotes per the specification).

Acronyms

Define acronyms on first use. On subsequent use in a topic you do not need to redefine the acronym, unless you feel it would provide clarity.

Be explicit

Try to be explicit. Use precise terms where necessary to improve clarity and avoid ambiguity.

Use the Ably Glossary to ensure that you refer to product names and features with consistency.

Avoid genderized language

Avoid genderized language (use user/developer/client as appropriate).

Sometimes there are exceptions to this. For example in cryptography, it is an established practice to use Alice, Bob, and Eve to illustrate cryptographic scenarios.

Avoid using 'he or she' constructs. For example:

• Avoid: The developer can invoke the method, and then he or she can check the return code.
• Better: You can invoke the connection_state() method and then check the status code returned.

Use correct case

Make sure you write the correct case for product names:

• JavaScript not Javascript
• GitHub not Github
• macOS not Mac OS

Avoid AI-generated content fingerprints

Technical documentation should maintain a natural, human writing style and avoid patterns commonly associated with AI-generated content:

• Do not use em-dashes (—) in technical writing. Prefer standard hyphens (-) or restructure the sentence for better clarity.
• Avoid bold prefixes in bullet points (for example, patterns like "Feature: Description" or "Benefits: Details"). This formatting style is a telltale sign of AI-generated content.
• Avoid formulaic patterns and overly structured prose that may appear mechanical or template-driven.

These guidelines help ensure documentation feels authentic and professionally written while maintaining readability and clarity.

The additional patterns below have been seen repeatedly in AI-assisted drafts and should be cut from final copy:

• Corrective antithesis: "Not X. But Y." constructions that set up something the reader never assumed and correct it for drama. Say what you mean instead. Example to cut: "Cancellation isn't a connection-level operation. It's a turn-level signal" becomes "Cancellation is a turn-level operation".
• Dramatic pivot phrases. Cut "But here's the thing", "Here's the catch", "Here's what most people miss", "Here's the bind". Fold the point into the sentence.
• Soft hedging. Cut "It's worth noting that", "Something we've observed", "This is where X really shines", "It's important to remember". State the thing directly.
• Throat-clearing intros. No "Let's explore", "Let's dive in", "Let's break it down", "In this article we'll", "First, let's understand". The page header is the title, and the first paragraph should land the reader in the middle of the topic.
• Gift-wrapped endings. Cut "In summary", "In conclusion", "Ultimately", "Moving forward", "At the end of the day". Pages end with related links or the last substantive paragraph; they do not restate themselves.
• Generic examples. "Imagine an e-commerce app" or "consider a chat application" with no specific behaviour is filler. Use concrete examples that name a real behaviour (for example, "a user closes their laptop and picks up their phone", "a tool that takes longer than the agent's runtime budget").
• Overexplaining the obvious. Developers know what an HTTP request, a WebSocket, a React hook, a JWT, and the await keyword are. Do not define them. State the specific behaviour the reader needs to know about this surface.
• Audience-aware cuts. Once the audience is established (developers and senior engineers), cut explanations of things they already understand. Restating known concepts to fill space makes the writer look unsure of the reader.
• Copy-paste metaphors. If the same metaphor or framing phrase appears more than twice, vary it. "Drop-in", "the session as the anchor", and "the layer that fills the gap" each get used once and stay specific.
• Staccato runs. Avoid stacks of short sentences with no variation (for example, "Sessions are durable. They persist. They survive disconnects. They span devices"). Combine some, let others stretch. Rhythm should follow thinking, not a drumbeat.

Patterns to keep

A few patterns are worth keeping when they earn their place. These are counter-rules to the patterns above:

• Fragments are fine when the rhythm asks for one. "No application code needed." is a complete-enough thought.
• Starting a sentence with "And" or "But" is fine sparingly.
• A comma splice that reads well is acceptable.
• Use judgment. If a sentence reads better with a "rule break", leave it. The goal is prose that sounds like a person wrote it.

Layer-0 hook for opening prose

Every page should open with a hook that answers "what is this, why should I care?". The intro: frontmatter feeds the auto-generated page header, and the body's first paragraph reinforces it.

Concept pages: an outcome-claim sentence, then mechanism. Example: "A session is the durable, shared state of a conversation. It outlives any single connection so a user can close their laptop, switch to a phone, or refresh the page without losing the stream."

Feature pages: an outcome sentence followed by a mechanism sentence. Example: "Your users can change direction mid-response. AI Transport's session layer lets a client cancel the in-progress turn and start a new one without breaking the stream."

Both patterns survive review when they sound like a person writing, not a Mad Libs template ("Your users can [X]. The [Y] layer lets [Z].").

Asides

Asides (<Aside data-type='...'/>) carry callouts in MDX pages. Use them sparingly:

• important only for production-blocking issues.
• note for genuine context the reader would otherwise miss.
• new for newly-added features.
• experimental for features still in preview.

Default to no aside; let prose carry the emphasis. Decorative asides get purged on review.

API keys in client code

Never include real API keys in client-side code samples. Use authUrl: '/auth' as the placeholder and link out to the relevant authentication setup page once per document. This applies to every code sample on every page, with no exceptions.

Other considerations

Some additional points to bear in mind:

• Explain the why to the developer. Rather than simply state what a feature or function does, also explain why it is needed.
• Avoid statements that predict the future, for example, "the next version will have feature X". There are good legal reasons for avoiding predicting the future.
• Avoid time sensitive information. Specify an exact version where possible, for example '1.1', rather than 'current version' as the current version may change. Sometimes though you do want to use the terms 'current version' or 'latest version', for example: "The latest version of the Ruby SDK can always be downloaded from its GitHub repository".
• Avoid using ampersand ('&') instead of 'and', unless you are specifying a programming language operator or similar.
• Avoid pricing information in technical documentation as it is subject to change, hard to maintain, and could lead to legal issues if wrong. Instead, direct developers to sales for the latest pricing information.

Examples of writing style guides

Some further examples of writing style guides are:

• Microsft Styleguide
• Microsoft Style for Technical Publications
• Kubernetes
• .NET
• Google's guide on inclusive documentation
• Vonage/Nexmo