From ae4905f3eebbaa3fb51ae536f0f71e3d0b4580f1 Mon Sep 17 00:00:00 2001 From: Ankush Goel Date: Tue, 17 Sep 2024 15:46:58 +0530 Subject: [PATCH] Update HOW_WE_WRITE_DOCS.md --- docs/HOW_WE_WRITE_DOCS.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/HOW_WE_WRITE_DOCS.md b/docs/HOW_WE_WRITE_DOCS.md index b74cdb91b60..d81fe19a17a 100644 --- a/docs/HOW_WE_WRITE_DOCS.md +++ b/docs/HOW_WE_WRITE_DOCS.md @@ -20,13 +20,13 @@ The Aztec docs roughly follow the [Diataxis](https://diataxis.fr/) framework. It Every page will fall into **one type of doc**. If your contribution covers multiple types, you will need to split it into multiple pages. -#### Explainations +#### Explanations -These answer the questions "What is...?" and don't have any direct implications for what the reader does. It helps readers understand a concept. These can exist in both `Learn` and `Build` sections of the docs, depending on the context of the explanations. For example, a doc explaining UTXOs would sit in `Learn`, but explaining how Aztec.nr abstracts UTXOs would sit in `Build`. +These answer the question "What is...?" and don't have any direct implications for what the reader does. It helps readers understand a concept. These can exist in both `Learn` and `Build` sections of the docs, depending on the context of the explanations. For example, a doc explaining UTXOs would sit in `Learn`, but explaining how Aztec.nr abstracts UTXOs would sit in `Build`. #### Tutorials -These are follow-along experiences that guide the reader into building something. In the context of Aztec docs, these are generally project-oriented rather than feature-oriented. For example, a developer might learn how to build a private token rather than focusing on how to use a specific Aztec privacy feature. It does not expect too much prior knowledge from the developer, and does not expect that they have a goal in mind aside from learning. They currently only exist in `Build`. +These are follow-along experiences that guide the reader into building something. In the context of Aztec docs, these are generally project-oriented rather than feature-oriented. For example, a developer might learn how to build a private token rather than focusing on how to use a specific Aztec privacy feature. It does not expect too much prior knowledge from the developer and does not expect that they have a goal in mind aside from learning. They currently only exist in `Build`. #### How-tos @@ -34,7 +34,7 @@ These are guides for the reader to accomplish a specific goal. In the context of #### References -These are docs that developers can consult to know exact and succint information about a specific library or feature. In the case of Aztec, it usually consists of lists of callable functions, their parameters, and return types. Most Aztec references are autogenerated. They currently only exist in `Build`. +These are docs that developers can consult to know exact and succinct information about a specific library or feature. In the case of Aztec, it usually consists of lists of callable functions, their parameters, and return types. Most Aztec references are autogenerated. They currently only exist in `Build`. ## Tone @@ -46,9 +46,9 @@ These are docs that developers can consult to know exact and succint information ## Grammar -To keep docs consistent and easily-searchable, follow these grammar guidelines: +To keep docs consistent and easily searchable, follow these grammar guidelines: -* Write with American English +* Write in American English * When talking about ZK, use: * `zero knowledge` as the noun * `zero-knowledge` as the adjective @@ -67,7 +67,7 @@ Markdown links by file (with extension). Can be relative to current path (`./`, `../`), eg within a section, or absolute (relative to docs). [link1](https://docusaurus.io/docs/markdown-features/links), [link2](https://docusaurus.io/docs/versioning#link-docs-by-file-paths) -If you spot a broken url, ping us in discord or create an issue :) +If you spot a broken URL, ping us in Discord or create an issue :) ## Keywords