Skip to content
Merged
Show file tree
Hide file tree
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
61 changes: 45 additions & 16 deletions STYLE_GUIDE.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,99 +7,118 @@ This style guide contains general rules and principles to ensure the documentati
This documentation strives to be

### Beginner Friendly

The Sei community welcomes members from all walks of life. As such, the documentation should be understandable by anyone, including those who are new to Web3 or non-technical.

The docs should strive to be Jargon Free

- Advanced terms and concepts, especially Web3 related terms and ideas, should be properly explained.
- Where appropriate, we should provide links to resources that can help the reader understand.
- Acronyms should be spelled out


### Simple

Great documentation is simple and to the point. It should aim to convey more meaning with less words.

- To be clear and inclusive, avoid using jargon and obscure words where possible.
- To be clear and inclusive, avoid using jargon and obscure words where possible.
- Limit the number of clauses in a sentence and make sure that your points are structured.
- Avoid qualifying language, which is ~~quite~~ often ~~completely~~ unnecessary.
- Information should be simply organized and easy to find.

### Self-explanatory

Great documentation is self-explanatory. Documentation shouldn't need more documentation to explain itself.

- Aim to provide as much context as possible. Code snippets and diagrams are great ways to illustrate complex concepts and provide examples.

## Organization

The Sei Docs are structured using the [Nextra](https://nextra.site). Are a guideline, we have split the pages by target audience.

### General

Docs in these section describe Sei and topics that are applicable to all audiences. This is general information that is not specific to users or developers. Information here is meant to be as layman as possible and should be understandable by everyone.

Information here might include:

- What is Sei?
- How does a blockchain work?
- General information about how things work.

### For Users

This section includes information specific to enabling people to interact with the Sei blockchain.

Examples include information about standard resources used to interact with the chain (Wallets, Block Explorers), as well as tutorials on how to get started on Sei (Where to find tokens, apps etc.)

### For Devs

This section includes resources for developers looking to build Dapps on Sei. Examples of what goes in here include:

- Smart contract tutorials
- Endpoints and config information that developers should use to interact with Sei (RPC Endpoints, Chain IDs etc)
- Information about clients and libraries that developers can use to easily develop apps.

### Advanced

This section covers topics that are more specific to chain infrastructure. These are topics that are typically abstracted away from regular users and developers, but might be relevant to those looking to contribute chain infrastructure. Examples of topics here include:

- How to run a Sei Node
- How to run a Sei Validator

### Misc

This section houses other pages that do not fall under the buckets above.

## Style guidelines

### Acronyms and Abbreviations

To maximize clarity, we should avoid Acronyms and Abbreviations where possible, especially for shorter, more ambiguous acronyms

- Just use 'CosmWasm' instead of 'CW'

However, there are occasions where acronyms might be more easily understandable (Eg. NFT instead of Non-Fungible Token, RPC instead of Remote Procedure Call), or referred to very frequently.
However, there are occasions where acronyms might be more easily understandable (Eg. NFT instead of Non-Fungible Token, RPC instead of Remote Procedure Call), or referred to very frequently.

In these cases, we should first use the use the spelled-out term followed by the shortened form in parentheses.

- Command Line Interface (CLI)
- Denomination (Denom)

On subsequent occurrences in the same topic, we can then use the acronym.

### Links

You can add links to text using the followings syntax
You can add links to text using the followings syntax

```md
[text_to_highlight](link)
```

Some examples (These examples assume the page is in the `/pages` directory):

1. Link to section of [same document](#style-guidelines).

```md
[same document](#style-guidelines)
```

2. Link to [another document](/pages/overview.mdx).
2. Link to [another document](/pages/overview).

```md
# Path is relative

[another document](/overview)
```

3. Link to [section of another document](/pages/overview.mdx#Staking).

```md
[section of another document](/overview#Staking)
```

4. External [Link](www.app.sei.io).

```md
[Link](www.app.sei.io)
```
Expand All @@ -112,38 +131,44 @@ Links should be as descriptive as possible to let the reader know where they are

- Better Example: Interested to learn more about staking? Refer to our [staking guide](#links) to find out more!


### Code

Code should either be specified as `inline`

```md
Code should either be specified as `inline`
```

Or within code blocks.

```ts
const codeBlockString = "codeBlock"
const codeBlockString = 'codeBlock';
```

```md
````md
```ts
const codeBlockString = "codeBlock"
```
```
````

`Inline Code` should be used when referring to

- File and directory names. (eg. `./pages/overview.mdx`)
- References to variables in code (eg. `codeBlockString`)

Code Blocks should be used when

- Sharing code snippets

```ts
const codeBlockString = () => {
const text = "codeblock"
let codeBlockSize: Number = 1
}
const text = 'codeblock';
let codeBlockSize: Number = 1;
};
```

- Scripts that users should copy and execute directly

```sh
git clone https://github.com/sei-protocol/sei-chain
cd sei-chain
Expand All @@ -152,7 +177,8 @@ make install
```

When code blocks are used, they should always be prettified by specifying the language. For example:
```md

````md
TypeScript code block labelled with 'ts'
```ts
const variable = value;
Expand All @@ -163,9 +189,10 @@ When code blocks are used, they should always be prettified by specifying the la
git clone https://github.com/sei-protocol/sei-chain
cd sei-chain
```
```
````

When writing code blocks, avoid

1. Creating large code blocks. Break your code into smaller, more digestible pieces.
2. Writing too much documentation in between lines. If necessary, break the code block up and add text to explain each code block instead.

Expand All @@ -184,18 +211,20 @@ Headings should be use to denote the start of each section. There are 4 levels o
#### Use only if more required
```

Headings levels should never be skipped. A level 2 heading should follow a level 1 heading, and a level 3 heading should follow a level 2 heading etc.
Headings levels should never be skipped. A level 2 heading should follow a level 1 heading, and a level 3 heading should follow a level 2 heading etc.

### Images

To use images, first add them to the `./public/assets` folder.

Afterwards, they can be imported in each page using an import statement. For example:

```md
import nameOfImage from "../../public/assets/nameOfImage.png";
```

Lastly, use the `ImageWithCaption` component to add the image to the page, along with a descriptive label:

```md
<ImageWithCaption img={nameOfImage} alt="alt text for my image" caption="Your caption here" />
```
```
2 changes: 1 addition & 1 deletion data/redirects.json
Original file line number Diff line number Diff line change
Expand Up @@ -400,7 +400,7 @@
"permanent": true
},
{
"source": "/dev-ecosystem-providers/wallets",
"source": "/providers/wallets/wallets",
"destination": "/providers/wallets",
"permanent": true
},
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"start": "next start",
"format:pages": "prettier --write 'pages/**/*.{js,ts,tsx,mdx}'",
"generate-seid-docs": "./generate-seid-docs.sh",
"check-links": "concurrently \"next start\" \"wait-on http://localhost:3000 && node scripts/check-links.mjs\" --kill-others --success first"
"check-links": "node scripts/check-links.mjs"
},
"license": "MIT",
"dependencies": {
Expand Down
Loading