Skip to main content
Version: Latest

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 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

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.