backupchecks/TODO-documentation.md

TODO: Documentation System

Branch: v20260207-02-wiki-documentation Date Started: 2026-02-07 Date Updated: 2026-02-08 Status: In Progress - 10 of 33 pages complete

---

📊 Current Progress

Completed Sections ✅

Phase 1: Core Infrastructure (COMPLETE)

• ✅ Routes and blueprint setup
• ✅ Navigation sidebar with icons
• ✅ Base layout template
• ✅ CSS styling with dark mode support
• ✅ Breadcrumb navigation
• ✅ Previous/Next pagination
• ✅ Documentation menu item in navbar

Phase 2: Getting Started (3/3 pages - COMPLETE)

• ✅ What is BackupChecks?
• ✅ First Login & Dashboard
• ✅ Quick Start Checklist

Phase 3: Users Section (3/3 pages - COMPLETE)

• ✅ Users & Roles (with user-management.png screenshot)
• ✅ Login & Authentication (with Firefox recommendation)
• ✅ Profile Settings (with user-settings.png screenshot)

Phase 3: Customers & Jobs Section (4/4 pages - COMPLETE)

• ✅ Managing Customers (with edit-customer.png, new-customers.png)
• ✅ Configuring Jobs (with approve-job.png)
• ✅ Approved Jobs (with job-details.png)
• ✅ Job Schedules (with schedule-indicators.png)

Screenshots Added (10 total)

1. user-management.png - User role checkboxes
2. user-settings.png - Password change form
3. edit-customer.png - Customer edit dialog with Autotask mapping
4. new-customers.png - Customer creation and CSV import/export
5. approve-job.png - Inbox email detail with customer selection
6. job-details.png - Job detail page with schedule and history
7. schedule-indicators.png - Daily Jobs schedule with run status indicators

Remaining Work 🚧

Phase 3: Mail & Import (0/4 pages - PLACEHOLDER)

• ⏳ Mail Import Setup
• ⏳ Inbox Management
• ⏳ Mail Parsing
• ⏳ Auto-Import Configuration

Phase 3: Backup Review (0/5 pages - PLACEHOLDER)

• ⏳ Approving Backups
• ⏳ Daily Jobs View
• ⏳ Run Checks Modal
• ⏳ Overrides & Exceptions
• ⏳ Remarks & Tickets

Phase 4: Advanced Features (0/17 pages - PLACEHOLDER)

• Reports (0/4 pages)
• Autotask Integration (0/4 pages)
• Settings (0/6 pages)
• Troubleshooting (0/3 pages)

Progress Summary:

• ✅ 10 of 33 pages complete (30%)
• ✅ 10 screenshots added
• ✅ All completed pages reviewed and corrected based on actual UI
• ⏳ 23 pages remaining (placeholders created)

---

🎯 Goal

Add a static documentation system to BackupChecks for user onboarding and reference. A comprehensive guide explaining how the application works, accessible only to logged-in users.

---

✅ Requirements Summary

• Format: HTML templates (for full CSS control)
• Structure: Multiple pages with navigation menu
• Menu Item: "Documentation" with 📖 icon
• Access: Logged-in users only
• Content: Basic + Advanced topics (all features)
• Language: English only (app is not translated to Dutch)
• Screenshots: Yes, embedded in pages
• Maintenance: Static content updated via git (no in-app editing)

---

📋 Documentation Structure

Navigation Menu (Left Sidebar)

