Skip to content

Latest commit

 

History

History
141 lines (95 loc) · 5.92 KB

starknet_docs_style_guide.adoc

File metadata and controls

141 lines (95 loc) · 5.92 KB
Raw

Starknet documentation supplementary style guide

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.
Table of Contents

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.

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.

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.

T

transaction

The default is to use the full word transaction in normal text. You can use tx as an abbreviation for the word transaction if it improves readability.

Reasoning: This abbreviation is well known in the industry.