ivooskamp/backupchecks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7b4b889911
backupchecks/TODO-documentation.md

1306 lines
40 KiB
Markdown
Raw Blame History

# TODO: Documentation System
**Branch:** `v20260207-02-wiki-documentation`
**Date Started:** 2026-02-07
**Date Updated:** 2026-02-08 (Latest: Per-job review corrections)
**Status:** Review Required - full documentation verification against current UI/flows
---
## ✅ Validation Update (2026-03-26)
This TODO was re-checked against the current codebase and documentation templates.
Findings:
- The progress metrics in this file are outdated (`19/33`) and no longer reflect the repository state.
- The documentation template tree currently contains **39 files** under `containers/backupchecks/src/templates/documentation`.
- Because the app layout and multiple workflows changed after the original documentation wave, **all documentation pages require content review** for functional correctness (not only layout styling).
Decision:
- Keep this TODO active.
- Treat this as a full documentation audit task: verify each page against current UI/routes/behavior and update screenshots/text where needed.
---
## 🧾 Review Checklist (2026-03-26)
Gebruik deze lijst voor de volledige inhoudsreview tegen de huidige applicatie.
**Legenda**
- `P1` = hoge prioriteit (kritieke workflows / grootste kans op afwijkingen)
- `P2` = normale prioriteit
- `P3` = lage prioriteit
### Global checks (voor elke pagina)
- [ ] Route, paginatitel en navigatiepad kloppen met huidige UI
- [ ] Terminologie klopt met huidige labels/knoppen in de app
- [ ] Screenshots zijn actueel (nieuwe layout) of vervangen/verwijderd
- [ ] Tekst verwijst niet naar verwijderde/gewijzigde functies
- [ ] Role-based behavior (admin/operator/viewer/reporter) klopt
### Missing documentation topics (new pages required)
- [x] `[P1]` Cove Accounts + Cove run detail flow documenteren
- [x] `[P1]` Veeam Cloud Connect accounts/run flow documenteren
- [x] `[P1]` Run Checks Autotask "Link existing" gedrag updaten (incl. cross-company)
- [ ] `[P1]` Sidebar layout v2 consistent door alle docs verwerken
### Page-by-page review
#### Getting Started
- [ ] `[P2]` getting-started/what-is-backupchecks
- [ ] `[P2]` getting-started/first-login
- [ ] `[P2]` getting-started/quick-start
#### User Management
- [ ] `[P2]` users/users-and-roles
- [ ] `[P2]` users/login-authentication
- [ ] `[P2]` users/profile-settings
#### Customers & Jobs
- [ ] `[P2]` customers-jobs/managing-customers
- [ ] `[P2]` customers-jobs/configuring-jobs
- [ ] `[P2]` customers-jobs/approved-jobs
- [ ] `[P2]` customers-jobs/job-schedules
#### Mail & Import
- [ ] `[P1]` mail-import/setup
- [ ] `[P1]` mail-import/inbox-management
- [ ] `[P1]` mail-import/mail-parsing
- [ ] `[P1]` mail-import/auto-import
#### Backup Review
- [ ] `[P1]` backup-review/approving-backups
- [ ] `[P1]` backup-review/daily-jobs
- [ ] `[P1]` backup-review/run-checks-modal
- [ ] `[P1]` backup-review/overrides
- [ ] `[P1]` backup-review/remarks-tickets
#### Reports
- [ ] `[P1]` reports/creating-reports
- [ ] `[P1]` reports/relative-periods
- [ ] `[P1]` reports/scheduling
- [ ] `[P1]` reports/exporting-data
#### Autotask Integration
- [x] `[P1]` autotask/setup-configuration
- [x] `[P1]` autotask/company-mapping
- [x] `[P1]` autotask/creating-tickets
- [x] `[P1]` autotask/ticket-management
#### Settings
- [x] `[P1]` settings/general
- [x] `[P1]` settings/mail-configuration
- [x] `[P1]` settings/autotask-integration
- [x] `[P1]` settings/entra-sso
- [x] `[P1]` settings/reporting-settings
- [x] `[P1]` settings/user-management
- [x] `[P1]` settings/maintenance
#### Troubleshooting
- [ ] `[P2]` troubleshooting/common-issues
- [ ] `[P2]` troubleshooting/faq
- [ ] `[P2]` troubleshooting/support-contact
---
## 🔎 Batch 1 Findings (P1) — 2026-03-26
### A. Immediate correctness fixes (existing content)
- [x] `documentation/backup-review/daily-jobs.html`
- Remove/replace incorrect claim that successful jobs are automatically reviewed.
- Align workflow text with current behavior: review is handled via Run Checks job-level review.
- [x] `documentation/backup-review/approving-backups.html`
- Replace wording "select multiple runs" with "select multiple jobs" where bulk review is described.
- Re-verify Daily Jobs vs Run Checks role split text for current operational flow.
- [x] `documentation/backup-review/run-checks-modal.html`
- Fix broken cross-link: `url_for('documentation.page', section='autotask', page='overview')` does not exist.
- Replace with valid links to existing Autotask pages.
- [x] `documentation/backup-review/remarks-tickets.html`
- Fix same broken `autotask/overview` link.
- Re-check Autotask behavior section against current link-existing/create/resolve-note flow.
### B. Placeholder pages that require full rewrite (currently "Coming Soon")
- [ ] `documentation/reports/creating-reports.html`
- [ ] `documentation/reports/relative-periods.html`
- [ ] `documentation/reports/scheduling.html`
- [ ] `documentation/reports/exporting-data.html`
- [x] `documentation/autotask/setup-configuration.html`
- [x] `documentation/autotask/company-mapping.html`
- [x] `documentation/autotask/creating-tickets.html`
- [x] `documentation/autotask/ticket-management.html`
- [x] `documentation/settings/general.html`
- [x] `documentation/settings/mail-configuration.html`
- [x] `documentation/settings/autotask-integration.html`
- [x] `documentation/settings/reporting-settings.html`
- [x] `documentation/settings/user-management.html`
- [x] `documentation/settings/maintenance.html`
### C. Pages with content present but requiring targeted re-validation
- [x] `documentation/settings/entra-sso.html`
- Verify navigation path labels (Integrations wording/layout) against current settings UI.
- Keep untested warning unless production validation has been completed.
- [ ] `documentation/mail-import/setup.html`
- Re-check exact settings navigation wording and folder-browser flow against current UI labels.
- [ ] `documentation/mail-import/auto-import.html`
- Re-check references to Logging page path/wording and Imports section labels.
---
## 🔎 Batch 2 Findings (P1) — 2026-03-26 (Completed)
### A. Autotask docs rewritten from placeholders
- [x] `documentation/autotask/setup-configuration.html`
- [x] `documentation/autotask/company-mapping.html`
- [x] `documentation/autotask/creating-tickets.html`
- [x] `documentation/autotask/ticket-management.html`
### B. Autotask behavior alignment fixes
- [x] Documented `Link existing` cross-company behavior for shared/umbrella tickets.
- [x] Removed references to non-existent `autotask/overview` page and replaced broken links.
- [x] Re-validated ticket lifecycle notes (create/link/resolve note) against current Run Checks behavior.
---
## 🔎 Batch 3 Findings (P1) — 2026-03-26 (Completed)
### A. Settings docs rewritten from placeholders
- [x] `documentation/settings/general.html`
- [x] `documentation/settings/mail-configuration.html`
- [x] `documentation/settings/autotask-integration.html`
- [x] `documentation/settings/reporting-settings.html`
- [x] `documentation/settings/user-management.html`
- [x] `documentation/settings/maintenance.html`
### B. Settings content alignment notes
- [x] Re-validated `documentation/settings/entra-sso.html` against current Settings -> Integrations navigation and field names.
- [x] Reporting page updated to explicitly document current status: no dedicated Reporting settings card is available in Settings.
- [x] Removed all placeholder text from Settings documentation pages.
---
## 📊 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)
**Phase 3: Mail & Import (4/4 pages - COMPLETE)**
- ✅ Mail Import Setup
- ✅ Inbox Management
- ✅ Mail Parsing
- ✅ Auto-Import Configuration
**Phase 3: Backup Review (5/5 pages - COMPLETE)**
- ✅ Approving Backups (corrected for per-job review)
- ✅ Daily Jobs View
- ✅ Run Checks Modal (corrected for per-job review, removed non-existent reviewed indicator)
- ✅ Overrides & Exceptions
- ✅ Remarks & Tickets
**Latest Corrections (2026-02-08):**
- Fixed per-job review mechanism documentation (review is per-JOB, not per individual run)
- Removed non-existent "reviewed indicator" from Run Checks Modal
- Corrected bulk review description from "select runs" to "select jobs"
- Updated Unmark Reviewed section to reflect per-job unmarking
- Removed incorrect statement that successful runs are automatically reviewed
### 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 4: Advanced Features (10/14 pages complete)**
- Reports (0/4 pages)
- Autotask Integration (4/4 pages - COMPLETE)
- Settings (6/6 pages - COMPLETE)
- Troubleshooting (0/3 pages)
**Progress Summary:**
- ✅ Batch 1 documentation updates completed (Integrations + critical Run Checks wording/link fixes).
- ✅ Batch 2 documentation updates completed (Autotask section rewritten and aligned with current behavior).
- ✅ Batch 3 documentation updates completed (Settings section rewritten and revalidated).
- ⏳ Remaining focus: Mail Import re-validation pages, Troubleshooting pages, and final Sidebar Layout v2 consistency pass.
---
## 🎯 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`
```python
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`
```python
# 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):
```html
<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`
```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`
```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`
```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`
```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
- [x] Create routes file and blueprint
- [x] Add documentation menu item
- [x] Create base layout template
- [x] Create navigation sidebar template
- [x] Create CSS styling
- [x] Test routing and navigation
- [x] Fix CSS image centering
- [x] Add dark mode support
**Status:** COMPLETE
**Time Spent:** ~4 hours
### Phase 2: Content Pages - Getting Started ✅ COMPLETE
- [x] What is BackupChecks?
- [x] First Login & Dashboard
- [x] Quick Start Checklist
- [x] Take screenshots for Getting Started section
**Status:** COMPLETE
**Time Spent:** ~6 hours
### Phase 3: Content Pages - Core Features ✅ COMPLETE (16 of 16 complete)
- [x] User Management (3 pages) ✅
- [x] Users & Roles
- [x] Login & Authentication
- [x] Profile Settings
- [x] Customers & Jobs (4 pages) ✅
- [x] Managing Customers
- [x] Configuring Jobs
- [x] Approved Jobs
- [x] Job Schedules
- [x] Mail & Import (4 pages) ✅
- [x] Mail Import Setup
- [x] Inbox Management
- [x] Mail Parsing
- [x] Auto-Import Configuration
- [x] Backup Review (5 pages) ✅
- [x] Approving Backups
- [x] Daily Jobs View
- [x] Run Checks Modal
- [x] Overrides & Exceptions
- [x] Remarks & Tickets
- [x] Take screenshots for core features (10 screenshots added)
**Status:** COMPLETE (16/16 pages)
**Time Spent:** ~21 hours
### Phase 4: Content Pages - Advanced Features (0/14 pages)
- [ ] Reports (4 pages)
- [ ] Autotask Integration (4 pages)
- [ ] Settings (3 pages)
- [ ] Troubleshooting (3 pages)
- [ ] Take screenshots for advanced features
**Estimated Complexity:** High
**Time Estimate:** 7-10 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
Reference in New Issue View Git Blame Copy Permalink