@ -0,0 +1,66 @@
|
||||
--- |
||||
title: "Writing docs" |
||||
description: "Overview to writing docs" |
||||
tags: ['Engineering'] |
||||
--- |
||||
|
||||
This article discusses some of the protocol and conventions to be followed while writing docs. |
||||
|
||||
## Folder Structure |
||||
- Docs follow object-oriented approach. Each folder represents an object and each file represents procedures associated with that object. |
||||
- Each folder contains an `_category_.json` file which contains the metadata for that object. |
||||
``` |
||||
{ |
||||
"label": "Engineering", |
||||
"collapsible": true, |
||||
"collapsed": true |
||||
} |
||||
``` |
||||
|
||||
## File Structure |
||||
- Add following metadata to the top of each file. |
||||
``` |
||||
--- |
||||
title: "Writing docs" |
||||
description: "Overview to writing docs" |
||||
tags: ['Engineering'] |
||||
keywords: ['Engineering', Writing docs', 'Docs conventions'] |
||||
--- |
||||
``` |
||||
- `title` is the title of the article that appears on the sidebar and on the top of the article. |
||||
- `description` is the description of the article that appears in search results. |
||||
- `tags` are the tags associated with the article. Tags are used to group articles together. For example, all articles with the tag `Workspaces` will be grouped together. |
||||
- `keywords` are the keywords associated with the article. Keywords are used to improve search results. For example, if the user searches for `Create workspace`, then the article with the keyword `Create workspace` will be displayed in the search results. |
||||
|
||||
## Nomenclature |
||||
- Folder names & file name are |
||||
- in kebab-case. |
||||
- prefix with a number that represents the order in which the folder/file should be displayed in the sidebar. |
||||
- prefix number is always a 3-digit number. |
||||
- For example, `010.account-settings`. |
||||
- Only first letter of the folder/file name is capitalized. Second letter onwards, first letter is capitalized only if it is a proper noun. |
||||
|
||||
## Tags |
||||
- First letter of each tag is capitalized. |
||||
- Tags usually are Objects or Actions. Add a tag only if we are sure that the tag will be used in multiple places. Example: 'Create' - we can have `Create project`, `Create user`, `Create API token` etc. |
||||
|
||||
### Active Tags |
||||
Tags that are currently being used in the docs are listed below. See if you can reuse any of these tags before adding a new tag. |
||||
|
||||
## Description |
||||
- Description should be crisp and to the point. Preferably one line. |
||||
- Refer to the description associated with the tag to get an idea of how the description should be. |
||||
- Descriptions appear in the search results (when searched by tags). So, it should be descriptive enough to give the user an idea of what the article is about. |
||||
|
||||
![Search by tags](/img/v2/engineering/engineering-search-by-tags.png) |
||||
|
||||
## Images |
||||
- Annotated images should be placed in `img/v2` folder. |
||||
- For every annotated image, there should be a corresponding unannotated image in the `img/v2-unannotated` folder. |
||||
- Images are kept in the same folder structure as the docs. |
||||
- Use `Skitch` for annotations. |
||||
|
||||
## Before you commit |
||||
- Use `npm run build` to build the docs. |
||||
- Ensure that the build is successful & there are no errors/warnings related to missing links, images, etc. |
||||
|
Before Width: | Height: | Size: 406 KiB After Width: | Height: | Size: 406 KiB |
Before Width: | Height: | Size: 189 KiB After Width: | Height: | Size: 189 KiB |
Before Width: | Height: | Size: 274 KiB After Width: | Height: | Size: 274 KiB |
Before Width: | Height: | Size: 354 KiB After Width: | Height: | Size: 354 KiB |
Before Width: | Height: | Size: 331 KiB After Width: | Height: | Size: 331 KiB |
Before Width: | Height: | Size: 349 KiB After Width: | Height: | Size: 349 KiB |
Before Width: | Height: | Size: 255 KiB After Width: | Height: | Size: 255 KiB |
Before Width: | Height: | Size: 306 KiB After Width: | Height: | Size: 306 KiB |
Before Width: | Height: | Size: 343 KiB After Width: | Height: | Size: 343 KiB |
After Width: | Height: | Size: 271 KiB |