Skip to main content

​
Documentation Standards

Documentation Standards

​
Overview

This document defines the standards for maintaining and updating documentation in the MOOD MNKY ecosystem. Following these standards ensures that documentation remains up-to-date, comprehensive, and aligned with code changes.
Documentation should be treated as a first-class citizen in the development process. Code changes are not complete until the corresponding documentation is updated.

​
Documentation Change Process

​
When to Update Documentation

Documentation should be updated in the following scenarios:

New Features

When adding new functionality, components, or services to the system.

Changes to Existing Features

When modifying existing functionality, APIs, or interfaces.

Deprecations or Removals

When deprecating or removing features, APIs, or components.

Best Practices Updates

When recommended approaches or best practices change.

Bug Fixes

When fixing bugs that affect documented behavior.

Infrastructure Changes

When changing how systems are deployed, configured, or operated.

​
Documentation Change Checklist

1

Identify Affected Documentation

Determine which documentation files need to be updated based on the code changes:
  • README files in affected directories
  • API documentation
  • Developer guides
  • End-user documentation
  • Architecture documentation
2

Update Documentation Files

Make necessary changes to documentation:
  • Update technical details to match new implementation
  • Revise examples to reflect current API or behavior
  • Add new sections for new features
  • Mark deprecated features appropriately
  • Update screenshots or diagrams if UI/UX changes
3

Add Changelog Entries

Document the changes in appropriate changelog files:
  • Add entries to the root CHANGELOG.md for significant changes
  • Update component-specific changelog sections in README files
  • Follow the standard format: [date] title, then Added/Changed/Deprecated/Removed sections
4

Update DOCUMENTATION-AUDIT.md

If creating new documentation files or significantly changing structure:
  • Update the DOCUMENTATION-AUDIT.md file with the new files
  • Mark completed documentation with checkmarks
  • Note any documentation that still needs work
5

Review Documentation Changes

Before submitting your PR:
  • Verify technical accuracy
  • Check for consistent terminology
  • Ensure proper formatting
  • Test any included code examples
  • Validate links to other documentation

​
Changelog Standards

​
Changelog Location

Root Changelog

CHANGELOG.md in the repository root for project-wide changes

Component Changelogs

Changelog section in component README files

Package Changelogs

Changelog section in package README files

​
Changelog Format

Changelogs should follow this format: 
## Changelog

### [YYYY-MM-DD] Title of Change or Release

#### Added
- New features or capabilities added

#### Changed
- Modifications to existing functionality

#### Deprecated
- Features that are still available but planned for removal

#### Removed
- Features or capabilities that have been removed

#### Fixed
- Bug fixes

### [Previous Date] Previous Change
...
Always include a date with each changelog entry to help track when changes were made.

​
Example Changelog Entry

### [2024-04-05] Supabase Restructuring

#### Added
- Initial `/infra/supabase` directory structure
- Shared client package in `/packages/supabase-client`
- Database schema definitions in `/data/schemas`
- Local development setup script

#### Changed
- Relocated Supabase configuration from root `/supabase` to `/infra/supabase`
- Created clear separation between infrastructure and data components
- Updated client implementation to use TypeScript types

#### Deprecated
- Root `/supabase` directory - will be removed in a future update

​
README Standards

​
README File Locations

Every significant directory in the codebase should have a README.md file that explains:

Purpose

What the directory contains and why it exists

Structure

The organization of files and subdirectories

Usage

How to use the components or services

Configuration

How to configure the components (if applicable)

Dependencies

Relationships with other parts of the system

Changelog

History of significant changes

​
README Structure Template

# Component Name

Brief description of the component's purpose and function.

## Directory Structure
directory/ ├── subdirectory1/ # Description of subdirectory1 ├── subdirectory2/ # Description of subdirectory2 ├── file1.ext # Description of file1 └── file2.ext # Description of file2 

## Purpose

Detailed explanation of what this component does and why it exists.

## Usage

Instructions for how to use this component, with examples.

```typescript
// Example code
import { someFunction } from './path/to/component';

const result = someFunction();

​
Configuration

Explanation of configuration options, environment variables, etc.

​
Dependencies

List of dependencies and relationships with other components.

​
Changelog

​
[YYYY-MM-DD] Change Title

​
Added

  • New features

​
Changed

  • Modified features
… etc. 

## Documentation Audit

The `DOCUMENTATION-AUDIT.md` file serves as a central registry of all documentation in the system. It helps track documentation completeness and identify areas needing improvement.

### Audit File Format

```markdown
# Documentation Audit

## Overview
This document provides an audit of the current documentation site structure, identifying missing files and inconsistencies.

## Audit Date: YYYY-MM-DD (Updated)

## Status

✅ **All referenced documentation pages now exist as at least placeholder files.**
Or
❌ **Some documentation pages are missing or incomplete.**

## Recent Updates (YYYY-MM-DD)

### Feature or Section Name
- ✅ Updated `path/to/doc.mdx` with changes
- ✅ Created `path/to/new-doc.mdx` as a new guide
- ❌ Need to update `path/to/outdated-doc.mdx`

## Navigation Structure

### Section Name
- ✅ docs/section/file1.md - Exists
- ✅ docs/section/file2.md - Exists (placeholder)
- ❌ docs/section/file3.md - Missing

## Recommendations

### Next Steps
1. Prioritized list of documentation work
The Documentation Audit should be updated whenever significant documentation changes are made or when new documentation needs are identified.

​
Documentation Review Process

1

Self-Review

Before submitting documentation changes:
  • Check for technical accuracy
  • Verify code examples work
  • Check for grammar and spelling
  • Ensure consistent formatting
2

Technical Review

Have a technical expert review the documentation for:
  • Correctness of technical information
  • Completeness of coverage
  • Clarity of explanations
  • Accuracy of examples
3

Documentation Review

Have a documentation expert review for:
  • Adherence to documentation standards
  • Consistency with existing documentation
  • Writing quality and clarity
  • Proper use of documentation components
4

Approval and Publishing

Once reviews are complete:
  • Address any feedback
  • Get final approval
  • Merge documentation changes
  • Update the Documentation Audit

​
Tools and Documentation Guidelines

For detailed information on writing documentation, using Mintlify components, and documentation best practices, refer to:

Documentation Guide

Comprehensive guide to writing documentation

Style Guide

Brand styling guidelines for documentation

Component Library

UI components for documentation

API Documentation

Standards for API documentation
This standards document is maintained by the Documentation Team. Last updated: April 2025.