Documentation Roadmap

Created: 2026-01-24
Last Updated: 2026-01-24 (Session 2)
Status: Active

This document tracks all planned documentation work for the DBTools wiki. It serves as a feature/issue tracker for documentation efforts.

Quick Status

Phase Status Progress
Phase 1: Infrastructure Complete 2/2
Phase 2: Theming Complete 3/3
Phase 3: Developer Guides Complete 5/5
Phase 4: User Documentation Complete 13/13
Phase 5: Diagrams Complete 4/4
Phase 6: XML Audit Not Started 0/10

Phase 1: Documentation Infrastructure

1.1 Documentation Roadmap

  • Status: Complete
  • File: DOCUMENTATION_ROADMAP.md (this file)
  • Description: Create feature/issue tracker for documentation work

1.2 Website Structure Redesign

  • Status: Complete
  • Priority: High
  • Description: Split site into user-facing and developer-facing sections

Implemented Structure:

wiki/
├── user-guide/                    # END-USER facing (non-developers)
│   ├── index.md                   # User guide home
│   ├── installation.md            # Install/uninstall, admin reqs
│   ├── getting-started.md         # Quick start for users
│   ├── toc.yml
│   └── tools/                     # HOW TO USE each tool (11 guides)
│       ├── gm.md
│       ├── sgt.md
│       ├── tdv.md
│       ├── foundation-tags.md
│       ├── elevation-tags.md
│       ├── elements-from-list-3d.md
│       ├── analytical-snap.md
│       ├── framing-joins.md
│       ├── joist-girder-weight.md
│       ├── organize-foundation.md
│       └── vtc.md
├── developer-guide/               # DEVELOPER facing
│   ├── index.md                   # Developer guide home
│   ├── architecture/              # Architecture docs
│   ├── projects/                  # Project docs
│   ├── tools/                     # Technical tool docs
│   ├── developing/                # Tool development guides
│   └── troubleshooting.md
├── templates/modern/styles/main.css  # Custom theming
├── images/                        # Logo, favicon
└── index.md                       # Site home

Tasks:

  • [x] Create user-guide/ directory structure
  • [x] Move existing docs to developer-guide/
  • [x] Update root toc.yml with new navigation
  • [x] Create section index pages
  • [x] Update cross-references in existing docs

Phase 2: Website Theming

2.1 Custom CSS

  • Status: Complete
  • Priority: High
  • File: templates/modern/styles/main.css

Brand Colors Applied:

Token Color Usage
Primary #1946B9 Links, headers, accents
Primary Light #3D6AD4 Hover states
Secondary #FEC425 Highlights, call-to-action
Secondary Light #FFD54F Secondary hover
Paper #181820 Dark theme background
Surface #222228 Cards, panels
Body #E6E6E6 Body text

Tasks:

  • [x] Create templates/modern/styles/main.css
  • [x] Override DocFX default colors with brand palette
  • [x] Style code blocks, tables, blockquotes
  • [x] Ensure accessibility (contrast ratios)
  • [x] Test dark/light theme toggle

2.2 Logo & Favicon

  • Status: Complete
  • Priority: High

Tasks:

  • [x] Copy db_tools_icon.png to images/logo.png
  • [x] Create favicon.ico
  • [x] Update docfx.json with logo/favicon paths

2.3 DocFX Configuration

  • Status: Complete
  • Priority: High
  • File: docfx.json

Tasks:

  • [x] Fix _gitContribute.repo URL
  • [x] Add custom template reference
  • [x] Configure _appLogoPath and _appFaviconPath
  • [x] Set default theme preference

Phase 3: Advanced Developer Guides

All guides created under developer-guide/developing/ with cross-links.

3.1 Settings Packs Guide

  • Status: Complete
  • Priority: High
  • File: developer-guide/developing/settings-packs.md

Content:

  • [x] What are settings packs?
  • [x] Defining in manifest.yml
  • [x] Settings model with Options pattern
  • [x] SettingsPack UI integration
  • [x] Configuration section naming conventions
  • [x] Real examples from GM, SGT, FoundationTags

