Skip to content

Documentation Plan

Jump to bottom
Bradley Brown edited this page Aug 13, 2026 · 1 revision

Documentation Plan

The documentation tree in Docs/ is treated as a first-class deliverable. This page is the central roadmap, conventions reference, and pending-work tracker for that effort.

For finished work, see the two indexes:

Goals

  1. Two audiences, one source tree. Anything a lay user might read lives under Docs/User/. Anything that assumes you know what a csproj is lives under Docs/Technical/. The split is enforced by directory location and audience voice, not by separate authoring tooling.
  2. Pour on the examples. Both user and technical docs are example-heavy. A formula without a worked example is a missed teaching opportunity. A UI feature without a screenshot is a description the reader still has to imagine.
  3. Cite everything. Mathematical facts, algorithms, and historical claims all link to Resources & Bibliography.
  4. One file, two surfaces. Each Markdown source renders inside the in-app Help viewer (HelpMarkdownRenderer in UI.Avalonia/ViewModels/HelpViewerViewModel.cs) and gets converted by Tools/DocSiteGen into a static HTML site under Docs/site/. No content lives in only one of those surfaces.
  5. History preserved. Older notes are kept in place as archival paragraphs. Errors get corrected with a [!NOTE] callout instead of being silently rewritten.

Layout

Docs/
├── Documentation-Plan.md      ← this file
├── Resources-Bibliography.md  ← shared citation file
├── _Index.md  (TBD — top-level landing for both audiences)
├── User/
│   ├── _Index.md              ← lay-person hub
│   ├── Avalonia-UserGuide.md
│   ├── CalcGen-UserGuide.md
│   ├── Capture-Guide.md
│   ├── ClientServer-UserGuide.md
│   ├── ColorGen-UserGuide.md
│   ├── ColorThemeEditor-Guide.md
│   ├── Keyboard-Shortcuts.md
│   ├── FracturingFog-Keyboard-shortcuts.txt
│   ├── Regions-Guide.md
│   ├── ServerAdmin-Guide.md
│   ├── Slideshow-AudioReactive-Guide.md
│   └── UserBulb-Guide.md
├── Technical/
│   ├── _Index.md              ← developer hub
│   ├── Architecture-Overview.md
│   ├── CalculatorGen-Architecture.md
│   ├── CalculatorGen-Authoring.md
│   ├── CalculatorGen-Roadmap.md
│   ├── CrossPlatform-Roadmap.md
│   ├── FractalEquation-DesignGuide.md
│   ├── Performance-DevelopmentPlan.md
│   ├── UserBulb3D-DevelopmentPlan.md
│   └── UserBulbSandbox-DevPlan.md
├── Images/                    ← see Docs/Images/README.md for capture protocol
│   ├── _placeholders/
│   ├── diagrams/
│   ├── dialogs/
│   ├── examples/
│   └── fractals/
└── site/                      ← generated by Tools/DocSiteGen (not committed by default)

Authoring conventions

Markdown subset

The in-app HelpMarkdownRenderer understands a focused subset of CommonMark plus a couple of GFM extensions. The static-site generator uses Markdig with the full AdvancedExtensions pipeline, so anything recognised by the renderer is recognised by the site — but only the renderer's subset ships into the live app.

