From 6493a5d50a03d4efa04dc2ff2dac94a394d20ed6 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Fri, 29 Dec 2023 11:09:36 -0500 Subject: [PATCH 1/7] first draft of a style guide --- docs/reference/style-guide.md | 107 ++++++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 108 insertions(+) create mode 100644 docs/reference/style-guide.md diff --git a/docs/reference/style-guide.md b/docs/reference/style-guide.md new file mode 100644 index 000000000..af1af9b36 --- /dev/null +++ b/docs/reference/style-guide.md @@ -0,0 +1,107 @@ +--- +title: Documentation style guide +authors: Tim McMackin +last_update: + date: 29 December 2023 +--- + +## Overall Tezos-related issues + +- Tezos is decentralized. +There is no official Tezos documentation, no official Tezos strategy, and no official entity in charge of Tezos. + +- Do not compare Tezos to other blockchains. + +- Use "tez" to describe the currency instead of "XTZ" unless there is a specific reason to use the ISO code/ticker symbol "XTZ," such as in accounting systems, exchange rates with other currencies, and anything that needs a standardized code. + +- Avoid using the ęś© glyph in text. + +- Do not use the term "initial coin offering (ICO)" or refer to Tezos "investors." +Instead, refer to the Tezos fundraiser. +See https://tezos.gitlab.io/user/key-management.html#getting-keys-for-fundraiser-accounts. + +## Blockchain terminology + +- Clients that send transactions to contracts are called "senders." + +- The fields in a contract's storage are called "properties." + +- Don't use abbreviations for layers, as in "l1" or "l2." Say "layer 1" or "layer 2." + +## Capitalization + +Use sentence case for headings, such as "Connecting to wallets." + +Capitalize these terms in text: + +- Tezos +- Smart Rollups +- Specific network names such as Mainnet, Ghostnet, Dailynet, and Mumbainet +- Sapling +- JSON +- Web3 + +Capitalize the "A" in "dApp." + +Do not capitalize these terms unless they are the first word in a sentence or if the capitalization style requires all major words to be capitalized: + +- tez +- blockchain +- proof of stake +- proof of work +- smart contract +- testnet + +## Emphasis + +Use emphasis sparingly to avoid making the page too visually busy or complex. + +- Use backticks for file names, variable names, and command names, not to emphasize words or denote technical terms. + +- Use bold for: + + - Buttons or links that the user must click or interact with + + - Very sparingly, to highlight important words and phrases, such as the words at the beginning of a definition list, such as in the [Glossary](../overview/glossary) + +- Do not emphasize the names of web sites, pages, or UI elements that the user sees but does not interact with directly + +- Use [admonitions](https://docusaurus.io/docs/markdown-features/admonitions) such as notes or warnings sparingly, only to denote warnings and critical issues + +- Avoid parenthetical expressions + +## Style and clarity + +- Use terms and phrasings that are clear to people using translation or to non-native speakers of English. + +- Use gender-neutral terminology. + +- Use the same word to represent something, instead of varying words for variety. +For example, use "stake" consistently and do not substitute synonyms such as "deposit" and "retainer" to refer to the same thing. + +- Do not use "as" or "since" to mean "because," as in "The system shows an error, as you have not connected your wallet yet." + +- Do not use "once" to mean "after," as in "Once the system shuts down, you can safely remove the drive." + +- Avoid Latinate abbreviations like e.g. and i.e. + +- Provide the information about the target of a link. +For example, instead of saying "for information about smart contracts, click [here](https://docs.tezos.com/smart-contracts)," say "for information about smart contracts, see [Smart contracts](https://docs.tezos.com/smart-contracts)." +When linking to an external site, consider mentioning the target site, as in "for more information, see [Blockchain basics](https://opentezos.com/blockchain-basics) on opentezos.com. + +- Do not describe documentation in terms of "chapters" or "articles." + +- Avoid meta-phrases that make the documentation sound like a lecture or textbook, such as "we will see" and "the goal of this information is to." + +- When writing steps that the user must follow, make it clear what the user must do by following these guidelines: + + - Make each action that the user does a numbered step. + + - Cover the action that the user does in the first sentence. + + - Use language that makes it clear that the user must do something and what that action is. + For example, instead of "4. In the file `myFile.js`:", say "4. Add this code to the file `myFile.js`." + +- Structure lists and headings in a parallel way. + For example, make sure each list item is capitalized and punctuated in the same way. + List items should be all complete sentences or all sentence fragments, not a mix. diff --git a/sidebars.js b/sidebars.js index 624a63a2d..6698dd8d5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -205,6 +205,7 @@ const sidebars = { // 'reference/encoding', // TODO // 'reference/merkle-formats', // TODO // 'reference/ocaml-apis', // TODO + 'reference/style-guide', { type: 'link', label: 'Whitepaper', From 53a3478cd887c8882d82cf421d5d7593541cb041 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 3 Jan 2024 14:09:43 -0500 Subject: [PATCH 2/7] consistency in lists --- docs/reference/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/style-guide.md b/docs/reference/style-guide.md index af1af9b36..66d3ac6f8 100644 --- a/docs/reference/style-guide.md +++ b/docs/reference/style-guide.md @@ -56,7 +56,7 @@ Do not capitalize these terms unless they are the first word in a sentence or if Use emphasis sparingly to avoid making the page too visually busy or complex. -- Use backticks for file names, variable names, and command names, not to emphasize words or denote technical terms. +- Use backticks for file names, variable names, and command names, not to emphasize words or denote technical terms - Use bold for: From ff272b22c718b935eea5a994a177b69e2c4eb490 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Tue, 9 Jan 2024 09:32:23 -0500 Subject: [PATCH 3/7] Clarify rule about comparing to other blockchains --- docs/reference/style-guide.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/style-guide.md b/docs/reference/style-guide.md index 66d3ac6f8..10435c94e 100644 --- a/docs/reference/style-guide.md +++ b/docs/reference/style-guide.md @@ -2,7 +2,7 @@ title: Documentation style guide authors: Tim McMackin last_update: - date: 29 December 2023 + date: 9 January 2024 --- ## Overall Tezos-related issues @@ -10,7 +10,8 @@ last_update: - Tezos is decentralized. There is no official Tezos documentation, no official Tezos strategy, and no official entity in charge of Tezos. -- Do not compare Tezos to other blockchains. +- Do not compare Tezos to other specific blockchains. +You can say that Tezos has advantages over other blockchains, but don't say that Tezos is better than or does things differently from another specific blockchain. - Use "tez" to describe the currency instead of "XTZ" unless there is a specific reason to use the ISO code/ticker symbol "XTZ," such as in accounting systems, exchange rates with other currencies, and anything that needs a standardized code. From 98b6c4d8b4fd3445a44d58c3017f8b9b51e51902 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 15 Jan 2024 13:18:26 -0500 Subject: [PATCH 4/7] However, there can be official documentation for a Tezos-related tool. --- docs/reference/style-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/style-guide.md b/docs/reference/style-guide.md index 10435c94e..5dd69b3df 100644 --- a/docs/reference/style-guide.md +++ b/docs/reference/style-guide.md @@ -2,13 +2,14 @@ title: Documentation style guide authors: Tim McMackin last_update: - date: 9 January 2024 + date: 15 January 2024 --- ## Overall Tezos-related issues - Tezos is decentralized. There is no official Tezos documentation, no official Tezos strategy, and no official entity in charge of Tezos. +However, there can be official documentation for a Tezos-related tool. - Do not compare Tezos to other specific blockchains. You can say that Tezos has advantages over other blockchains, but don't say that Tezos is better than or does things differently from another specific blockchain. From 99a037f17bf2e9d1b064183ae74afc0bebb80716 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 15 Jan 2024 13:22:00 -0500 Subject: [PATCH 5/7] Layer abbreviations --- docs/reference/style-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/style-guide.md b/docs/reference/style-guide.md index 5dd69b3df..0953d5720 100644 --- a/docs/reference/style-guide.md +++ b/docs/reference/style-guide.md @@ -28,7 +28,8 @@ See https://tezos.gitlab.io/user/key-management.html#getting-keys-for-fundraiser - The fields in a contract's storage are called "properties." -- Don't use abbreviations for layers, as in "l1" or "l2." Say "layer 1" or "layer 2." +- Use the full forms "layer 1" and "layer 2" when talking about layers. +The abbreviations "L1" and "L2" (always capitalized) are acceptable later after you have introduced the concept of layers. ## Capitalization From 71c7ce3caf1f8745022b83497cbc920338bdcaf6 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 15 Jan 2024 13:31:48 -0500 Subject: [PATCH 6/7] meta-phrases --- docs/reference/style-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/style-guide.md b/docs/reference/style-guide.md index 0953d5720..6e2421a38 100644 --- a/docs/reference/style-guide.md +++ b/docs/reference/style-guide.md @@ -94,7 +94,8 @@ When linking to an external site, consider mentioning the target site, as in "fo - Do not describe documentation in terms of "chapters" or "articles." -- Avoid meta-phrases that make the documentation sound like a lecture or textbook, such as "we will see" and "the goal of this information is to." +- Avoid meta-phrases that don't add information. +For example, instead of "We will see how you can deploy smart contracts to Tezos by...," say "You can deploy smart contracts to Tezos by..." - When writing steps that the user must follow, make it clear what the user must do by following these guidelines: From aaa2d059f3fe4aa3470716a64a3dc88db85fc740 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 15 Jan 2024 13:32:27 -0500 Subject: [PATCH 7/7] Structure lists and headings in a consistent way. Co-authored-by: NicNomadic <148877430+NicNomadic@users.noreply.github.com> --- docs/reference/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/style-guide.md b/docs/reference/style-guide.md index 6e2421a38..5cb81e9c1 100644 --- a/docs/reference/style-guide.md +++ b/docs/reference/style-guide.md @@ -106,6 +106,6 @@ For example, instead of "We will see how you can deploy smart contracts to Tezos - Use language that makes it clear that the user must do something and what that action is. For example, instead of "4. In the file `myFile.js`:", say "4. Add this code to the file `myFile.js`." -- Structure lists and headings in a parallel way. +- Structure lists and headings in a consistent way. For example, make sure each list item is capitalized and punctuated in the same way. List items should be all complete sentences or all sentence fragments, not a mix.