Documentation Workflow

Overview

Our documentation workflow encompasses the complete process of creating, maintaining, and publishing technical documentation using mdBook and GitHub-based collaboration.

Documentation Ecosystem

Primary Platform: mdBook static site generator
Content Format: Markdown with GitHub Flavored Markdown extensions
Version Control: Git-based content management
Collaboration: GitHub repository-based workflow
Deployment: Automated GitHub Actions to GitHub Pages

Content Creation Process

Planning & Structure

Content Planning: Outline documentation structure and scope
Information Architecture: Organize content hierarchically
SUMMARY.md: Define navigation and table of contents
Directory Structure: Create numbered, logical directory organization
Asset Planning: Identify required images, diagrams, and examples

Writing Workflow

# Documentation Creation Steps
1. Create branch for new content
2. Write content in Markdown format
3. Add supporting images and assets
4. Test locally with mdBook serve
5. Review and refine content
6. Commit and push changes
7. Create pull request for review
8. Merge and deploy automatically

Content Standards

Writing Style: Clear, concise technical writing
Structure: Logical hierarchy with consistent heading levels
Code Examples: Working, tested code snippets
Screenshots: High-quality, annotated images
Cross-references: Internal linking for navigation

Technical Implementation

mdBook Configuration

# book.toml configuration
[book]
title = "Documentation Title"
authors = ["Author Name"]
language = "en"
multilingual = false
src = "src"

[build]
build-dir = "book"
create-missing = true

[output.html]
default-theme = "light"
preferred-dark-theme = "navy"
copy-fonts = true
mathjax-support = true
git-repository-url = "https://github.com/user/repo"
git-repository-icon = "fa-github"

[output.html.search]
enable = true
limit-results = 30
teaser-word-count = 30
use-boolean-and = true
boost-title = 2
boost-hierarchy = 1
boost-paragraph = 1
expand = true
heading-split-level = 3

Content Organization

Documentation Structure:
src/
├── SUMMARY.md                    # Navigation structure
├── 0-introduction/               # Getting started
│   ├── README.md                # Main introduction
│   ├── overview.md              # Project overview
│   └── quick-start.md           # Quick start guide
├── 1-setup/                     # Installation and setup
│   ├── README.md                # Setup overview
│   ├── requirements.md          # System requirements
│   ├── installation.md          # Installation guide
│   └── configuration.md         # Configuration details
├── 2-usage/                     # User guide
│   ├── README.md                # Usage overview
│   ├── basic-usage.md           # Basic operations
│   ├── advanced-features.md     # Advanced functionality
│   └── examples/                # Usage examples
└── assets/                      # Shared assets
    ├── images/                  # Global images
    ├── css/                     # Custom stylesheets
    └── js/                      # Custom JavaScript

Quality Assurance Process

Content Review

Technical Accuracy: Verify all technical information
Code Testing: Test all code examples
Link Validation: Check all internal and external links
Image Optimization: Compress and optimize images
Accessibility: Ensure content is accessible to all users

Review Workflow

# Local review process
mdbook serve --open              # Live preview
mdbook test                      # Test code examples
mdbook build                     # Production build test

# Quality checks
markdownlint src/               # Markdown linting
vale src/                       # Prose linting
alex src/                       # Inclusive language check

Collaborative Workflow

Multi-author Workflow

Branch Creation: Feature branches for content updates
Parallel Development: Multiple authors working simultaneously
Conflict Resolution: Merge conflict handling
Review Process: Peer review before merging
Integration: Automated testing and deployment

GitHub Integration

# Pull request template
## Content Changes
- [ ] New content added
- [ ] Existing content updated
- [ ] Images optimized
- [ ] Links tested
- [ ] Local build successful

## Review Checklist
- [ ] Technical accuracy verified
- [ ] Writing quality reviewed
- [ ] Formatting consistent
- [ ] Navigation updated
- [ ] Ready for deployment

Automation & Deployment

Automated Workflows

Build Automation: GitHub Actions for mdBook builds
Quality Checks: Automated linting and testing
Deployment: Automatic publishing to GitHub Pages
Notification: Status updates on build success/failure
Backup: Automated content backup strategies

Deployment Pipeline

# GitHub Actions workflow
name: Deploy Documentation
on:
  push:
    branches: [main]
    paths: ['src/**', 'book.toml']
  pull_request:
    branches: [main]
    paths: ['src/**', 'book.toml']

jobs:
  test:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
      - name: Test build
        run: mdbook build
      - name: Test links
        run: mdbook test

  deploy:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
      - name: Build documentation
        run: mdbook build
      - name: Deploy to Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

Maintenance & Updates

Content Maintenance

Regular Reviews: Scheduled content audits
Link Monitoring: Automated link checking
Update Schedules: Planned content updates
Version Management: Content versioning strategies
Archive Strategy: Handling outdated content

Performance Optimization

# Performance optimization tasks
# Image compression
find src -name "*.png" -exec pngquant --ext .png --force {} \;

# Asset optimization
npx imagemin src/images/* --out-dir=src/images/optimized

# Build optimization
mdbook build --dest-dir book-optimized