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