Skip to content

Latest commit

 

History

History
384 lines (289 loc) · 17.3 KB

style-guide.md

File metadata and controls

384 lines (289 loc) · 17.3 KB

Dev Docs Style Guide

Overview

This guide outlines the format, language, and style that should be used when contributing pages to the BigFile developer documentation. This is designed to assist with standardizing the documentation to create a cohesive, uniform look and feel across all pages of documentation that have been contributed by multiple individuals and teams.

This guide will outline the following:

  • Page structure.
  • Use of page headings.
  • Use of capitalization.
  • Documentation language, spelling, grammar, and word choice.
  • Use of punctuation.
  • Bulleted lists.
  • Bold text.
  • Italic text.
  • Hints.
  • Links and hyperlinks.
  • Code snippets and code blocks.
  • Command line syntax.
  • FAQ sections.

Page structure

The developers docs contain a wide variety of different document types, such as overview pages, concept pages, feature pages, tutorials, and reference pages. For this reason, the page structure will vary based on what type of document the page is.

The following example template can be used:

---
keywords: [keyword1, keyword2, keyword3]
---

import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";

# Page title

<MarkdownChipRow labels={["label1", "label2", "label3"]} />

## Overview

Introduce the feature or tool. What is it? Give a brief overview of how it works, but keep it very high level. Link to additional documents that explain the in-depth concepts behind it (if they exist). 

## Prerequisites

Optional; only necessary for documents that require prerequisite conditions or parameters be met.


## Topic 1

What is the first topic that the developer should be introduced to? If the tool has several workflows, which should be introduced initially? Is there an initial configuration required? 

### Subtopic 1

Include any information about a subtopic of Topic 1 here. This may include nuances with Topic 1 or best practices that should be noted. 

## Topic 2

Introduce the second topic. 

This is optional; there may be only one primary topic within the feature. Use your best judgement for what topics and subtopics your document may need. 

## Topic 3

If your document includes a step-by-step walkthrough, introduce the walkthrough as a topic, then use the following format:

- #### Step 1: Description of step for reader to take.
- #### Step 2: Description of step for reader to take.
- #### Step 3: Description of step for reader to take.

## Resources
- [Link](link.com)

Page headings

There are 4 types of headings used throughout the BigFile developer docs:

  • Heading size 1: #
  • Heading size 2: ##
  • Heading size 3: ###
  • Heading size 4: ####

Heading usage

Heading size Usage
Heading 1 Page title only; not used within the page's content.
Heading 2 Used for primary topics amongst the page; used for consistent page headings such as 'Overview', 'Prerequisites', 'Conclusion' and 'References'.
Heading 3 Used for subtopics under primary topics amongst the page or user steps within a tutorial. Note; there are some instances where using Heading 2 for a tutorial step is more fitting, such as when a step contains several different concepts or subtopics. Please refer to the writing a tutorial section below for further information.
Heading 4 Used for listing steps a user should take within a guide document, where the guide document includes several different, separate walkthroughs for the user to follow; in this scenario, this heading should be used in conjunction with a bullet point. Heading 4 is also used for listing terms within the glossary document page and for subtopics under an already existing Heading 3 subtopic heading.

Heading usage example

The following is a sample guide document that showcases how the 4 types of headings should be used:

# File management

## Overview

This document describes basic file management workflows.

### Workflows covered

The following workflows are covered:
- Creating a file.
- Saving a file.

## Prerequisites

- [x] Download and install a text editor program.

## Creating a file

To create a new file:

- #### Step 1: Open the text editor program.
- #### Step 2: From the navigation bar, select **File** then **New File**.
- #### Step 3: Enter text into the new, blank file.

## Saving a file

To save a file:

- #### Step 1: From the navigation bar, select **File** then **Save**.
- #### Step 2: Enter a file name to save your file under.
- #### Step 3: Confirm the file name and select **Save**.

## Conclusion
This document described basic file management workflows.

## Resources
- [Link](link.example)

Prerequisites sections

For guides or tutorials that include a prerequisites section that contains tasks a reader must complete before starting to follow the guide or tutorial, the following format should be used:

Prerequisites

  • Download and install a program.
  • Download and install a package.
  • Download and install a framework.

Capitalization

