Docs Style Guide

Technical docs are a high visibility way to connect with our users. Consistent, accurate, and error-free docs build trust.

In general, we use the Google developer documentation style guide and document the exceptions here.

Our product development cycle includes creating, updating, and maintaining content for each feature and update. Contributions are welcome and appreciated.

• For the preferred spelling of common terms, see the Word List.
• For advanced Markdown syntax, see Markdown Syntax.

For guidance not on this page, refer to these style guides:

• Google Developer Documentation Style Guide
• Microsoft Style Guide

Terminology

To ensure consistency in the documentation, be sure to follow the preferred usage of common terms. See the Word List.

Highlights

This list covers important points. For more information about topics on the page, follow the links. As always, please ask if you have questions.

Tone and Content

• Be conversational and friendly without being frivolous.

• Don't pre-announce anything in documentation.

• In general, use present tense rather than future tense; in particular, try to avoid using will where possible.

• Use short descriptive link text that helps provide context for the material that you're linking to.

• Write timeless documentation that avoids words and phrases that anchor the documentation to a point in time or assume knowledge of prior or future products and features. Words to avoid: now, new, soon, not yet, latest, future, and currently.

• Swap formal words for normal ones:

  • Assistance - Help
  • Commence - Start
  • Enable - Let
  • Ensure - Make sure
  • Further - More
  • However - But
  • In order to - To
  • Obtain - Get
  • Provide - Give
  • Request - Ask
  • Require - Need
  • Resolve - Fix
  • Therefore - So
  • Utilize - Use

Language and Grammar

• Write for a global audience.
• Use second person: "you" rather than "we."
• Use active voice: make clear who's performing the action.
• Use standard American spelling and punctuation.
• Use serial commas.
• In general, in cases where American spelling differs from Commonwealth/"British" spelling, use the American spelling.

Syntax Conventions

• Put UI elements in bold.
• Enclose methods and functions in single tick marks and include the parentheses. For example, init() method, add() method.
• Make sure that the spelling of a class name matches the spelling in the code, with capital letters and no spaces. For example, accountUpdate: AccountUpdate; where accountUpdate is for the JavaScript code and AccountUpdate is the class in SnarkyJS that represents account updates instructions for the Mina network.

For more syntax guidance, see Markdown Syntax.

Sidebar Capitalization

• Use Title Case Protocol Architecture
• Use sentence case for tasks and phrases--for example, How to use a zkApp, Install a wallet

Tip: Use a Title Capitalization tool.

Graphics

• Graphics are created using an iPad, stylus, and Procreate.
• By convention, images are stored in the static/img folder.

Units of measurement

Use a non-breaking space between the number and the unit of measurement. For example, 128 GB. Use standard unit of measure abbreviations. Follow the Microsoft style guidelines.