Construct In-app Static site
Headings (#, ##, ###, ####) yes yes
Paragraphs yes yes
Bold / italic yes yes
inline code yes yes
```fenced code``` yes yes
Bullet lists (-, *) yes yes
Ordered lists (1.) yes yes
Pipe tables yes yes
Blockquote (>) yes yes
Callouts (> [!NOTE]) yes yes (rendered as styled blockquote)
Horizontal rule (---) yes yes
Images (![](path)) yes yes
Links ([label](url)) yes yes
Inline LaTeX ($x$) yes — source rendered styled yes — KaTeX typeset
Block LaTeX ($$x$$) yes — source rendered styled yes — KaTeX typeset
Footnotes ([^id]) partial — kept as text yes
Task lists (- [ ]) partial — kept as text yes

Note

Anything not in the in-app column degrades gracefully — it still appears as plain text inside the embedded viewer, just unstyled. The web export is always richer.

Voice

  • User docs: speak to a curious novice. Define every term the first time it appears. Replace jargon with plain words whenever the meaning survives. Do not dumb down; explain.
  • Technical docs: speak to a peer. Assume working knowledge of .NET, C#, Markdown, git. Lean into precision: cite, show full code blocks, prefer truth to brevity. Be verbose.

Callout types

> [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING]

Choose by intent, not severity:

  • NOTE — neutral aside the reader can skip without losing the thread.
  • TIP — friendly shortcut or "did you know" moment.
  • IMPORTANT — load-bearing detail; ignore at your peril.
  • WARNING — destructive or irrecoverable action ahead.

Warning

The renderer uses yellow for warnings — never red. The project owner is red/green colour-blind, and the yellow #FFCC00 accent is the canonical alert hue across every dialog and overlay in the app. Stay consistent.

LaTeX

Block formulas:

$$
z_{n+1} = z_n^2 + c
$$

Inline formulas: the bailout test $|z| > 2$ follows from ….

The static site runs KaTeX auto-render with $..$ and $$..$$ delimiters; the in-app viewer keeps the raw source in a code-styled span so users can copy-paste it.

Images

See Docs/Images/README.md for the capture protocol. Always reference relative paths so the static site and the in-app viewer resolve them identically:

![Mandelbrot — Seahorse Valley at zoom 1e4](../Images/fractals/mandelbrot-seahorse.png)

If the image does not exist yet, use the placeholder + add a row to Pending Image Captures below.

Building the static site

dotnet run --project Tools/DocSiteGen

This produces Docs/site/index.html and one HTML page per source .md. Open index.html directly in a browser; no web server required.

When the site is published to GitHub Pages the URL is https://<user>.github.io/FracturingFog/site/ (adjust to the actual deployment).

Tip

The static-site output is not committed by default — it is build artefact. If you want to ship pre-built pages, add Docs/site/ to source control after a clean run.

Pending work

Pending User-guide rewrites (Phase B)

Doc Status
User/Avalonia-UserGuide.md Existing — re-write in lay voice in progress.
User/Capture-Guide.md Existing — needs worked examples + visuals.
User/Regions-Guide.md Existing — needs worked examples + visuals.
User/ColorThemeEditor-Guide.md Existing — needs visual editor walk-through.
User/ColorGen-UserGuide.md Existing — needs DSL worked examples.
User/CalcGen-UserGuide.md Existing — needs equation worked examples.
User/Slideshow-AudioReactive-Guide.md Existing — needs music-source walkthrough.
User/UserBulb-Guide.md Existing — needs 3-D rendering visuals.
User/ClientServer-UserGuide.md Existing — needs setup screenshot sequence.
User/ServerAdmin-Guide.md Existing — minor wording polish only.
User/Keyboard-Shortcuts.md Existing — verify against current build.

Pending Technical-doc polish (Phase C)

Doc Status
Technical/Architecture-Overview.md Add LaTeX for QD threshold derivations.
Technical/CalculatorGen-Architecture.md Add ILGPU JIT path section.
Technical/CalculatorGen-Authoring.md Add full worked example: Tricorn.
Technical/CalculatorGen-Roadmap.md Verify dates, mark completed items.
Technical/FractalEquation-DesignGuide.md Add User Bulb 3D quat algebra section.
Technical/Performance-DevelopmentPlan.md Bring in line with GPU JIT staged feature work.
Technical/CrossPlatform-Roadmap.md Refresh after Skia smoke tests are green.

Per-dialog help (Phase D — landed 2026-06-11)

Every Phase 2 / Phase 3 dialog now exposes a yellow ? button. The button calls HelpViewerLauncher.Show(this, docId, anchor, title) (see UI.Avalonia/Views/HelpViewerLauncher.cs) which opens HelpViewerView modeless on top of the dialog, pre-sliced to the right anchor.

Already wired (Phase 2 / Phase 3 baseline):

  • UserEquationView → User/CalcGen-UserGuide.md
  • SandboxView → User/Avalonia-UserGuide.md#Sandbox
  • UserBulbView → User/UserBulb-Guide.md

Phase D landed:

  • AudioSettingsView → User/Slideshow-AudioReactive-Guide.md#audio-reactive-engine
  • SlideshowSettingsView → User/Slideshow-AudioReactive-Guide.md
  • VideoSettingsView → User/Capture-Guide.md#video-zoom
  • ColorThemeEditorView → User/ColorThemeEditor-Guide.md
  • ColorGenEditorView → User/ColorGen-UserGuide.md
  • FFClientView → User/ClientServer-UserGuide.md#first-time-server-setup
  • ServerAdminView → User/ServerAdmin-Guide.md
  • FractalParamsView → User/Avalonia-UserGuide.md#Params
  • WatermarkEditorView → User/Avalonia-UserGuide.md#Watermark

Pending Image Captures

Status column key: ✅ landed · 🟡 fractal render scripted (see batch recipe below) · ⬜ needs interactive capture.

Status Image path Used by Capture spec
✅ Images/fractals/mandelbrot.png User/Avalonia-UserGuide.md, _Index.md Home view, HSV palette, 1600×1000
✅ Images/fractals/julia-default.png User/Avalonia-UserGuide.md Reset, HSV palette, 1600×1000
✅ Images/fractals/burningship.png User/Avalonia-UserGuide.md Reset, HSV palette, 1600×1000
✅ Images/fractals/tricorn.png User/Avalonia-UserGuide.md Reset, HSV palette, 1600×1000
✅ Images/fractals/newton.png User/Avalonia-UserGuide.md Reset, HSV palette, 1600×1000
✅ Images/fractals/mandelbulb.png User/UserBulb-Guide.md Reset, "New 3D" Phong palette, 1600×1000
✅ Images/diagrams/render-pipeline.svg Technical/Architecture-Overview.md Toolchain dataflow
✅ Images/diagrams/precision-promotion.svg Technical/Architecture-Overview.md SP → DD → QD threshold chart
✅ Images/dialogs/slideshow-settings.png User/Slideshow-AudioReactive-Guide.md Default state, dark theme
✅ Images/dialogs/audio-settings.png User/Slideshow-AudioReactive-Guide.md Default state
✅ Images/dialogs/color-theme-editor.png User/ColorThemeEditor-Guide.md New theme, Gradient kind selected
✅ Images/dialogs/colorgen-editor.png User/ColorGen-UserGuide.md New empty editor
✅ Images/dialogs/server-admin.png User/ServerAdmin-Guide.md Started server, default limits
✅ Images/dialogs/ffclient-top.png User/ClientServer-UserGuide.md FFClient panel 1 — vault status + connection list + cert path / password.
✅ Images/dialogs/ffclient-middle.png User/ClientServer-UserGuide.md FFClient panel 2 — render preset through iteration field.
✅ Images/dialogs/ffclient-bottom.png User/ClientServer-UserGuide.md FFClient panel 3 — video options through Close button.
⬜ Images/dialogs/scene-editor.png User/SceneEngine-UserGuide.md Scene Editor with a 2-shot timeline + a camera keyframe row expanded. Reach via floating menu → Edit Scene…; load built-in "Bulb → Box".

Fractal batch-render recipe (reproducible)

The six fractal renders above were produced from the headless --batch path:

dotnet build FracturingFogCLD.csproj -c Release
dotnet run --project FracturingFogCLD.csproj -c Release --no-build -- `
  --batch --mode image --fractal Mandelbrot --x -0.5 --y 0 --zoom 1.0 `
  --theme HSV --width 1600 --height 1000 `
  --out Docs\Images\fractals\mandelbrot.png

Swap --fractal / --x / --y / --zoom per row of FractalViewState.SnapToFractalDefault (Abstractions/ViewState/FractalViewState.cs). For Mandelbulb pass --theme "New 3D" instead of HSV.

Dialog screenshot checklist (interactive)

The six remaining captures need the running Avalonia shell. Standard prep for every shot:

  1. dotnet run --project FracturingFogCLD.csproj -c Release — launches the Avalonia shell.
  2. OS theme dark, Windows scaling 100 %, no DPI virtualisation.
  3. Snipping tool → Window snip mode crops cleanly to the chrome.
  4. Save as PNG into Docs/Images/dialogs/<filename>.png.

Per-dialog launch route:

Filename How to reach it
slideshow-settings.png Floating menu → Slideshow → Slideshow Settings. Defaults loaded, no preset modified.
audio-settings.png Slideshow Settings → top-right Audio… button. Default device, beat counters at 0.
color-theme-editor.png Floating menu → Theme → Edit Theme… → click New → set Kind to Gradient. Empty stops list.
colorgen-editor.png Floating menu → Theme → ColorGen Editor…. Default seed DSL in the source pane.
server-admin.png Start the server with --server --admin, then capture the admin window after first heartbeat (~3 s).
ffclient-top.png Floating menu → Remote → Open FFClient…. Unlock vault, pick a saved connection so all top-half fields populate. Crop from window chrome down to the cert-password row.
ffclient-middle.png Same dialog instance. Crop from the render-preset row down through the iteration field. Slight overlap with the top crop is fine.
ffclient-bottom.png Same dialog instance. Crop from the video-options row down through the Close button.

Citation maintenance

Run periodically (every release):

  • npx markdown-link-check Docs/**/*.md — flags dead bibliography links.
  • Re-check every URL in Resources-Bibliography.md once a year.
  • Verify every historical date claim in Technical/UserBulb3D-DevelopmentPlan.md and Technical/CalculatorGen-Roadmap.md.

Maintenance log

Date Change
2026-06-11 Initial pass: split User/Technical, added Documentation-Plan + Resources-Bibliography, upgraded HelpMarkdownRenderer (selectable text + images + LaTeX), introduced Tools/DocSiteGen.
2026-06-11 Phase B: lay-voice "Friendly tour" prepends on all User guides.
2026-06-11 Phase C: LaTeX derivations + extended worked examples on Architecture-Overview, CalculatorGen-Architecture (+ ILGPU section), CalculatorGen-Authoring (Tricorn walkthrough), FractalEquation-DesignGuide (quaternion algebra). Status banners on roadmaps.
2026-06-11 Phase D: yellow ? button wired on all 9 modeless dialogs via HelpViewerLauncher helper.
2026-06-11 Phase F (partial): 6 fractal family PNGs + 2 architecture SVGs landed; 6 dialog screenshots queued with reproducible recipes. Placeholder refs replaced in _Index.md, UserBulb-Guide.md, Avalonia-UserGuide.md, Architecture-Overview.md.
2026-06-11 Phase F (dialogs): 7 dialog screenshots captured (slideshow-settings, audio-settings, color-theme-editor, colorgen-editor, server-admin + FFClient top/middle/bottom). Wired into Slideshow-AudioReactive-Guide.md, ColorThemeEditor-Guide.md, ColorGen-UserGuide.md, ServerAdmin-Guide.md, ClientServer-UserGuide.md.
2026-06-11 Phase F (worked examples): added --bulb-power + --multibrot-exp to batch CLI (Batch/BatchOptions.cs, Batch/BatchRenderer.cs). Rendered 5 examples: mandelbulb-p4 / mandelbulb-p12 (UserBulb-Guide triptych using existing mandelbulb.png as p=8), multibrot-cubic (CalcGen-UserGuide), seahorse-sunset (ColorThemeEditor-Guide), tricorn-handtuned + tricorn-calcgen pair (CalculatorGen-Authoring). Newton domain-colouring example dropped: Newton kernel ignores theme overrides — basin coloring is hard-wired RGB. Quaternion-slice example (FractalEquation-DesignGuide.md:112) deferred: needs UserBulb DSL preset, not batch CLI.
2026-06-11 DocSiteGen: fixed 404s on every intra-doc link. Markdig preserved .md in href targets — browsers hit URLs the site never wrote. Two-part fix in Tools/DocSiteGen/Program.cs: regex rewrite of all .md hrefs → .html (preserves #anchor), plus a bare-name fallback that emits ../Technical/Foo.html when a User/ page links bare Foo.md (and vice-versa). Mirrors the in-app HelpViewer's User/ ↔ Technical/ fallback so live and embedded views agree.
2026-06-11 PHASE2_AVALONIA_MIGRATION.md moved from repo root to Docs/Technical/ so DocSiteGen sees it and emits the page. Cross-ref in Architecture-Overview.md dropped the ../ prefix (same folder now). Code-comment refs in HelpTextBundle.cs / FractalViewState.cs / CrossPlatform-Roadmap.md left as bare filenames — they're prose, not links. Site emits 25 pages (was 24).
2026-07-04 Scene Engine docs (S0–S8 shipped). Added User/SceneEngine-UserGuide.md (lay voice: preview-vs-export split, orbit camera, easing, transitions, tone-map, global tracks, export + CLI, troubleshooting) and Technical/SceneEngine-Architecture.md (module map, camera-track/spline/easing math, timeline cut model, offline frame plan + motion blur, extension recipes). Added four importable example Scenes under Docs/Examples/Scenes/ (+ walkthrough _Index.md), region-free and JSON-validated. Added a Scene Engine citation block to Resources-Bibliography.md (Catmull-Rom, Reyes motion blur, dolly zoom, Reinhard/ACES). Wired all three doc indexes; queued one interactive capture (scene-editor.png).
2026-07-22 Feature sweep for #54 (batch --watermark inverted to default-on, alias --no-watermark) and the GPU-compute / Series-Approximation / DD-BLA toggles (#57, #88). Capture-Guide.md: new "Watermark (on by default)" subsection under Batch CLI + cross-ref from §9. Keyboard-Shortcuts.md: added "Overlays & Toggles" (G/K/H/Shift+H/X/P/F1) and "Performance & Deep-Zoom Diagnostics" (Ctrl+G GPU, Ctrl+Shift+A/S/D) sections. Avalonia-UserGuide.md §16: new "GPU compute" subsection (Control Center checkbox, Ctrl+G, auto-fallback, in-shader SA). FEATURES.md §12.2: batch watermark-default note.
2026-07-22 CalcGen / DesignGuide depth pass. Fixed the integer-power bound doc bug (0..16 → 0..64, matching EquationParser.cs:151) in CalcGen-UserGuide.md §2/§7 and the CalculatorGen --help string. Added a "Cookbook — end-to-end recipes" section to CalcGen-UserGuide.md (preview→promote, generate a compiled calculator, headless render of the pre-wired Generated* families with the new watermark default, --bailout for smooth transcendentals, keeping equations deep-zoomable) and clarified --bailout squares the radius. Added an "Author's pre-flight checklist — seeds, guards, and degeneracies" section to FractalEquation-DesignGuide.md consolidating the z₀=0 singularity pitfalls (1/z, log(0), linear i*z, (z²+c)/(z+a), conj/fold order) plus a holomorphic "keep DE on" helper table.
2026-07-22 UserBulb Quat + Sandbox wave parity (missed by the earlier sweeps). Source of truth: commit acf0c52 (quat transcendentals in DSL; Quat math + escape contract) plus the Wave 4.4/4.5/4.6 Sandbox-GPU work in UserBulbCalculator.cs. UserBulb-Guide.md: §4 Quat API rewritten from 4 members to the full surface — constants (One/Pi/HalfPi/QuatAxis), Pow/Sqrt/Exp/Log/Inverse/Scale, and the complete trig / hyperbolic / inverse-trig / reciprocal families, with Pow algorithm split, the never-throw escape contract, and worked snippets. §7 Backends corrected — three GPU routes (Sandbox-quat analytic+numerical+Julia, Sandbox-vec analytic, legacy Roslyn triplex-power), KIFS CPU-only note. §19 Sandbox DSL: intro table (now Vec3+Quat, CPU+GPU), .w member access (§19.2/§19.3 grammar), Hamilton * and Quat ^ operator rules (§19.4), the 26 q* functions — qvec/qmul/qpow/qconj (structural) plus the 22 quaternion-algebra transcendentals qexp/qlog/qsqrt/qinv + trig/hyperbolic/inverse/reciprocal families (§19.5), corrected limitations (§19.8 — dropped the false "No Quat"/"No GPU" bullets, flagged the stale Compiler-combo label), decision table (§19.9), and a new §19.10 quaternion cookbook (6 GPU-translatable DSL recipes). Gallery example #8 cross-linked to §4/§19.10. FractalEquation-DesignGuide.md §0.4: NOTE cross-referencing the transcendental library + escape contract + Sandbox-GPU path. Verified against Quat.cs, SandboxBulbExpression.cs, UserBulbSandboxGpuCompiler.cs, UserBulbCalculator.cs, UserBulbView.axaml, UserBulbViewModel.cs.

Clone this wiki locally