Capitalization within the developer documentation should follow these outlined standards:

  • Only the first word of a title should be capitalized unless the title includes a proper noun.
    • Example: How to use the BigFile
    • Example: Using BIG ID with a dapp
    • Example: Motoko reference guide
  • Only the first word of a page heading should be capitalized unless the title includes a proper noun.
    • Example: Overview
    • Example: Register, build, and deploy the dapp
    • Example: Using Motoko cubes
  • Titles of links to other documentation pages or external articles, such as blog posts, should not be capitalized except for the proper nouns within the title.
  • Any reference to specific GUI buttons or other visual aids that are capitalized within the referenced interface should be capitalized to match the format shown on the GUI.
    • Example: Open your account and navigate to My Products.
    • Example: Click on the Save button.
    • Example: Select Add site to save the configuration.
  • When a bullet point list begins with a sentence, the first word in the sentence should be capitalized:
    • Example: Step 1: First, you need to look up the IP addresses of the boundary nodes.
  • When a bullet point list is used to define terms, the first word after the term should not be capitalized:
    • Example: Term: definition of the term.
  • When a code-specific value, such as the name of a method, variable, integer, or data type, is being referenced, the capitalization used within the code or the language's reference documentation should be followed.
    • Example: ConstructionPayloadRequest
    • Example: ingress_start

Proper nouns

The following proper nouns should always be capitalized:

  • Blockchain Singularity
  • BigFile
  • BigFile Foundation
  • BigFile
  • BigFile Protocol
  • BIG ID
  • JavaScript
  • NodeJS
  • README
  • Rust
  • Service Nervous System
  • TypeScript
  • WebAssembly (Wasm)
  • Wiki
  • YouTube

This is not an exhaustive list, and other proper nouns such as tool names, company names, or project names should be capitalized. Examples of these are Unity, Godot, Namecheap, GoDaddy, and GitHub.

Abbreviations and acronyms

The following is a list of common abbreviations that are capitalized within the developer docs:

  • BTC
  • SDK
  • DAO
  • DeFi
  • ECDSA
  • HTTP/HTTPS
  • BIG
  • NFT

Language

The following language and capitalization of certain terms and phrases should be used across the BigFile developer documentation:

  • Big Tech

  • built on BIG

  • smart contract

  • chain-key signature

  • chain-key cryptography

  • dapp: should be used in place of any reference to an BigFile app, decentralized application, or 'dApp'.

  • DeFi

  • deployed on BIG

  • HTTP outcalls

  • BIG: When abbreviating 'BigFile', it should be referred to as 'BIG' instead of 'BIG' or 'the BIG'. Two exceptions to this are:

      - The BIG SDK, which should be referred to as 'the BIG SDK'.

  - The BIG interface specification, which should be referred to as 'the BIG specification' or 'the BIG interface specification'.

    When there may be a confusion between BIG referring to BigFile Protocol and BIG the token, the words 'BigFile Protocol' can be written out for clarity.

  • BIG SDK: should be used in place of any reference to the BIG's SDK.

  • mainnet

    • In context: Deploying to the mainnet or on the mainnet. Note the use of the word the.
    • Other contextual usage:
      • The dapp has been deployed to the mainnet.
      • Before deploying on to the mainnet... Additionally, mentions of the Bitcoin mainnet should use the same structure (prefaced with the word the.)

  • multi-chain

  • neuron

  • node provider

  • reverse gas model

  • Sybil resistance

  • Sybil attack

  • Web3

  • World Wide Web

Spelling, grammar, and word choice

The following spelling, grammar, and word choice rules should be followed:

  • Avoid using language that uses 'we' or 'us'; use a protocol point of view, such as phrases like, "the protocol ensures", "the protocol does", and “it is explained” rather than “we explain”. This is to help make clear that BIG is a protocol that is community-controlled and autonomously governed. - An exception to this is the Developer Blog; blog posts are written using a different style for a different audience, and using 'we' or 'us' in this context is acceptable.

  • Do not refer to the BigFile as a system or a platform. Say "BigFile" or "protocol" instead.

  • Regarding spelling and grammar, American spelling and grammar should be used with the exception that all article titles follow British capitalization rules (see details in the Capitalization section.)

  • Assure that the language in the document reads well for non-native English speakers, and avoid phrases or sayings that may be confusing, such as "Dig in."

  • Avoid informal, personal thoughts or otherwise unnecessary language within the developer docs. A few examples of this might be:

    • Referring to the default configuration as the 'boring default configuration'.

    • Making a joke within the document, then using parentheses to acknowledge the joke such as "(Get it? heh)".

    • Avoid speaking directly to the reader, unless within a tutorial that is designed to be an interactive, onboarding experience.

    For example, avoid the following:

    • "Get it? heh."
    • "Take a deep dive."
    • "Go down the rabbit hole."
    • "Dig in."

    Whereas, the following are acceptable in certain contexts:

    • "Ready to get started? Let's go!"
    • "Here is a checklist of the things you will need to consider:"

Numbers

