Skip to content

Commit

Permalink
Added basic writing guideline summary
Browse files Browse the repository at this point in the history
  • Loading branch information
stoobie committed Jan 17, 2024
1 parent 98288d1 commit 310dbe6
Showing 1 changed file with 22 additions and 0 deletions.
22 changes: 22 additions & 0 deletions contributing_to_docs/doc_guidelines.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,28 @@ All Starknet documentation should conform to the same rules and guidelines, as d

toc::[]

[#basic writing guidelines]
== Basic writing guidelines

* Avoid the passive voice, use the active voice. Only use the passive voice as a last resort. Most of the time you can write with the active voice.
* Make it easy to scan
** Use helpful titles and headings
** Lists
** Tables
* By default, use the second person imperative _You_, not third person, _The user_. +
Talk _to_ your reader, not _about_ them.
* Be consistent, use the same word to refer to a thing in different sentences.
* Use the present tense, not the future. For example:
+
> To create a Signer you +++<del>+++*will*+++</del>+++ need the private key.
* Don’t use slang.
* Don’t refer to programmatic names as words.
* Don’t use Latin (e.g. and i.e.).
* Avoid quotation marks except for actual quotes.
* Avoid ambiguous words, like _may_. Use _might_ or _can_, depending on your intent, instead of _may_.
* Avoid complex words, use simple words where possible.
* Avoid using parentheses, except as labels.

== Adding files to the collection

When you create new files, you must add them to the `components/Starknet/modules/<module>/nav*.adoc` file so that the build system can render them in the table of contents.
Expand Down

0 comments on commit 310dbe6

Please sign in to comment.