Contributing to Documentation¶

This guide outlines our documentation standards and contribution process.

Documentation Standards¶

File Naming¶

Use lowercase with hyphens: service-name.md
Be descriptive: rabbitmq-setup.md not setup.md
Use consistent naming patterns within sections

Structure¶

Every documentation file should include:

YAML Frontmatter (metadata):

---
audience: developers|devops|clients|reference
category: guide|reference|troubleshooting|api
last_updated: YYYY-MM-DD
related_docs:
  - path/to/related/doc.md
---

Title (H1): Clear, descriptive title
Overview: Brief description of what the document covers
Content: Well-organized sections with clear headings
See Also: Links to related documentation at the bottom

Formatting Guidelines¶

Headings: Use H1 for title, H2 for main sections, H3 for subsections
Code Blocks: Always specify language: ```bash, ```typescript, etc.
Links: Use relative paths: text
Lists: Use consistent bullet or numbered list formatting
Tables: Use markdown tables for structured data

Writing Style¶

Be Clear: Write for your audience (developers vs. clients)
Be Concise: Avoid unnecessary verbosity
Be Accurate: Keep documentation up-to-date with code
Be Helpful: Include examples, code snippets, and troubleshooting tips

Adding New Documentation¶

1. Choose the Right Location¶

Developers: docs/developers/ - Development guides, APIs, services
DevOps: docs/devops/ - Deployment, infrastructure, operations
Clients: docs/clients/ - Non-technical overviews, features
Reference: docs/reference/ - Quick references, glossaries

2. Create the File¶

# Example: Adding a new service guide
touch docs/developers/services/my-service/README.md

3. Add Content¶

Follow the structure guidelines above. Include: - Clear title and overview - Step-by-step instructions (if applicable) - Code examples - Troubleshooting section (if needed) - Links to related docs

4. Update Index Files¶

Add entry to relevant README.md (section index)
Update navigation if needed
Add to glossary if introducing new terms

5. Test Links¶

Verify all internal links work
Check that referenced files exist
Test code examples

Updating Existing Documentation¶

Check Last Updated: Update the last_updated date in frontmatter
Maintain Structure: Keep existing organization unless improving it
Update Related Docs: If content changes affect other docs, update them too
Preserve Context: Don't remove historical context unless truly outdated

Documentation Categories¶

guide: Step-by-step instructions, tutorials
reference: API docs, command references, specifications
troubleshooting: Problem-solving guides
api: API documentation

Review Process¶

Self-Review: Check formatting, links, and accuracy
Peer Review: Have another team member review
Update Indexes: Ensure navigation is updated
Merge: Submit via merge request

Common Patterns¶

Service Documentation Template¶

---
audience: developers
category: guide
last_updated: YYYY-MM-DD
related_docs:
  - ../architecture/service-architecture.md
---

# Service Name

## Overview

Brief description of the service.

## Quick Start

```bash
# Installation commands

API Reference¶

Endpoints¶

GET /api/endpoint - Description

Development¶

Local Setup¶

Testing¶

Troubleshooting¶

AI Agent Assistance¶

When working with AI agents to create or update documentation:

Provide Context: Reference docs/README.md and the documentation structure
Specify Location: Tell the agent where to save files (e.g., docs/developers/services/[service]/README.md)
Reference Standards: Point to this CONTRIBUTING.md file
Use Metadata: Ensure YAML frontmatter is included

See AI Agent Guide for detailed guidance on prompting AI agents.

Questions?¶

If you're unsure about: - Where to put something: Check existing structure or ask the team - How to format: Follow existing patterns in similar docs - What to include: Think about what your audience needs to know - AI agent prompts: See AI Agent Guide

Remember: Good documentation is as important as good code. Thank you for contributing!