Docs Style Guide

Technical docs are a 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. Contributions are welcome and appreciated.

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, and currently.

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.

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.

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.

Callouts

Use this Callout syntax.

You can update the callout headline, but not the callout icon.

• Danger Use for security warnings. For example, where failure to take x action can result in a security vulnerability (for example, loss of funds or XSS attack). For example, "Always validate user-provided data to prevent XSS attacks."

  

• Caution Do not use.

  

• Info Use for limitations and "must know" information.

  

• Note Use for general and "nice to know" information.

  

• Tip Do not use, mostly because of the green color.

  

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.