Access the Mind Measure Platform →
Contributing
Documentation Workflow

Mind Measure Documentation Workflow

Overview

This document establishes the documentation-as-code workflow for Mind Measure, ensuring that all changes are properly documented and maintained as part of the development process.

Documentation Principles

1. Documentation as Code

  • All documentation lives in version control
  • Documentation changes are reviewed like code changes
  • Documentation is deployed automatically
  • Documentation is tested for accuracy

2. Documentation First

  • Architecture decisions are documented before implementation
  • API changes include documentation updates
  • Database schema changes include documentation updates
  • Security changes include compliance documentation updates

3. Living Documentation

  • Documentation is updated with every relevant change
  • Outdated documentation is treated as a bug
  • Documentation accuracy is monitored and validated
  • Regular documentation audits are conducted

Documentation Structure

docs.mindmeasure.co.uk - Primary Documentation Site

├── Overview (landing page)
├── Architecture (system design)
├── Mobile App (mobile application)
├── Backend (server architecture)
├── Database & RLS (database schema)
├── Assessment Methodology (clinical approach)
├── AWS Authentication Guide (auth implementation)
├── Deployment (deployment procedures)
├── Privacy & Legal (compliance)
├── Development (dev setup)
├── ADRs (architectural decisions)
├── Playbooks (operational procedures)
├── Admin UI (admin interface)
├── API Documentation (API reference)
├── CMS User Guide (content management)
├── CMS Technical Documentation (CMS tech details)
├── Aurora Serverless v2 (database implementation)
├── Testing Panel Guide (testing procedures)
├── Medical-Grade Security (security implementation)
├── Phase 2: Advanced Security (security phase 2)
├── Phase 3: Final Security (security phase 3)
└── Documentation Guide (this workflow)

Repository Documentation - Technical Reference

├── README.md (project overview)
├── CHANGELOG.md (version history)
├── CONTRIBUTING.md (contribution guidelines)
├── DEPLOYMENT.md (deployment instructions)
├── SECURITY.md (security policies)
├── API.md (API documentation)
├── DATABASE.md (database documentation)
├── ARCHITECTURE.md (architecture overview)
└── docs/ (additional documentation)

Workflow Process

For Every Code Change

1. Pre-Development

  • Check if change affects existing documentation
  • Identify documentation that needs updates
  • Create documentation update tasks

2. During Development

  • Update inline code documentation
  • Update API documentation if endpoints change
  • Update database documentation if schema changes
  • Update architecture documentation if design changes

3. Pre-Deployment

  • Review documentation changes
  • Validate documentation accuracy
  • Update deployment documentation if process changes
  • Update user guides if UI changes

4. Post-Deployment

  • Update docs.mindmeasure.co.uk with changes
  • Update version numbers and changelogs
  • Notify stakeholders of documentation updates
  • Archive outdated documentation

Documentation Types & Responsibilities

Technical Documentation

Owner: Development Team Updates Required For:

  • API changes
  • Database schema changes
  • Architecture modifications
  • Security implementations
  • Deployment process changes

Examples:

  • Database schema updates → Update Database & RLS section
  • New Lambda functions → Update API Documentation
  • AWS service changes → Update Architecture section

User Documentation

Owner: Product Team Updates Required For:

  • UI/UX changes
  • Feature additions/removals
  • Workflow modifications
  • Admin interface changes

Examples:

  • New CMS features → Update CMS User Guide
  • Admin dashboard changes → Update Admin UI documentation
  • Mobile app features → Update Mobile App section

Compliance Documentation

Owner: Security/Compliance Team Updates Required For:

  • Security implementations
  • Privacy policy changes
  • Compliance requirement updates
  • Audit findings

Examples:

  • HIPAA changes → Update Privacy & Legal section
  • Security enhancements → Update Medical-Grade Security
  • AWS compliance → Update AWS Migration & Compliance

Operational Documentation

Owner: DevOps Team Updates Required For:

  • Deployment process changes
  • Infrastructure modifications
  • Monitoring implementations
  • Incident response procedures

Examples:

  • New deployment steps → Update Deployment section
  • Infrastructure changes → Update Architecture section
  • New monitoring → Update operational playbooks

Documentation Standards

Writing Standards

  • Use clear, concise language
  • Include code examples where relevant
  • Use consistent formatting and structure
  • Include diagrams for complex concepts
  • Provide step-by-step instructions

Technical Standards

  • All code examples must be tested
  • API documentation must match implementation
  • Database documentation must reflect current schema
  • Architecture diagrams must be current

Review Standards

  • All documentation changes require review
  • Technical accuracy must be verified
  • Compliance implications must be assessed
  • User impact must be considered

