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