Documentation Guidelines

Welcome to the FairDM documentation guidelines for contributors. This section covers how to write, organize, and validate documentation that serves the diverse FairDM community.

For Framework Contributors

If you’re contributing to the FairDM framework codebase, these guides will help you ensure your documentation is clear, well-organized, and properly validated:

Essential Guides

Information Architecture

Learn where documentation lives and how to determine the correct location for new content

Read the IA Guide →

Documentation Information Architecture

Feature Documentation Checklist

Track documentation updates for new features with a structured workflow

Learn the Workflow →

Feature Documentation Checklist Workflow

Cross-Reference Patterns

Link documentation to specifications and constitutional principles for traceability

Learn the Patterns →

Cross-Reference Patterns

Documentation Validation

Ensure your documentation builds correctly and meets quality standards

Learn Validation Rules →

Documentation Validation Rules

Quick Links

• Where do I add documentation? → Information Architecture

• How do I track documentation updates? → Feature Checklist Workflow

• How do I add cross-references? → Cross-Reference Patterns

• How do I validate documentation? → Validation Rules

• What are the writing standards? → Coming soon

Overview

FairDM documentation serves four distinct audiences, each with different needs:

Audience	Section	Purpose
Portal Users	docs/user-guide/	How to use a FairDM-powered portal
Portal Administrators	docs/portal-administration/	How to manage and configure a portal
Portal Developers	docs/portal-development/	How to build and customise a portal
Framework Contributors	docs/contributing/	How to contribute to FairDM itself

Important

These four sections are immutable — future features must use these section names and locations.

Documentation Principles

FairDM documentation follows these core principles from our Constitution:

1. Audience-First: Organize content by reader role, not by technical implementation

2. Traceability: Link documentation to specifications and governance principles

3. Quality Gates: Automated validation prevents broken links and incomplete documentation

4. FAIR-Aligned: Documentation itself follows FAIR principles (Findable, Accessible, Interoperable, Reusable)

Contributing to Documentation

Before You Write

1. Identify your audience: User, Admin, Developer, or Contributor?

2. Check existing content: Is there already documentation for this topic?

3. Consult the IA guide: Where should this documentation live?

While You Write

1. Follow the style guide: Clear, concise, example-rich content

2. Add cross-references: Link to specs, constitution, related docs

3. Include examples: Show, don’t just tell

4. Consider accessibility: Alt text for images, descriptive link text

After You Write

1. Run validation: Build docs locally and check for errors

2. Complete the checklist: Use the feature documentation checklist

3. Request review: Tag documentation reviewers in your PR

Tools and Resources

• Sphinx: Documentation build system (docs)

• MyST Parser: Markdown support for Sphinx (docs)

• PyData Theme: Our documentation theme (docs)

• Vale Linter: Prose linting tool (optional, for style consistency)

Getting Help

• Questions about where to document something? → File an issue

• Need help with MyST syntax? → MyST Syntax Reference

• Found a documentation bug? → Report it

---

Table of Contents

• Documentation Information Architecture
  • Overview
  • The Four Primary Sections
  • Decision Tree: Where Do I Document X?
  • File Creation Guidelines
  • Cross-Reference Patterns
  • Lifecycle Markers
  • Examples
  • FAQ
  • Validation
  • Related Documentation
• Feature Documentation Checklist Workflow
  • Overview
  • The 6-Step Workflow
  • Common Questions
  • Examples
  • Integration with Speckit
  • Related Documentation
• Cross-Reference Patterns
  • Why Cross-References Matter
  • Specification Cross-References
  • Constitution Cross-References
  • Anchor Generation Rules
  • Cross-Reference Checklist
  • Common Cross-Reference Scenarios
  • Integration with Feature Workflow
  • Validation Commands
  • Related Documentation
  • Questions & Troubleshooting
• Documentation Validation Rules
  • Overview
  • Validation Categories
  • Build Validation
  • Link Validation
  • Checklist Validation
  • CI/CD Integration
  • Running Validation Locally
  • Troubleshooting Validation Failures
  • Validation Configuration
  • Related Documentation
  • Summary

---

Ready to contribute documentation? Start with the Information Architecture Guide to find the right home for your content.