Skip to content
This repository has been archived by the owner on Apr 10, 2023. It is now read-only.

Documentation style guide

Ake Gaviar edited this page Jan 11, 2021 · 3 revisions

General

For structure, use the principles of topic-based authoring.

For general text guidelines, consult with The Chicago Manual of Style.

Em dash

In a sentence

Use an em dash without spaces.

Example: Chainstack—a platform to manage decentralized networks and services—is actually the easiest to use.

In a bullet list

Use an em dash with spaces.

Example:

  • Ethereum — a public distributed computing platform.
  • Corda — a permissioned business platform.

Bullet lists

  • List item — lowercase.
  • DOCS-LEVEL-VARIABLE — lowercase.
  • code-level-variable — lowercase.

If the list item is not a parameter explanation, but a parameter value then use : instead of an em dash :

  • Parameter name/explanation parameter: value

Example:

  • Decoded vout: 0

UI elements

Use bold to denote UI elements.

Example: To see project members, click Members.

UI clickthrough

Use > to denote clicking through UI elements.

Example: To invite a member to the project, click Members > Invite member.

Note that only the UI elements are in bold, and the right angle bracket is not a UI element.

Full markdown code: To invite a member to the project, click **Members** > **Invite member**.

UI as a word

Never use UI as a word when providing instructions for the Chainstack console. Instead, use Chainstack.

  • Correct: On Chainstack, navigate to your vault
  • Incorrect: In the platform UI, navigate to your vault

Linking

Avoid one-word linking.

Always link a meaningful word or a phrase that relates to the link. When you can, choose to link a phrase over a word.

Example: See Getting set up for CorDapp development

Example to avoid: See Getting set up for CorDapp development here.

Crosslinking

Use full links only for external resources.

Cross-topic

Use /path/section to crosslink a word to a level one heading from a different section.

Example: [word](/path/section)

Cross-section

Use /path/section#heading to crosslink a word to a non-level one heading from a different section.

Example: [word](/path/section#heading)

In-section

Use #heading to crosslink to a section on the same page.

Example: [word](#heading)

Quotation marks and punctuation

Punctuation in a sentence that ends with quotation marks always goes inside the quotation marks.

Example: For the quotation and punctuation use, we are following the American English style—"put the full stop inside the quotation."

Authenticated curl requests

This is a pure consistency nitpick and preference.

Use curl https://user-name:[email protected] for authenticated curl requests.

Example: curl https://user-name:[email protected]

Example to avoid: curl https://nd-123-456-789.p2pify.com -u "user-name:pass-word-pass-word-pass-word"

Using id: in requests

Use logically numbered id: values for requests.

Example:

  1. Step one: command: id:1
  2. Step two: No command in step two.
  3. Step three: command: id:2
  4. Step four: command: id:3

If a request is independent, default to id:1.

Word forms of cancel

Use American English (AmE) for word forms of cancel.

Avoid using British English (BrE).

Canceling:

  • AmE: Canceling
  • BrE: Cancelling

Canceled:

  • AmE: Canceled
  • BrE: Cancelled

Cancellation:

  • Both AmE and BrE: Cancellation
  • Always incorrect: Cancelation

Word forms of sync

  • Correct: syncing, synced
  • Incorrect: synching, synched

Merriam-Webster also prefers sync.

Currency vs. protocol in naming

Use lowercase for currency and uppercase for protocol.

Bitcoin example:

  • Currency: bitcoin
  • Protocol Bitcoin

Ethereum example:

  • Currency: ether
  • Protocol Ethereum

Avoid using ETH or Ether.

Linking the words Chainstack and Chainstack account

Use [Chainstack account](link) to link to console.chainstack.com.

Use [Chainstack](link) should be for chainstack.com.

Do not mix these two.

Directory vs. folder

Use the word directory.

Do not use the word folder.

Consortia vs. consortiums

Use consortia for the plural form of consortium.

Both consortia and consortiums are accepted terms, with some dictionaries leaning towards consortia. That said, in the rare case that one has to use a possessive, then consortia's wins over consortiums'.

Using ampersand &

Avoid using & unless the ampersand is a part of an official name.

Linting

Use a markdown linter before pushing your documentation code.