Writing Documentation

This article discusses the protocol and conventions to follow when writing documentation for CTRL in the ctrl-docs repository.

Folder Structure

Documentation follows an object-oriented approach:

• Each folder represents an object (e.g., architecture, repository-structure).
• Each file represents a procedure or topic related to that object.
• Each folder can contain a meta.json file with metadata for that object.

Example meta.json:

{
  "title": "Engineering",
  "icon": "terminal",
  "pages": [
    "architecture",
    "repository-structure",
    "development-setup",
    "unit-testing",
    "playwright",
    "build-and-releases",
    "translations",
    "writing-docs"
  ]
}

File Structure

Add the following metadata to the top of each .mdx file:

---
title: "Writing docs"
description: "Overview to writing docs"
tags: ['Engineering']
keywords: ['Engineering', 'Writing docs', 'Docs conventions']
---

• title: Appears in the sidebar and at the top of the article.
• description: Appears in search results.
• tags: Used to group articles.
• keywords: Improve search results.

Nomenclature

• Folder and file names use kebab-case (e.g., account-settings).
• Only the first letter is capitalised if it is a proper noun.
• Tags: First letter capitalised, usually objects or actions. Only add a tag if it will be reused.

Descriptions

• Should be concise and to the point (preferably one line).
• Descriptions appear in search results and should clearly indicate the article's purpose.

Images

Place any images in the public/ folder and name them appropriately.

Before You Commit

• Run yarn build to build the docs.
• Ensure the build is successful and there are no errors or warnings about missing links or images.

By following these conventions, we ensure that documentation in ctrl-docs is consistent, searchable, and easy to maintain.

Docs built with Fumadocs

CTRL's documentation is compiled using Fumadocs which is an opensource documentation tool built with the Next.js framework: