Writing Style Guide

These are technical writing guidelines that can be used across all Nexmo technical documentation as well as blog posts.

These guidelines are designed to improve clarity and consistency. Some of the benefits of writing in this style are:

As with most guidelines these are suggestions, not hard and fast rules. Use your best judgement.

Use present tense

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

Examples:

Use simple language

Use clear, simple, and direct language. Avoid flowery and verbose writing styles.

Use active voice

Use active voice. In active voice the Subject Verbs the Object. Remember SVO.

Examples:

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

Paragraph breaks

In technical writing, and especially blog posts, you can be a little more generous with your use of paragraph breaks. Paragraph breaks make the text less overwhelming and easier to read.

Avoid vague and cautious language

Avoid words like would, should, might and so on.

Example:

Use second person

Use 'you' rather than 'we' when referring to the reader.

Example:

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

Example:

Use American English

The company standard is, as with most software companies, to use American English.

The industry standard dictionary is Merriam Webster.

Avoid Latin phrases and slang

Latin phrases and abbreviations can sometimes cause confusion. They can also be less convenient to translate.

Examples:

Headings

Try to be consistent with capitalization of headings. You can follow these guidelines:

There is no need to capitalize minor words in headings. For example:

Always capitalize words that would normally be capitalized. For example:

The following shows an example of correct heading case:

Getting Started Guide (top-level topic)
  Overview
    Concepts
    How to send an SMS
    How to use the Installation Guide

Installation Guide
  Configure your Dashboard
  Install the client library
    How to install the Node library
      Clone the source code from GitHub (sub-section heading, not visible in TOC)
    How to install the Python library
      Clone the source code from GitHub (sub-section heading, not visible in TOC)
  Test the installation

Another example demonstrates correct heading case:

Code Snippets  (main section)
  Before you begin
  Connect an inbound call
  Download a recording
  Earmuff a call
  Handle user input with DTMF
  ...

Blog article titles

For Nexmo developer blog article titles, use title case. Blog article sub-headings should also use title case.

You can refer to these guidelines on using title case.

Bulleted lists

This is an example of a bulleted list:

Note the following points:

Codeblocks

When inserting codeblocks for example code in the text:

Acronyms

Define acronyms before first use. On subsequent use on a page/section you do not need to redefine the acronym.

Be explicit

Try to be explicit, that is use precise terms where necessary to improve clarity and avoid ambiguity.

Some examples are given here:

Avoid using 'he or she' constructs

Avoid "He or she" (use user/developer/caller as appropriate). Do not replace 'he or she' by 'they'.

Example:

Miscellaneous

Some additional points to bear in mind:

Replaceable values

When working with keys, phone numbers, or accounts be clear where values should be replaced by customer-specific values.

Key Markdown Value Rendered Value (if different)
Timestamp 2020-01-01 12:00:00 -
ISO8601 Timestamp 2020-01-01T12:00:00.000Z -
Epoch 1577880000 -
HTTP Method [GET] or [POST] GET or POST
HTTP Response `200 OK` or

`404 Not Found`
200 OK or

404 Not Found
Balance 3.14159 -
Latency 3000 -
UUID aaaaaaaa-bbbb-cccc-dddd-0123456789ab -

Numbers

When use of a real phone number can't be avoided, for example when listing out the result of nexmo numbers:list in the CLI, use the following numbers:

US Numbers

Human readable format E.164 format
(415) 555-0100 14155550100
(415) 555-0101 14155550101
(415) 555-0102 14155550102
(415) 555-0103 14155550103
(415) 555-0104 14155550104
(415) 555-0105 14155550105

GB Numbers

Human readable format E.164 format
020 7946 0000 442079460000
020 7946 0001 442079460001
020 7946 0002 442079460002
020 7946 0003 442079460003
020 7946 0004 442079460004
020 7946 0005 442079460005

GB Mobile Numbers

Human readable format E.164 format
07700 900000 447700900000
07700 900001 447700900001
07700 900002 447700900002
07700 900003 447700900003
07700 900004 447700900004
07700 900005 447700900005

Examples of writing style guides

Some further examples of writing style guides are: