-
Notifications
You must be signed in to change notification settings - Fork 341
Documentation style guide
For structure, use the principles of topic-based authoring.
For general text guidelines, consult with The Chicago Manual of Style.
Use an em dash without spaces.
Example: Chainstack—a platform to manage decentralized networks and services—is actually the easiest to use.
Use an em dash with spaces.
Example:
- Ethereum — a public distributed computing platform.
- Corda — a permissioned business platform.
- 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
- Decoded
vout:0
Use bold to denote UI elements.
Example: To see project members, click Members.
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**.
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
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.
Use full links only for external resources.
Use /path/section to crosslink a word to a level one heading from a different section.
Example: [word](/path/section)
Use /path/section#heading to crosslink a word to a non-level one heading from a different section.
Example: [word](/path/section#heading)
Use #heading to crosslink to a section on the same page.
Example: [word](#heading)
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."
This is a pure consistency nitpick and preference.
Use curl https://user-name:pass-word-pass-word-pass-word@nd-123-456-789.p2pify.com for authenticated curl requests.
Example: curl https://user-name:pass-word-pass-word-pass-word@nd-123-456-789.p2pify.com
Example to avoid: curl https://nd-123-456-789.p2pify.com -u "user-name:pass-word-pass-word-pass-word"
Use logically numbered id: values for requests.
Example:
- Step one:
command: id:1 - Step two: No command in step two.
- Step three:
command: id:2 - Step four:
command: id:3
If a request is independent, default to id:1.
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
- Correct:
syncing,synced - Incorrect:
synching,synched
Merriam-Webster also prefers sync.
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.
Use [Chainstack account](link) to link to console.chainstack.com.
Use [Chainstack](link) should be for chainstack.com.
Do not mix these two.
Use the word directory.
Do not use the word folder.
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'.
Avoid using & unless the ampersand is a part of an official name.
Use a markdown linter before pushing your documentation code.