Skip to content

Latest commit

 

History

History
200 lines (154 loc) · 6.99 KB

starknet_docs_style_guide.adoc

File metadata and controls

200 lines (154 loc) · 6.99 KB
Raw

Starknet documentation supplementary style guide

Table of Contents

This guide provides style guidelines and preferred term usage for the Starknet website, including docs.starknet.io. Use it as a supplement to the following style guides:

How to use this guide

When looking for style guidance and writing guidance, use these guides in the following order:

Starknet documentation supplementary style guide

Reference this guide first. It provides guidance that is specific to Starknet documentation. This guidance either supplements or, in specific cases, overrides the other style guides.
Red Hat supplementary style guide for product documentation

Provides additional guidance or overrides guidance in the Google developer documentation style guide.
Google developer documentation style guide

The primary source of style guidance for Starknet documentation.

If you cannot find helpful information or if you must deviate from the guidance in any of these guides, open an issue for this style guide. The stakeholders can then discuss and determine how to address the issue.

Related guides

The following reference guides for technical writers provide technical information on AsciiDoc, the markup language we use to author the Starknet technical documentation:

AsciiDoc Language Documentation

documentation for the AsciiDoc language as it’s implemented in Asciidoctor.
AsciiDoc Mark-up Quick Reference

Guidance specific to writing in AsciiDoc. Includes links to complete documentation for AsciiDoc and Asciidoctor.

Titles and section headings

Guidelines for writing headings

  • Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.

  • Be as descriptive as possible with the title or section headings without making them unnecessarily long.

  • For procedural topics, use a gerund form in headings, such as:

    • Creating

    • Managing

    • Using

  • For conceptual topic titles, see Headings and titles in the Google developer documentation style guide.

  • For Reference topic titles, use a title beginning with a noun that describes the content, such as:

    • Compiler command reference

    • The name of a command/programming element, such as starknet get_block.

    • System calls

    • For more examples, see Reference module examples in the Modular documentation reference guide.

Guidelines for headings as structural elements

  • Use only one level 1 heading (=) in any file.

  • For subsequent heading levels, avoid using a single heading for each level. For example, if you have one heading 2 you should add another heading 2.

    Headings generally separate ideas on a page, so usually a heading indicates a new idea, which logically presupposed a heading for the first idea. Sometimes implementing this guideline requires restructuring the page.

Example of what to do

  • H1: Applying to join the bar

  • H2: Pass law school

  • H3: Study all day

  • H3: Study all night

  • H2: Pass the bar exam

  • H3: Learn all the laws

  • H3: Register for the exam

Example of what not to do

  • H1: Applying to join the bar

  • H2: Pass the bar exam //Notice this is the only H2

  • H3: Pass law school //Notice this is the only H3

  • H4: Study all day

  • H4: Study all night

  • H4: Learn all the laws

  • H4: Register for the exam

Links to external websites

If you want to link to a third-party website:

  • Do not create a hyperlink.

  • Use the site top level URL as text.

  • Provide the title of the page to search for on the site.

Example
For more information, see _A specific page_ at \http://www.example.com/.

A hyperlink to a page on a third-party website is convenient and user-friendly as long as the link works. The problem is that a third-party site can move pages without notification, in which case that user-friendly link can become a user-unfriendly broken link, and broken links also impact our search engine rankings.

Glossary

Deprecated

Refers to a feature or capability that is still supported, but support will be removed in a future release of Starknet. Future fixes or enhancements are unlikely. If necessary, an alternative is available.

Fri

The smallest unit of the Starknet native token, STRK, equal to 10-18 STRK.

G-fri

1,000,000,000 fries.

Removed

Refers to a feature or capability that has been entirely removed.

Unsupported

Refers to a feature or capability that is no longer supported.

Word list

If a term doesn’t appear here, refer to the following guides, in order:

  1. Glossary of terms and conventions in the Red Hat supplementary style guide for product documentation.

  2. Word list in the Google developer documentation style guide.

E

EIP-<num>, ERC-20

Correct form: EIP-<num>

Example: EIP-4844

Incorrect forms: EIP4844, EIP 4844

Reasoning: This is the convention used on ethereum.org.

F

fri (10-18 STRK)

Correct forms

  • Singular: Fri

  • Plural: Fries

Usage rule

Normal word casing, so use Fri at the beginning of a sentence, and fri after the first word of a sentence.

Examples

  • Alice holds 5 million fries.

  • Fri is the smallest unit of STRK.

G

G-fri (1,000,000,000 fries)

Correct forms

  • Singular: G-fri

  • Plural: G-fries

Usage rule

Normal word casing, so use G-fri at the beginning of a sentence, and g-fri after the first word of a sentence.

Examples

  • Alice holds 5 million g-fries.

  • G-fri is a unit that is equal to one billion fries.

O

offchain

Correct form: offchain

Incorrect forms: off-chain, off chain

Reasoning: Align with trending industry usage.

onchain

Correct form: onchain

Incorrect forms: on-chain, on chain

Reasoning: Align with trending industry usage.

S

Starknet Core Contract

Correct form: Starknet Core Contract

Incorrect forms: Starknet core contract, Starknet Core contract

T

transaction

Correct form: transaction, transactions

Avoid: tx, txs

Reasoning: Although this abbreviation is well known in the industry, we avoid abbreviations. Abbreviations present a barrier to first-time readers and can also interfere with localization.