Writing docs
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 tagWorkspaces
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 forCreate workspace
, then the article with the keywordCreate 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.