Numbers should be formatted using the _ character, and not any other character. For example:

  • 44_760_000
  • 54_000
  • 1_000

API methods

For API methods such as GET, POST, PUT, DELETE, HEAD, or any other API method requests, they should be formatted as such:

  • In headings, they should be capitalized without additional formatting.
    • Example: "Using HTTP GET calls."
    • Example: "Using HTTP PUT calls."
  • In the body of documents, they should be formatted as in-line code, such as:
    • Example: "A minimal example to make a GET HTTPS request."
    • Example: "That is, the canister could define the quorum size to be 1 and have only 1 replica execute the POST request."

Punctuation

The following punctuation standards should be followed:

  • All sentences end in a period.
  • Exclamation points can be used where appropriate, but should not be used excessively.
  • Question marks can be used where appropriate.
  • Semicolons (;) should be used to indicate a pause within a sentence.
  • Parentheses should be used to include additional context where appropriate.
  • All bullet point lists should be prefaced with introduction text followed by a colon.
  • All items within a bullet point list should end in a period, regardless if the entry is a full sentence or not.
  • All numbered lists should use the format 1. for numbering each list entry.
  • All user steps for tutorials should use the format Step 1: to preface each step's contents.

Bulleted lists

The following bullet point format and standards should be followed:

  • Bullet point lists can be written using either the - character or the * character; they both display the same on the webpage.
  • Bullet point lists that define a term or technology should follow the format:
    • Term: definition of the term.
  • Bullet point lists that are used to indicate user steps for a guide should use the format:

    • Step 1: Description of step

  • Bullet point lists that contain subtopics or sub-points should use the format:
    • Bullet point 1.
      • Subtopic bullet point.
    • Bullet point 2.

Bullet points should end in a period unless otherwise specified. An exception to this is the Developer Journey index pages. Bullet points indicating the title of subpages (0.1 Introduction to the BigFile, 0.2 BigFile terminology, etc) intentionally do not end in a period.

Numbered lists

The following numbered list format and standards should be followed:

  • Numbered lists should be used to outline architecture steps that describe what happens within the backend or frontend of a tool or service, where it does not describe steps that a user interacts with directly.
    • For example, steps that detail how a service interacts with a client application should be explained using a numbered list, whereas steps detailing how a user can interact with the client application should be listed as guide or tutorial steps that use the correct heading sizes and format.
  • Numbered lists should also be used when presenting a list of questions to the reader to provoke their thoughts. For example:
    1. Which WebAssembly (Wasm) code is being executed for a canister?
    2. The canisters are normally written in a higher-level language, such as Motoko or Rust, and not directly in Wasm. The second question is then: is the Wasm that’s running really the result of compiling the purported source code?

Bold text

The following standards for bold text should be followed:

  • Bullet point lists that are used to list and define terms should bold the term(s) being defined.
    • Term: definition of the term.
  • Terms that are important for the reader to understand, such as a term found in the BIG glossary, should be bolded for emphasis.
  • When describing steps for a user to follow in a guide or tutorial, if the user is expected to interact with a button or GUI interface, the button's name should be bolded and follow the capitalization format found on the GUI.
    • Example: Click on the Save button.

Italic text

Italic text is not used within the BIG developer documentation. Bold text should be used to emphasis terms or phrases that are important.

Hints

The BIG developer documentation uses two forms of hints provided by the Docusaurus framework:

  • Info: the info hint is used to provide important information that the reader should be prompted to read. This hint can be used to provide additional context, resources, or add important notes that the reader should be aware of before continuing.
  • Caution: the caution hint is used to provide a warning to readers about the consequences of certain steps or actions as indicated in the guide, doc, or tutorial.

Hints can be used with the following markdown format:

:::info Info hint :::

:::caution Caution hint :::

Links

Links that are referenced within the developer docs should use the following format and structure:

Code snippets and code blocks

The following format should be used for code snippets and code blocks:

  • In-line code references to commands, language specific methods, or other code-related terms should be emphasized using in-line code expressions such as:
    • To install code in a canister, the install_code function of the BigFile is used.
    • For example, the function canister_init is the first function that gets called after the code is installed for the first time.
  • When a code-specific value, such as the name of a method, variable, integer, or data type, is being referenced, the capitalization used within the code or the language's reference documentation should be followed.
    • Example: ConstructionPayloadRequest
    • Example: ingress_start
  • Command-line commands that should be run by the user should be listed in their own line using code formatting, such as:

    • Step 1: Install the React module by running the following command:

              npm install --save react react-dom

FAQ sections

Frequently asked question (FAQ) sections should use the following structure and format:

## Frequently asked questions

- #### Question 1?
Answer

- #### Question 2?
Answer