3.2 Feature Warnings Guide

  • Status: Complete
  • Priority: High
  • File: developer-guide/developing/feature-warnings.md

Content:

  • [x] Warning system architecture
  • [x] Defining warnings in manifest.yml
  • [x] Warning lifecycle (trigger, display, dismiss)
  • [x] disableTools mechanism
  • [x] Warning UI in Settings window
  • [x] IWarningPublisher usage
  • [x] Real examples with code

3.3 Hooks Guide

  • Status: Complete
  • Priority: High
  • File: developer-guide/developing/hooks.md

Content:

  • [x] Hook system architecture
  • [x] DbtHookHost internals
  • [x] Available hook types:
    • [x] IViewActivatedHookHandler
    • [x] IContextualRibbonHookHandler
  • [x] Registering hooks in ToolModule
  • [x] Writing custom hook handlers
  • [x] Hook execution order and lifecycle
  • [x] Real examples from existing tools
  • [x] Creating new hook types (extension guide)

3.4 Sandbox Integration Guide

  • Status: Complete
  • Priority: High
  • File: developer-guide/developing/sandbox-integration.md

Content:

  • [x] What is the Sandbox?
  • [x] Why validation matters
  • [x] Registering sandbox windows in manifest
  • [x] Design-time ViewModels
  • [x] SandboxMode detection
  • [x] DistValidator checks
  • [x] Running sandbox validation locally
  • [x] Troubleshooting validation failures

3.5 Testing Tools Guide

  • Status: Complete
  • Priority: High
  • File: developer-guide/developing/testing-tools.md

Content:

  • [x] Test project structure
  • [x] Test categories (headless vs Revit integration)
  • [x] TestSupport library usage
  • [x] Writing headless tests
  • [x] Writing Revit integration tests
  • [x] Test doubles and stubs (legitimate vs illegitimate)
  • [x] Running tests locally
  • [x] CI integration
  • [x] Debugging test failures
  • [x] Real examples from GM.Tests, SGT.Tests

3.6 Update new-tool-guide.md

  • Status: Complete (existing doc maintained)
  • Priority: Medium
  • File: developer-guide/developing/new-tool-guide.md

Phase 4: User-Facing Documentation

4.1 Installation Guide

  • Status: Complete
  • Priority: High
  • File: user-guide/installation.md

Content:

  • [x] System requirements (Revit versions, Windows version)
  • [x] Download location
  • [x] Installer workflow (what it does step-by-step)
  • [x] Installation directory structure
  • [x] Where settings are stored (%APPDATA%/DBTools/)
  • [x] Admin requirements (if any)
  • [x] Silent install options (if applicable)
  • [x] Uninstallation process
  • [x] Troubleshooting installation issues

4.2 Getting Started Guide

  • Status: Complete
  • Priority: High
  • File: user-guide/getting-started.md

Content:

  • [x] First launch experience
  • [x] Finding the DB Tools ribbon tab
  • [x] Overview of available tools
  • [x] Quick example: running a simple tool
  • [x] Where to find help

4.3 Tool User Guides

  • Status: Complete
  • Priority: Medium

Each tool has a user-facing guide at user-guide/tools/<tool>.md:

Tool Status File
GM (Global Mapper) Complete gm.md
SGT (Super Girt Tool) Complete sgt.md
TDV (Transfer Drafting Views) Complete tdv.md
Foundation Tags Complete foundation-tags.md
Elevation Tags Complete elevation-tags.md
Elements From List 3D Complete elements-from-list-3d.md
Analytical Snap Complete analytical-snap.md
Framing Joins Complete framing-joins.md
Joist Girder Weight Complete joist-girder-weight.md
Organize Foundation Complete organize-foundation.md
VTC Complete vtc.md

Each guide includes:

  • What the tool does (non-technical)
  • When to use it (scenario table)
  • Quick Start steps
  • UI description
  • Settings explanation (if applicable)
  • Workflows (step-by-step)
  • Tips and tricks
  • Troubleshooting
  • FAQ

