Documentation Standards

Good documentation reduces onboarding time, prevents knowledge loss, and ensures consistency across projects. This document defines where documentation lives, how it is written, and how it stays current.

Documentation Locations

Documentation is stored in one of three locations depending on its audience and scope.

Location	Audience	Content	Examples
SOP sites (public Docusaurus)	All team members, clients (where applicable)	Standard operating procedures, company policies, onboarding guides	EGI SOP, Mast SOP, Anchor SOP
dev-docs (private repository)	Engineering team only	Internal technical references, architecture decisions, credentials guides, internal tooling docs	API patterns, deployment configs, secrets management
Project repositories	Project team members	Project-specific documentation	README, ADRs, API docs, environment setup, runbooks

Rules for Placement

• If the content applies to how the company operates, it belongs in the relevant SOP site
• If the content is internal engineering knowledge not tied to a single project, it belongs in dev-docs
• If the content is specific to one project, it belongs in that project's repository
• Never duplicate documentation across locations; link to the source of truth instead

File Format

All documentation is written in Markdown (.md files). This applies to SOP sites, dev-docs, and project repository docs.

Frontmatter Requirements

Every Markdown file in an SOP site must include YAML frontmatter at the top of the file.

Required fields:

---
id: unique-identifier
title: Human-Readable Title
sidebar_position: 1
---

• id -- A unique, lowercase, hyphen-separated identifier. Must match the filename (without extension).
• title -- The display title shown in the sidebar and page heading.
• sidebar_position -- An integer that controls ordering within the sidebar section.

Optional fields:

---
description: A one-line summary of the document's purpose.
tags: [operations, slack, communication]
---

Project Repository Docs

Project repos use a standard README.md at the root. Additional documentation goes in a /docs directory within the repo. Frontmatter is optional for project repo docs but encouraged if the project uses a documentation site.

Writing Style Guide

Tone and Voice

• Write in plain, direct language. Avoid jargon unless the audience is technical and the term is standard.
• Use active voice and second person ("you") when giving instructions.
• Be concise. If a sentence does not add information, remove it.
• Write for someone who is new to the team but has relevant professional experience.

Formatting Rules

1. Headings: Use heading levels hierarchically (H1 for the page title only, H2 for major sections, H3 for subsections). Never skip heading levels.
2. Lists: Use bullet lists for unordered items and numbered lists for sequential steps.
3. Tables: Use tables when comparing items or presenting structured data with multiple attributes.
4. Code blocks: Use fenced code blocks with a language identifier for all code, commands, and configuration snippets.
5. Links: Use relative links for documents within the same site. Use absolute URLs for external references.
6. Bold: Use bold for key terms on first use, UI element names, and emphasis on critical instructions.
7. Avoid: Emojis in documentation, exclamation marks, vague language ("simple", "just", "easy"), and first-person singular ("I").

Naming Conventions

• Filenames: Lowercase, hyphen-separated, descriptive (e.g., launch-checklist.md, not LC.md or Launch Checklist.md)
• Directory names: Lowercase, hyphen-separated (e.g., company-operations/, not CompanyOperations/)
• Image files: Stored in a /static/img/ directory (SOP sites) or /docs/assets/ directory (project repos), named descriptively

Content Structure

Every document should follow this general structure:

1. Title (H1) -- Matches the frontmatter title
2. Introduction -- One to three sentences explaining what the document covers and who it is for
3. Body -- Organized under H2 and H3 headings, with the most important information first
4. Cross-references -- Links to related documents at the end of relevant sections or in a dedicated "See Also" section

Review Cycle

Quarterly Review

All SOP documentation is reviewed on a quarterly cycle to ensure accuracy.

Quarter	Review Period	Deadline
Q1	January 1 -- 15	January 31
Q2	April 1 -- 15	April 30
Q3	July 1 -- 15	July 31
Q4	October 1 -- 15	October 31

Review process:

1. Each document has a designated owner (typically the person or team lead most familiar with the content)
2. The owner reads the document, verifies all procedures and links are current, and updates outdated content
3. Changes are submitted as a pull request against the SOP site repository
4. A second team member reviews and approves the PR
5. Once merged, the document is considered current for the quarter

Triggered Reviews

Outside of the quarterly cycle, a document must be reviewed and updated when:

• A process it describes changes
• A tool it references is replaced or significantly updated
• A team member identifies an error or gap
• A new team member reports confusion during onboarding

Creating New Documentation

Before creating a new document:

1. Search existing docs to confirm the topic is not already covered
2. Determine the correct location using the placement rules above
3. Use an existing document as a structural reference
4. Submit via PR with a clear description of what the document covers and why it was needed
5. Assign a reviewer who is familiar with the subject matter

Archiving Documentation

When a document is no longer relevant (e.g., a deprecated process or a completed project):

• Do not delete the file
• Move it to an /archive directory within the same documentation site or repository
• Add a note at the top of the document: > **Archived:** This document is no longer active as of [date]. See [replacement document] for current procedures.