Documentation 📖
├─ 🏠 Getting Started
│  ├─ What is BackupChecks?
│  ├─ First Login & Dashboard
│  └─ Quick Start Checklist
│
├─ 👥 User Management
│  ├─ Users & Roles
│  ├─ Login & Authentication
│  └─ Profile Settings
│
├─ 💼 Customers & Jobs
│  ├─ Managing Customers
│  ├─ Configuring Jobs
│  ├─ Approved Jobs
│  └─ Job Schedules
│
├─ 📧 Mail & Import
│  ├─ Mail Import Setup
│  ├─ Inbox Management
│  ├─ Mail Parsing
│  └─ Auto-Import Configuration
│
├─ ✅ Backup Review
│  ├─ Approving Backups
│  ├─ Daily Jobs View
│  ├─ Run Checks Modal
│  ├─ Overrides & Exceptions
│  └─ Remarks & Tickets
│
├─ 📊 Reports
│  ├─ Creating Reports
│  ├─ Relative Periods
│  ├─ Report Scheduling
│  └─ Exporting Data
│
├─ 🎫 Autotask Integration
│  ├─ Setup & Configuration
│  ├─ Company Mapping
│  ├─ Creating Tickets
│  └─ Ticket Management
│
├─ ⚙️ Settings
│  ├─ General Settings
│  ├─ Mail Configuration
│  ├─ Autotask Integration
│  ├─ Reporting Settings
│  ├─ User Management
│  └─ Maintenance
│
└─ ❓ Troubleshooting
   ├─ Common Issues
   ├─ FAQ
   └─ Support Contact

---

🎨 UI Design

Layout Structure

┌─────────────────────────────────────────────────────┐
│ Navbar (standard app navbar)                        │
├──────────────┬──────────────────────────────────────┤
│              │                                       │
│  Navigation  │  Content Area                        │
│  Sidebar     │                                       │
│  (250px)     │  ┌─ Breadcrumb ───────────────────┐  │
│              │  │ Documentation > Getting Started │  │
│  📖 Docs     │  └─────────────────────────────────┘  │
│              │                                       │
│  🏠 Getting  │  <h1>What is BackupChecks?</h1>     │
│     Started  │                                       │
│   • What is  │  <p>BackupChecks is a...</p>         │
│   • First    │                                       │
│   • Quick    │  <img src="..." />                   │
│              │                                       │
│  👥 Users    │  <h2>Key Features</h2>               │
│   • Users &  │  <ul>...                             │
│   • Login    │                                       │
│              │  ┌─ Next/Previous ──────────────┐    │
│  💼 Customer │  │ ← Previous  |  Next →        │    │
│   • Managing │  └───────────────────────────────┘    │
│   • Config   │                                       │
│              │                                       │
│  ...         │                                       │
│              │                                       │
│              │                                       │
│              │                                       │
└──────────────┴──────────────────────────────────────┘

Navigation Sidebar (Fixed)

• Fixed position (scrolls with page)
• Collapsible sections (categories)
• Active page highlighted
• Icons per section
• Responsive: collapse to hamburger on mobile

Content Area

• Max-width for readability (800-900px)
• Breadcrumb navigation
• H1/H2/H3 hierarchy
• Code blocks with syntax highlighting
• Screenshots with captions
• Tables for settings/options
• Info/warning/tip callout boxes
• Next/Previous navigation at bottom

---

📂 File Structure

