This article discusses some of the protocol and conventions to be followed while writing docs.
- Docs follow object-oriented approach. Each folder represents an object and each file represents procedures associated with that object.
- Each folder contains an
_category_.jsonfile which contains the metadata for that object.
- Add following metadata to the top of each file.
title: "Writing docs"
description: "Overview to writing docs"
keywords: ['Engineering', Writing docs', 'Docs conventions']
titleis the title of the article that appears on the sidebar and on the top of the article.
descriptionis the description of the article that appears in search results.
tagsare the tags associated with the article. Tags are used to group articles together. For example, all articles with the tag
Workspaceswill be grouped together.
keywordsare 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 workspacewill be displayed in the search results.
- 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,
- Only first letter of the folder/file name is capitalized. Second letter onwards, first letter is capitalized only if it is a proper noun.
- 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 API tokenetc.
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 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.
- Annotated images should be placed in
- For every annotated image, there should be a corresponding unannotated image in the
- Images are kept in the same folder structure as the docs.
Before you commit
npm run buildto build the docs.
- Ensure that the build is successful & there are no errors/warnings related to missing links, images, etc.