Change Management Process

Major Changes (Architecture, Security, Compliance)

  • RFC (Request for Comments)

    • Create architectural decision record (ADR)
    • Document proposed changes
    • Include impact assessment
    • Gather stakeholder feedback

  • Documentation Planning

    • Identify all affected documentation
    • Plan documentation updates
    • Assign documentation responsibilities
    • Set documentation deadlines

  • Implementation

    • Implement changes with documentation updates
    • Review documentation changes
    • Test documentation accuracy
    • Deploy documentation updates

  • Post-Implementation

    • Validate documentation accuracy
    • Gather user feedback
    • Update based on feedback
    • Archive old documentation

Minor Changes (Bug fixes, UI tweaks)

  • Identify Impact

    • Check if documentation needs updates
    • Identify specific sections affected

  • Update Documentation

    • Make necessary documentation changes
    • Review for accuracy
    • Deploy updates

Documentation Maintenance

Regular Audits

  • Monthly: Review recent changes for documentation gaps
  • Quarterly: Comprehensive documentation accuracy review
  • Annually: Full documentation structure review

Automated Checks

  • Link validation (ensure all links work)
  • Code example validation (ensure examples compile/run)
  • Schema validation (ensure database docs match schema)
  • API validation (ensure API docs match endpoints)

Metrics & Monitoring

  • Documentation page views and usage
  • User feedback on documentation quality
  • Time to find information (user experience)
  • Documentation coverage (% of features documented)

Tools & Technologies

Documentation Site

  • Platform: docs.mindmeasure.co.uk
  • Technology: Static site generator
  • Source Control: Git-based workflow
  • Deployment: Automated from repository

Collaboration Tools

  • Reviews: GitHub/GitLab pull requests
  • Planning: Issue tracking for documentation tasks
  • Communication: Team channels for documentation updates
  • Feedback: User feedback collection system

Documentation Templates

API Endpoint Documentation

## POST /api/endpoint
 
**Description**: Brief description of what this endpoint does
 
**Authentication**: Required/Optional
 
**Parameters**:
- `param1` (string, required): Description
- `param2` (number, optional): Description
 
**Request Example**:
```json
{
  "param1": "value",
  "param2": 123
}

Response Example:

{
  "success": true,
  "data": {...}
}

Error Responses:

  • 400: Bad Request - Invalid parameters
  • 401: Unauthorized - Authentication required
  • 500: Internal Server Error

### **Database Table Documentation**
```markdown
## table_name

**Purpose**: Description of what this table stores

**Schema**:
```sql
CREATE TABLE table_name (
    id UUID PRIMARY KEY,
    field1 TEXT NOT NULL,
    field2 JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

Indexes:

  • idx_table_field1: Optimizes queries on field1
  • idx_table_created_at: Optimizes date-based queries

RLS Policies:

  • Users can only access their own records
  • Admins have full access

Related Tables:

  • other_table: Relationship description

### **Feature Documentation**
```markdown
## Feature Name

**Overview**: Brief description of the feature

**User Journey**:
- User does X
- System responds with Y
- User sees Z

**Technical Implementation**:
- Frontend: Component/page details
- Backend: API endpoints used
- Database: Tables affected

**Security Considerations**:
- Authentication requirements
- Data privacy implications
- Access control

**Testing**:
- Unit tests: Location and coverage
- Integration tests: Scenarios covered
- User acceptance tests: Criteria

Implementation Checklist

Immediate Actions (This Week)

  • Add documentation tasks to all current development work
  • Review existing documentation for accuracy
  • Identify documentation gaps from recent changes
  • Set up documentation review process

Short Term (Next Month)

  • Implement automated documentation checks
  • Create documentation templates
  • Train team on documentation workflow
  • Set up documentation metrics

Long Term (Next Quarter)

  • Implement comprehensive documentation testing
  • Create user feedback system
  • Establish documentation governance
  • Regular documentation audits

Success Metrics

Quality Metrics

  • Documentation accuracy (% of docs that match implementation)
  • Documentation coverage (% of features documented)
  • User satisfaction with documentation
  • Time to find information

Process Metrics

  • Documentation updates per code change
  • Time between code change and documentation update
  • Documentation review completion rate
  • Documentation-related issues/bugs

Business Metrics

  • Reduced support tickets due to better documentation
  • Faster onboarding of new team members
  • Improved compliance audit results
  • Better stakeholder communication

Document Owner: Development Team
Last Updated: October 28, 2025
Next Review: November 28, 2025
Status: Active

Implementation CompleteHow to Add Documentation