containers/backupchecks/src/
├── backend/app/main/
│   └── routes_documentation.py          # NEW: Documentation routes
│
├── templates/
│   ├── documentation/
│   │   ├── base.html                    # Base layout with sidebar
│   │   ├── _navigation.html             # Sidebar navigation menu
│   │   ├── getting-started/
│   │   │   ├── what-is-backupchecks.html
│   │   │   ├── first-login.html
│   │   │   └── quick-start.html
│   │   ├── users/
│   │   │   ├── users-and-roles.html
│   │   │   ├── login-authentication.html
│   │   │   └── profile-settings.html
│   │   ├── customers-jobs/
│   │   │   ├── managing-customers.html
│   │   │   ├── configuring-jobs.html
│   │   │   ├── approved-jobs.html
│   │   │   └── job-schedules.html
│   │   ├── mail-import/
│   │   │   ├── setup.html
│   │   │   ├── inbox-management.html
│   │   │   ├── mail-parsing.html
│   │   │   └── auto-import.html
│   │   ├── backup-review/
│   │   │   ├── approving-backups.html
│   │   │   ├── daily-jobs.html
│   │   │   ├── run-checks-modal.html
│   │   │   ├── overrides.html
│   │   │   └── remarks-tickets.html
│   │   ├── reports/
│   │   │   ├── creating-reports.html
│   │   │   ├── relative-periods.html
│   │   │   ├── scheduling.html
│   │   │   └── exporting-data.html
│   │   ├── autotask/
│   │   │   ├── setup-configuration.html
│   │   │   ├── company-mapping.html
│   │   │   ├── creating-tickets.html
│   │   │   └── ticket-management.html
│   │   ├── settings/
│   │   │   ├── general.html
│   │   │   ├── mail-configuration.html
│   │   │   ├── autotask-integration.html
│   │   │   ├── reporting-settings.html
│   │   │   ├── user-management.html
│   │   │   └── maintenance.html
│   │   └── troubleshooting/
│   │       ├── common-issues.html
│   │       ├── faq.html
│   │       └── support-contact.html
│   │
│   └── layout/base.html                 # Update: add Documentation menu item
│
└── static/
    ├── css/
    │   └── documentation.css            # NEW: Documentation-specific styles
    └── images/
        └── documentation/               # NEW: Screenshots folder
            ├── dashboard-overview.png
            ├── customer-list.png
            ├── job-configuration.png
            ├── inbox-view.png
            └── ... (more screenshots)

Total pages to create: ~30 HTML pages

---

🔧 Implementation Plan

Phase 1: Core Structure

1A. Routes Setup

File: containers/backupchecks/src/backend/app/main/routes_documentation.py

from flask import Blueprint, render_template
from flask_login import login_required

doc_bp = Blueprint('documentation', __name__, url_prefix='/documentation')

# Documentation structure (for navigation and routing)
DOCUMENTATION_STRUCTURE = {
    'getting-started': {
        'title': 'Getting Started',
        'icon': '🏠',
        'pages': [
            {'slug': 'what-is-backupchecks', 'title': 'What is BackupChecks?'},
            {'slug': 'first-login', 'title': 'First Login & Dashboard'},
            {'slug': 'quick-start', 'title': 'Quick Start Checklist'},
        ]
    },
    'users': {
        'title': 'User Management',
        'icon': '👥',
        'pages': [
            {'slug': 'users-and-roles', 'title': 'Users & Roles'},
            {'slug': 'login-authentication', 'title': 'Login & Authentication'},
            {'slug': 'profile-settings', 'title': 'Profile Settings'},
        ]
    },
    # ... (all other sections)
}

def get_navigation_context(current_section=None, current_page=None):
    """Build navigation context with active states."""
    return {
        'structure': DOCUMENTATION_STRUCTURE,
        'current_section': current_section,
        'current_page': current_page
    }

def get_prev_next(section, page_slug):
    """Get previous and next page for navigation."""
    # Flatten all pages into single list
    all_pages = []
    for sect_key, sect_data in DOCUMENTATION_STRUCTURE.items():
        for page in sect_data['pages']:
            all_pages.append({
                'section': sect_key,
                'slug': page['slug'],
                'title': page['title']
            })

    # Find current page index
    current_idx = None
    for i, p in enumerate(all_pages):
        if p['section'] == section and p['slug'] == page_slug:
            current_idx = i
            break

    if current_idx is None:
        return None, None

    prev_page = all_pages[current_idx - 1] if current_idx > 0 else None
    next_page = all_pages[current_idx + 1] if current_idx < len(all_pages) - 1 else None

    return prev_page, next_page

@doc_bp.route('/')
@doc_bp.route('/index')
@login_required
def index():
    """Documentation home - redirect to first page."""
    return redirect(url_for('documentation.page', section='getting-started', page='what-is-backupchecks'))

