Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: redo typo PR by ankushgoel27 #8595

Merged
merged 1 commit into from
Sep 17, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/HOW_WE_WRITE_DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,21 @@ 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

These are guides for the reader to accomplish a specific goal. In the context of Aztec docs, how-to guides usually cover a specific feature, library, or setup. It expects the reader to know why they are there and does not provide any additional context than needed. They currently only exist in `Build`.

#### 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

Expand All @@ -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
Expand All @@ -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

Expand Down