Style guide

As Symbol grows as an open source project, more developers will begin to rely on documentation to provide quick and efficient education about the platform. It is thus imperative that a high level of cohesion is achieved across numerous articles on the Symbol Developer Documentation. The following style guide will provide a guideline to improve the consistency and quality of writing from the Symbol technical writing team.

Getting started

Before you start your writing process, here are some things to consider:

  1. Determine purpose and use

    Establishing the purpose of your article should be the first step of your writing process. Determine what you want the readers to know when they finish reading. Defining the objectives will help you with each subsequent step in writing.

  2. Identify the audience and their need

    Keep in mind that the documentation will be mostly read by curious or contributing developers and system integrators, who we should assume to have at least an elementary level of technical knowledge. Determine what information, and how much detail, the readers need to achieve the purpose of your article.

  3. Organize the information

    Once you have determined what information the readers need, organize the information in a logical manner for the best flow and comprehension.

You are now ready to begin writing! Visit this page to learn how to download the project and submit documentation.

Tools

Sphinx: Sphinx is the documentation generator we use to facilitate writing documentation. Its features (extensive cross-references, hierarchical structure, automatic indices, etc) and range of languages make it a useful tool for our purposes.

reStructuredText: Sphinx uses reStructuredText as its markup syntax. reStructuredText is a straightforward yet powerful system that is a major strength of using Sphinx. You can refer to the reStructuredText cheat-sheet for the basics.

GitHub: GitHub is the hosting service we use for our documentation. To commit your contributions, you will need to be familiar with the platform. Beginners can start learning by reading this introduction to Git.

Transifex: Transifex is the collaborative localization platform we use to translate our documentation to various languages. Follow our guide to start contributing to the translations.

Writing patterns

While it is unreasonable to expect all of the many writers on the technical writing team to have an identical writing style, we can attempt to have a consistent voice that resonates with the readers by maintaining a similar writing pattern. Keep in mind these basic rules as you write.

Tone

Do

Don’t

Use American English variant.

Use UK Spelling/grammar: “colo**u**r”.

Be friendly, maintaining a professionalism.

Use too much contractions, slang, colloquialism, buzz words, excessive exclamation marks.

Use active voice & present tense by default.

Use passive voice.

Address the reader as “you” by default. Use “we” as the default pronoun in your article unless you are referring to a personal recommendation.

Use “you” to describe an action the user has to do.

Write documentation for an international audience, with diversity and inclusivity in mind.

Include culturally or politically controversial ideas or examples.

Be Concise.

Use long sentences or filler words in excess (“simply”, “really”, “just”, “please”).

Basic formatting

Maintaining a uniform format is also essential for consistency.

Case

Example

Defining new or important vocabulary.

Private Key is a random 256-integer.

Emphasizing important differences.

If valid, the harvester stores the transaction in a block, and it reaches the confirmed status.

Writing headers for a table.

This table.

Writing titles.

Basic formatting (first letter capitalized).

Writing numbers

1,000.5. Use the period (full stop) as the decimal separator.

Referencing variable values, functions, file names, mosaic ids, addresses or urls.

Symbol has a rewrite limit of 360 blocks. Once a transaction has more than 360 confirmations, it cannot be reversed.

Warning the reader.

Use notes. Example

Providing helpful hyperlinks throughout your article.

transfer transactions are used to send mosaics between two accounts.

Explaining a difficult concept with many steps.

Break information and actions into bulleted or numbered lists when possible.

Code snippets

Common practices to include code snippets in a document.

Case

Example

Documenting bash commands.

Do not add $> before bash commands: symbol-cli account info.

Using code snippets.

Import them from a file using the .. viewsource:: directive. Example

Displaying a subset of the code

Use the comments /* start block 01*/ and /* end block 01 */ to divide code blocks. Example

If you are writing a guide, you might find helpful this guideline.

Terms

List of terms that are prone to be written in different ways.

Correct

Incorrect

API

Api, Api

blockchain

block chain

Catapult

catapult, NEM Catapult

CLI

cli, Cli

GitHub, github, Github

id

ID

JavaScript

Javascript, javascript

MongoDB

mongodb, Mongodb

NEM

Nem, nem

Node.js

nodejs, node.js

RxJS

rxjs

SDK

Sdk, Sdk

SHA-256

SHA256, Sha-256

Smart Asset System

Smart asset system

Symbol

symbol, NEM Symbol

TransferTransaction

Transfer Transaction, transfer transaction

TypeScript

typescript, Typescript

Whitepaper

WhitePaper