@doc_bp.route('/<section>/<page>')
@login_required
def page(section, page):
    """Render a documentation page."""
    # Validate section and page exist
    if section not in DOCUMENTATION_STRUCTURE:
        abort(404)

    section_data = DOCUMENTATION_STRUCTURE[section]
    page_exists = any(p['slug'] == page for p in section_data['pages'])
    if not page_exists:
        abort(404)

    # Get page title
    page_title = next(p['title'] for p in section_data['pages'] if p['slug'] == page)

    # Get navigation context
    nav_context = get_navigation_context(section, page)

    # Get prev/next pages
    prev_page, next_page = get_prev_next(section, page)

    # Render template
    template_path = f'documentation/{section}/{page}.html'
    return render_template(
        template_path,
        page_title=page_title,
        section_title=section_data['title'],
        navigation=nav_context,
        prev_page=prev_page,
        next_page=next_page
    )

1B. Register Blueprint

File: containers/backupchecks/src/backend/app/__init__.py

# Import documentation blueprint
from .main.routes_documentation import doc_bp

# Register blueprint
app.register_blueprint(doc_bp)

1C. Add Menu Item

File: containers/backupchecks/src/templates/layout/base.html

Add to navigation menu (after existing items):

<li class="nav-item">
  <a class="nav-link {% if request.path.startswith('/documentation') %}active{% endif %}"
     href="{{ url_for('documentation.index') }}">
    <span class="nav-icon">📖</span>
    Documentation
  </a>
</li>

1D. Base Layout Template

File: containers/backupchecks/src/templates/documentation/base.html

{% extends "layout/base.html" %}

{% block extra_css %}
<link rel="stylesheet" href="{{ url_for('static', filename='css/documentation.css') }}">
{% endblock %}

{% block content %}
<div class="documentation-container">
  <div class="row g-0">
    <!-- Sidebar Navigation -->
    <div class="col-12 col-lg-3 doc-sidebar-wrapper">
      {% include 'documentation/_navigation.html' %}
    </div>

    <!-- Content Area -->
    <div class="col-12 col-lg-9 doc-content-wrapper">
      <div class="doc-content">
        <!-- Breadcrumb -->
        <nav aria-label="breadcrumb" class="mb-4">
          <ol class="breadcrumb">
            <li class="breadcrumb-item">
              <a href="{{ url_for('documentation.index') }}">Documentation</a>
            </li>
            <li class="breadcrumb-item">{{ section_title }}</li>
            <li class="breadcrumb-item active" aria-current="page">{{ page_title }}</li>
          </ol>
        </nav>

        <!-- Page Content -->
        {% block doc_content %}{% endblock %}

        <!-- Previous/Next Navigation -->
        <div class="doc-pagination mt-5 pt-4 border-top">
          <div class="row">
            <div class="col-6">
              {% if prev_page %}
              <a href="{{ url_for('documentation.page', section=prev_page.section, page=prev_page.slug) }}"
                 class="btn btn-outline-secondary">
                ← {{ prev_page.title }}
              </a>
              {% endif %}
            </div>
            <div class="col-6 text-end">
              {% if next_page %}
              <a href="{{ url_for('documentation.page', section=next_page.section, page=next_page.slug) }}"
                 class="btn btn-outline-primary">
                {{ next_page.title }} →
              </a>
              {% endif %}
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>
{% endblock %}

1E. Navigation Sidebar

File: containers/backupchecks/src/templates/documentation/_navigation.html

<nav class="doc-nav">
  <div class="doc-nav-header">
    <h5>📖 Documentation</h5>
  </div>

  {% for section_key, section_data in navigation.structure.items() %}
  <div class="doc-nav-section {% if section_key == navigation.current_section %}active{% endif %}">
    <div class="doc-nav-section-title">
      <span class="doc-nav-icon">{{ section_data.icon }}</span>
      {{ section_data.title }}
    </div>

    <ul class="doc-nav-pages">
      {% for page in section_data.pages %}
      <li class="{% if section_key == navigation.current_section and page.slug == navigation.current_page %}active{% endif %}">
        <a href="{{ url_for('documentation.page', section=section_key, page=page.slug) }}">
          {{ page.title }}
        </a>
      </li>
      {% endfor %}
    </ul>
  </div>
  {% endfor %}
</nav>

1F. CSS Styling

