Skip to content

Docs Style Guide

Jump to bottom
Barrie Byron edited this page Apr 10, 2023 · 21 revisions

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:

Terminology

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

Sidebar Capitalization

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

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."

    danger

  • Caution Do not use.

    caution

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

    info

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

    note

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

    tip

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 space between the number and the unit of measurement. For example, 128 GB.

Use standard unit of measure abbreviations:

  • B bytes
  • kB kilobyte
  • KiB kibibytes
  • MB megabyte
  • MiB mebibyte
  • GB gigabyte
  • GiB Gibibyte
  • TB Terabyte
  • TiB tebibyte

Unit of Measure Bytes

Kilobyte (kB) 1,000¹ = 1,000 Megabyte (MB) 1,000² = 1,000,000 Gigabyte (GB) 1,000³ = 1,000,000,000 Terabyte (TB) 1,000⁴ = 1,000,000,000,000 Petabyte (PB) 1,000⁵ = 1,000,000,000,000,000

Unit of Measure Bytes

Kibibyte (KiB) 1,024¹ = 1,024 Mebibyte (MiB) 1,024² = 1,048,576 Gibibyte (GiB) 1,024³ = 1,073,741,824 Tebibyte (TiB) 1,024⁴ = 1,099,511,627,776 Pebibyte (PiB) 1,024⁵ = 1,125,899,906,842,620

For other guidance on units of measure, follow the Microsoft style guidelines.

Mina Docs

Clone this wiki locally