Documentation Style Guide Complete

This guide explains the approach and principles used to create comprehensive HTML documentation for infrastructure and software projects.

Icon Legend
Critical/Danger Warning/Important Success/Complete Information Active/Key Integration

Philosophy

Documentation as Architecture

Documentation should mirror and reinforce the software architecture. Each component gets its own focused document that clearly explains its purpose, boundaries, and relationships.

User-Centric Design

Documentation serves multiple audiences:

  • Developers need technical details and implementation guidance
  • Stakeholders need high-level overviews and business context
  • Red Panda needs approval checkpoints and critical decisions highlighted

Living Documentation

Documentation evolves with the codebase and captures both current state and architectural decisions.

Structure Principles

1. Hierarchical Information Architecture

Main Documentation (project.html)
├── Component Docs (component1.html, component2.html, etc.)
├── Standards References (docs/standards/)
└── Supporting Materials (README.md, style guides)

2. Consistent Navigation

Every document includes:

  • Navigation bar with key sections
  • Cross-references to related components
  • Return links to main documentation

3. Progressive Disclosure

Information flows from general to specific:

Overview → Architecture → Implementation → Details

Visual Design Principles

1. Clean Typography

  • System fonts for readability
  • Generous line spacing (1.6)
  • Clear hierarchy with consistent heading sizes

2. Color-Coded Information Types

Bootstrap Alert Classes (Preferred):

  • alert alert-danger - Critical decisions requiring immediate attention
  • alert alert-warning - Important context and warnings
  • alert alert-success - Completed features and positive outcomes
  • alert alert-info - Technical architecture information
  • alert alert-primary - Key workflows and processes
  • alert alert-secondary - Cross-component integration details

Legacy Custom Classes (Backward Compatible):

  • .tech-stack - Technical architecture information
  • .critical - Important decisions requiring attention
  • .workflow - Process and workflow information
  • .integration - Cross-component integration details

3. Responsive Layout

  • Bootstrap grid system for all screen sizes
  • Consistent spacing with utility classes
  • Card-based information grouping

Bootstrap Icons Integration

Setup

Add Bootstrap Icons CDN to your HTML documents:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.0/font/bootstrap-icons.css">

Benefits:

  • Minimal overhead (~75KB)
  • 2000+ icons matching Bootstrap design
  • CDN caching for fast loading

Common Icon Patterns

Status & Progress
  • bi-check-square - Completed
  • bi-square - Pending
  • bi-hourglass-split - In Progress
  • bi-x-circle - Failed/Error
Navigation
  • bi-house-door - Home
  • bi-arrow-left - Back
  • bi-box-arrow-up-right - External
  • bi-link-45deg - Link
Alerts
  • bi-exclamation-triangle-fill - Danger
  • bi-exclamation-circle-fill - Warning
  • bi-info-circle-fill - Info
  • bi-check-circle-fill - Success
Technical
  • bi-code-slash - Code
  • bi-database - Database
  • bi-cpu - System
  • bi-plug - API/Integration

Usage Examples

Section Headers with Icons
<h2><i class="bi bi-book section-icon"></i>Section Title</h2>
Alert Boxes with Icons
<div class="alert alert-info border-start border-4 border-info">
  <h3><i class="bi bi-info-circle-fill alert-icon"></i>Information</h3>
</div>
Badges with Icons
<span class="badge bg-success"><i class="bi bi-check-circle-fill"></i> Complete</span>
List Items with Icons
<li><i class="bi bi-check-circle"></i> Completed task</li>
<li><i class="bi bi-arrow-right-short"></i> Action item</li>

Best Practices

  • Use semantic icons that match content meaning
  • Maintain consistent icon usage across documents
  • Don't overuse icons - they should enhance, not clutter
  • Ensure icons are visible and meaningful at all screen sizes
  • Icons should supplement text, not replace it (accessibility)

Implementation Guidelines

HTML Document Template

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document Title</title>
    <!-- Bootstrap CSS -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
    <!-- Bootstrap Icons -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.0/font/bootstrap-icons.css">
</head>
<body>
    <div class="container-fluid">
        <!-- Navigation -->
        <nav class="navbar navbar-dark bg-dark rounded mb-4">
            <a class="navbar-brand" href="main.html">
                <i class="bi bi-arrow-left"></i> Back
            </a>
        </nav>
        
        <!-- Breadcrumb -->
        <nav aria-label="breadcrumb">
            <ol class="breadcrumb">
                <li class="breadcrumb-item"><a href="main.html"><i class="bi bi-house-door"></i> Main</a></li>
                <li class="breadcrumb-item active">Current Page</li>
            </ol>
        </nav>
        
        <!-- Content -->
        <h1><i class="bi bi-journal-code"></i> Page Title</h1>
        
        <!-- Sections -->
    </div>
    
    <!-- Bootstrap JS -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
    
    <!-- Dark mode support -->
    <script>
        if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
            document.documentElement.setAttribute('data-bs-theme', 'dark');
        }
    </script>
</body>
</html>

Dark Mode Support

Bootstrap 5.3+ includes built-in dark mode support. Add this script to automatically detect system preferences:

<script>
  if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
    document.documentElement.setAttribute('data-bs-theme', 'dark');
  }
</script>

Scroll to Top Button

Add a floating button for easy navigation in long documents:

<button id="scrollTopBtn" class="btn btn-primary">
  <i class="bi bi-arrow-up-circle"></i>
</button>

<script>
  window.onscroll = function() {
    if (document.documentElement.scrollTop > 300) {
      document.getElementById('scrollTopBtn').style.display = 'block';
    } else {
      document.getElementById('scrollTopBtn').style.display = 'none';
    }
  };
  document.getElementById('scrollTopBtn').onclick = function() {
    window.scrollTo({top: 0, behavior: 'smooth'});
  };
</script>

Quality Standards

Style Guide Implementation: 100% Complete

Technical Accuracy

  • All code examples must work
  • All URLs must be valid
  • All relationships must be correct

Clarity and Completeness

  • Each section serves a specific purpose
  • Information is neither duplicated nor missing
  • Cross-references are accurate

Professional Presentation

  • Consistent formatting throughout
  • Clean visual hierarchy
  • Responsive design for all devices

This style guide ensures consistent, professional, and maintainable documentation that serves both technical and business needs while supporting the long-term success of your projects.