File: containers/backupchecks/src/static/css/documentation.css

/* Documentation Container */
.documentation-container {
  margin-top: 20px;
}

/* Sidebar */
.doc-sidebar-wrapper {
  border-right: 1px solid #dee2e6;
  min-height: calc(100vh - 80px);
}

.doc-nav {
  position: sticky;
  top: 20px;
  padding: 20px;
  max-height: calc(100vh - 100px);
  overflow-y: auto;
}

.doc-nav-header h5 {
  margin-bottom: 20px;
  padding-bottom: 10px;
  border-bottom: 2px solid #007bff;
}

.doc-nav-section {
  margin-bottom: 20px;
}

.doc-nav-section-title {
  font-weight: 600;
  margin-bottom: 10px;
  padding: 8px 12px;
  background-color: #f8f9fa;
  border-radius: 4px;
  cursor: pointer;
}

.doc-nav-section.active .doc-nav-section-title {
  background-color: #e7f1ff;
  color: #0056b3;
}

.doc-nav-icon {
  margin-right: 8px;
}

.doc-nav-pages {
  list-style: none;
  padding-left: 30px;
  margin: 0;
}

.doc-nav-pages li {
  margin: 5px 0;
}

.doc-nav-pages li a {
  display: block;
  padding: 5px 10px;
  color: #495057;
  text-decoration: none;
  border-radius: 4px;
  transition: all 0.2s;
}

.doc-nav-pages li a:hover {
  background-color: #f8f9fa;
  color: #007bff;
}

.doc-nav-pages li.active a {
  background-color: #007bff;
  color: white;
  font-weight: 500;
}

/* Content Area */
.doc-content-wrapper {
  padding: 20px 40px;
}

.doc-content {
  max-width: 900px;
  margin: 0 auto;
}

.doc-content h1 {
  margin-bottom: 30px;
  padding-bottom: 15px;
  border-bottom: 3px solid #007bff;
}

.doc-content h2 {
  margin-top: 40px;
  margin-bottom: 20px;
  color: #0056b3;
}

.doc-content h3 {
  margin-top: 30px;
  margin-bottom: 15px;
}