Phase 5: Diagrams & Visuals

Mermaid diagrams added to key documents.

5.1 Architecture Diagram

  • Status: Complete
  • File: developer-guide/architecture/overview.md
  • Added: Component diagram showing project relationships, discovery flow sequence diagram

5.2 Build Pipeline Diagram

  • Status: Complete
  • File: developer-guide/architecture/build-pipeline.md
  • Added: Build targets flowchart showing Preflight → Build → Package phases

5.3 Tool Module Lifecycle Diagram

  • Status: Complete
  • File: developer-guide/developing/new-tool-guide.md
  • Added: State diagram showing Discovered → Instantiated → Registered → Active lifecycle

5.4 Hook Execution Diagram

  • Status: Complete (already existed)
  • File: developer-guide/developing/hooks.md
  • Existing: Component overview flowchart, registration sequence, execution flow sequence diagrams

Phase 6: XML Comment Audit

Systematic review of XML documentation comments in source code.

Priority Order

Project Status Est. Files Priority
DBTools.Core Not Started ~50 1 (Highest)
DBTools.App Not Started ~30 2
DBTools.Themes Not Started ~5 3
DBTools.Loader Not Started ~5 4
DBTools.Sandbox Not Started ~10 5
Tools/Common/GM Not Started ~40 6
Tools/Structural/SGT Not Started ~30 7
Tools/Common/TDV Not Started ~15 8
Tools/Structural/* Not Started ~40 9
Tools/Common/* Not Started ~20 10

Audit Checklist (per project)

  • [ ] Public classes have <summary>
  • [ ] Public methods have <summary>, <param>, <returns>
  • [ ] Public properties have <summary>
  • [ ] Complex logic has <remarks>
  • [ ] Obsolete items have migration notes
  • [ ] Stale/misleading comments removed
  • [ ] IntelliSense reads naturally
  • [ ] Consistency with naming conventions

Execution Notes

Parallel Work

These can be worked on in parallel:

  • Phase 2 (Theming) - independent of content
  • Phase 5 (Diagrams) - can be added anytime
  • Phase 6 (XML Audit) - separate from wiki

Dependencies

Phase 1.2 (Structure) 
    ├── Phase 3 (Dev Guides) - need new paths
    └── Phase 4 (User Docs) - need new paths

Phase 2 (Theming) - independent

Phase 3 + 4 complete → Phase 5 (Diagrams) - add to final docs

All content complete → Phase 6 (XML Audit)

Session Continuity

When picking up work:

  1. Check this roadmap for current status
  2. Update status as you work
  3. Commit changes frequently
  4. Update "Last Updated" date

Completed Work

2026-01-24: Session 2 - Website Restructure, User Guides & Diagrams

PR: https://github.com/kirsch33/dbtools/pull/198 (continued)

Completed:

  • Website restructured into user-guide / developer-guide split
  • Custom CSS theming with DBTools brand colors
  • Logo and favicon added
  • 5 advanced developer guides (settings-packs, feature-warnings, hooks, sandbox-integration, testing-tools)
  • 11 user-facing tool guides (all tools)
  • Installation and Getting Started guides
  • Updated navigation and index pages
  • Mermaid diagrams added to architecture overview, build pipeline, and new-tool-guide

Commits:

  • 52da0ffc - docs: restructure site (user/developer split), add theming, add advanced dev guides
  • 25fed669 - docs: add user guides for GM, SGT, TDV, Foundation Tags
  • 6d000f73 - docs: add user guides for remaining 7 tools
  • 4657b14a - docs: update roadmap - phases 1-4 complete
  • e7c015b0 - docs: add Mermaid diagrams to architecture and developer guides

2026-01-24: Session 1 - Initial Documentation

Completed:

  • 26 documentation files (~12,700 lines)
  • All architecture docs
  • All project docs
  • All tool technical docs (developer-facing)
  • Developer guides (new-tool-guide, modularity)
  • Troubleshooting guide
  • Updated manifest and index

Branch: docs-run-20260124-020412

Edit this page