mirror of https://github.com/nocodb/nocodb
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
67 lines
3.0 KiB
67 lines
3.0 KiB
1 year ago
|
---
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## 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.
|
||
|
|
|