.doc-content img {
  max-width: 100%;
  height: auto;
  border: 1px solid #dee2e6;
  border-radius: 4px;
  margin: 20px 0;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

.doc-content figcaption {
  text-align: center;
  font-style: italic;
  color: #6c757d;
  margin-top: -15px;
  margin-bottom: 20px;
}

/* Code Blocks */
.doc-content pre {
  background-color: #f8f9fa;
  border: 1px solid #dee2e6;
  border-radius: 4px;
  padding: 15px;
  overflow-x: auto;
}

.doc-content code {
  background-color: #f8f9fa;
  padding: 2px 6px;
  border-radius: 3px;
  font-family: 'Courier New', monospace;
  font-size: 0.9em;
}

.doc-content pre code {
  background-color: transparent;
  padding: 0;
}

/* Tables */
.doc-content table {
  width: 100%;
  margin: 20px 0;
  border-collapse: collapse;
}

.doc-content table th,
.doc-content table td {
  padding: 12px;
  border: 1px solid #dee2e6;
  text-align: left;
}

.doc-content table th {
  background-color: #f8f9fa;
  font-weight: 600;
}

.doc-content table tr:nth-child(even) {
  background-color: #f8f9fa;
}

/* Callout Boxes */
.doc-callout {
  padding: 15px 20px;
  margin: 20px 0;
  border-left: 4px solid;
  border-radius: 4px;
}

.doc-callout-info {
  background-color: #e7f3ff;
  border-left-color: #007bff;
}

.doc-callout-warning {
  background-color: #fff3cd;
  border-left-color: #ffc107;
}

.doc-callout-tip {
  background-color: #d4edda;
  border-left-color: #28a745;
}

.doc-callout-danger {
  background-color: #f8d7da;
  border-left-color: #dc3545;
}

.doc-callout strong {
  display: block;
  margin-bottom: 5px;
}

/* Pagination */
.doc-pagination {
  margin-top: 40px;
}

/* Responsive */
@media (max-width: 991px) {
  .doc-sidebar-wrapper {
    border-right: none;
    border-bottom: 1px solid #dee2e6;
    min-height: auto;
  }

  .doc-nav {
    position: static;
    max-height: none;
  }

  .doc-content-wrapper {
    padding: 20px 15px;
  }
}

---

📝 Content Template Example

File: containers/backupchecks/src/templates/documentation/getting-started/what-is-backupchecks.html

{% extends "documentation/base.html" %}

{% block doc_content %}
<h1>What is BackupChecks?</h1>

<p class="lead">
  BackupChecks is a backup monitoring and validation system designed to help IT teams
  verify that backups are running successfully across their customer infrastructure.
</p>

<h2>Key Features</h2>

<ul>
  <li><strong>Automated Mail Parsing:</strong> Import backup reports via email and automatically parse results</li>
  <li><strong>Approval Workflow:</strong> Review and approve backup jobs on a daily basis</li>
  <li><strong>Customer Management:</strong> Organize backups by customer and manage multiple backup jobs per customer</li>
  <li><strong>Autotask Integration:</strong> Create tickets in Autotask PSA for failed backups</li>
  <li><strong>Reporting:</strong> Generate backup status reports with flexible scheduling</li>
  <li><strong>Role-Based Access:</strong> Admin, Operator, Reporter, and Viewer roles</li>
</ul>

<figure>
  <img src="{{ url_for('static', filename='images/documentation/dashboard-overview.png') }}"
       alt="BackupChecks Dashboard Overview" />
  <figcaption>Figure 1: BackupChecks Dashboard showing daily backup status</figcaption>
</figure>

<h2>How It Works</h2>

<p>BackupChecks follows a simple workflow:</p>

<ol>
  <li><strong>Import:</strong> Backup reports are sent via email to a configured mailbox</li>
  <li><strong>Parse:</strong> The system parses email content to extract backup status</li>
  <li><strong>Match:</strong> Reports are matched to configured jobs based on sender, subject, and content</li>
  <li><strong>Review:</strong> Operators review backup status and approve successful jobs</li>
  <li><strong>Alert:</strong> Failed backups can trigger Autotask tickets or manual follow-up</li>
  <li><strong>Report:</strong> Generate periodic reports to track backup health over time</li>
</ol>

<div class="doc-callout doc-callout-info">
  <strong>💡 Tip:</strong>
  Start with the <a href="{{ url_for('documentation.page', section='getting-started', page='quick-start') }}">Quick Start Checklist</a>
  to get your first customer and job configured.
</div>

<h2>Who Should Use BackupChecks?</h2>

<p>BackupChecks is designed for:</p>

<ul>
  <li><strong>Managed Service Providers (MSPs):</strong> Monitor backups across multiple customer environments</li>
  <li><strong>IT Departments:</strong> Track backup compliance for internal infrastructure</li>
  <li><strong>Backup Administrators:</strong> Centralize backup verification from multiple backup solutions</li>
</ul>

<h2>Supported Backup Software</h2>

<p>BackupChecks supports parsing backup reports from:</p>

<table>
  <thead>
    <tr>
      <th>Software</th>
      <th>Support Level</th>
      <th>Notes</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Veeam Backup & Replication</td>
      <td>Full</td>
      <td>Email notifications with detailed job status</td>
    </tr>
    <tr>
      <td>Acronis Cyber Protect</td>
      <td>Full</td>
      <td>Backup completion reports</td>
    </tr>
    <tr>
      <td>Synology Active Backup</td>
      <td>Full</td>
      <td>Task result notifications</td>
    </tr>
    <tr>
      <td>Custom/Other</td>
      <td>Configurable</td>
      <td>Manual job configuration for non-standard formats</td>
    </tr>
  </tbody>
</table>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Important:</strong>
  BackupChecks monitors backup <em>reports</em>, not the backup data itself. Ensure your backup software is configured to send email notifications on job completion.
</div>

<h2>Next Steps</h2>

<p>Ready to get started? Continue to:</p>

<ul>
  <li><a href="{{ url_for('documentation.page', section='getting-started', page='first-login') }}">First Login & Dashboard</a> - Learn about the dashboard interface</li>
  <li><a href="{{ url_for('documentation.page', section='getting-started', page='quick-start') }}">Quick Start Checklist</a> - Set up your first customer and job</li>
  <li><a href="{{ url_for('documentation.page', section='mail-import', page='setup') }}">Mail Import Setup</a> - Configure email integration</li>
</ul>

{% endblock %}

---

✅ Testing Checklist

Navigation & Routing

• Navigate to /documentation - redirects to first page
• Click on sidebar navigation - loads correct page
• Breadcrumb shows correct hierarchy
• Previous/Next buttons work correctly
• Previous button hidden on first page
• Next button hidden on last page
• Active page highlighted in sidebar
• Active section expanded in sidebar

Access Control

• Not logged in - redirected to login
• Logged in as admin - can access all pages
• Logged in as operator - can access all pages
• Logged in as viewer - can access all pages
• Documentation menu item highlighted when active

Content Rendering

• All 30+ pages render without errors
• Images load correctly
• Screenshots display with proper sizing
• Code blocks formatted correctly
• Tables display properly
• Callout boxes styled correctly
• Links between pages work
• External links open in new tab

Responsive Design

• Desktop (1920x1080) - sidebar fixed, content readable
• Laptop (1366x768) - layout works
• Tablet (768x1024) - sidebar collapses or stacks
• Mobile (375x667) - content readable, navigation accessible

Performance

• Page loads fast (<500ms)
• Images optimized (screenshots compressed)
• CSS minified
• No console errors

---

📸 Screenshot Guidelines

Taking Screenshots

• Resolution: 1920x1080 (full HD)
• Browser: Chrome/Edge in normal mode (not incognito)
• Zoom: 100% (default browser zoom)
• Format: PNG (for UI clarity)
• Compression: Use tools like TinyPNG to reduce file size
• Naming: Descriptive kebab-case (e.g., customer-list-view.png)

Screenshot Checklist

• Remove sensitive/real customer data (use dummy data)
• Blur or hide any sensitive information
• Crop to relevant area (don't include browser chrome unless needed)
• Add borders/shadows for visual depth (done in CSS)
• Include captions explaining what's shown

Required Screenshots (Minimum)

• Dashboard overview
• Customer list page
• Job configuration modal
• Inbox with unread messages
• Daily Jobs view
• Run Checks modal (approve/reject)
• Settings pages (all tabs)
• Reports creation page
• Autotask integration settings

---

📋 Content Writing Guidelines

Style Guide

• Tone: Professional but friendly
• Person: Second person (you/your, not we/our)
• Tense: Present tense for instructions
• Voice: Active voice preferred
• Length: Concise but complete (aim for scanability)

Structure

• H1: Page title (only one per page)
• H2: Major sections
• H3: Subsections
• Lists: Use for steps, features, options
• Paragraphs: Keep short (2-4 sentences max)
• Callouts: Use for tips, warnings, important notes

Example Phrasing

✅ Good: "Click the New Customer button to add a customer" ❌ Bad: "We can add a new customer by clicking on the button"

✅ Good: "BackupChecks monitors backup reports via email" ❌ Bad: "BackupChecks will monitor the backup reports that are sent via email"

Callout Usage

• Info (Blue): General information, tips, context
• Warning (Yellow): Important considerations, limitations
• Tip (Green): Best practices, shortcuts, recommendations
• Danger (Red): Critical warnings, data loss risks

---

🚀 Implementation Phases

Phase 1: Core Infrastructure ✅ COMPLETE

• Create routes file and blueprint
• Add documentation menu item
• Create base layout template
• Create navigation sidebar template
• Create CSS styling
• Test routing and navigation
• Fix CSS image centering
• Add dark mode support

Status: COMPLETE Time Spent: ~4 hours

Phase 2: Content Pages - Getting Started ✅ COMPLETE

• What is BackupChecks?
• First Login & Dashboard
• Quick Start Checklist
• Take screenshots for Getting Started section

Status: COMPLETE Time Spent: ~6 hours

Phase 3: Content Pages - Core Features 🚧 IN PROGRESS (7 of 16 complete)

• User Management (3 pages) ✅
  • Users & Roles
  • Login & Authentication
  • Profile Settings
• Customers & Jobs (4 pages) ✅
  • Managing Customers
  • Configuring Jobs
  • Approved Jobs
  • Job Schedules
• Mail & Import (4 pages) ⏳
  • Mail Import Setup
  • Inbox Management
  • Mail Parsing
  • Auto-Import Configuration
• Backup Review (5 pages) ⏳
  • Approving Backups
  • Daily Jobs View
  • Run Checks Modal
  • Overrides & Exceptions
  • Remarks & Tickets
• Take screenshots for core features (10 screenshots added)

Status: 43% complete (7/16 pages) Time Spent: ~12 hours Remaining: ~8 hours

Phase 4: Content Pages - Advanced Features

• Reports (4 pages)
• Autotask Integration (4 pages)
• Settings (6 pages)
• Troubleshooting (3 pages)
• Take screenshots for advanced features

Estimated Complexity: High Time Estimate: 8-12 hours

Phase 5: Polish & Review

• Proofread all content
• Verify all links work
• Optimize all images
• Test on different screen sizes
• Get user feedback

Estimated Complexity: Low Time Estimate: 2-4 hours

Total Estimate: 24-38 hours of work

---

📝 Page Content Outline (Template)

For each page, follow this structure:

1. Page Title (H1)
2. Introduction paragraph (what this page covers)
3. Main content sections (H2)
   - Explanatory text
   - Screenshots/images
   - Step-by-step instructions (if applicable)
   - Tables for settings/options (if applicable)
4. Callout boxes (tips, warnings)
5. Related pages / Next steps (end of page)

---

🎯 Success Criteria

• All 30+ documentation pages created and accessible
• Navigation works seamlessly (sidebar + prev/next)
• All screenshots embedded and displaying correctly
• Content is clear, accurate, and helpful for new users
• Pages load quickly (<500ms)
• Mobile-responsive design works on all screen sizes
• No broken links or missing images
• Access restricted to logged-in users only
• Documentation menu item integrated in navbar

---

🔮 Future Enhancements (Post-MVP)

• Search functionality: Full-text search across all pages
• Keyboard shortcuts: Navigate pages with arrow keys
• Dark mode: Theme toggle for documentation
• Print stylesheet: Printer-friendly version
• Video tutorials: Embed short walkthrough videos
• Feedback widget: "Was this helpful?" on each page
• Version indicator: Show app version documentation matches
• PDF export: Export entire documentation as PDF
• Changelog page: Document what's new in each version

---

📂 Important Files Summary

Backend:
- routes_documentation.py              # NEW: Documentation routes + navigation structure

Templates:
- documentation/base.html              # NEW: Base layout with sidebar
- documentation/_navigation.html       # NEW: Sidebar navigation
- documentation/*//*.html              # NEW: 30+ content pages
- layout/base.html                     # MODIFY: Add Documentation menu item

Static Files:
- static/css/documentation.css         # NEW: Documentation styling
- static/images/documentation/*        # NEW: Screenshots folder

Docs:
- changelog-claude.md                  # UPDATE: Document feature addition

---

💡 Notes

• Language: All content in English (app is not translated)
• Maintenance: Content updated via git (no in-app editing)
• Access: Login required (@login_required on all routes)
• Screenshots: Use dummy/anonymized data only
• Style: Professional tone, second person, active voice
• Structure: Hierarchical navigation, prev/next pagination
• Performance: Optimize images, minify CSS
• Responsive: Mobile-friendly sidebar and content