Documentation Cleanup

Documentation Cleanup

Validate and fix documentation integrity across the docs/ folder.

Process overview

1. Identify files to validate
2. Check module ↔ doc parity
3. Check indexes
4. Validate tables and Mermaid diagrams
5. Validate ADR structure
6. Check links and formatting
7. Fix numbered lists

Documentation references

• README.md — top-level module index
• docs/ — per-module docs and reviews
• docs/adr/ — Architecture Decision Records

Step-by-step procedure

1. Identify files

Collect every *.md under docs/ and the workspace root.

2. Module ↔ Doc Parity

For each folder src/SolTechnology.Core.<Module>/:

• A documentation file exists under docs/ (the file name is set by README.md — e.g. Tale → docs/Tale.md, MessageBus → docs/Bus.md).
• The module is listed in the README table with a NuGet badge.
• A review template exists under docs/reviews/ when the module is publicly consumed; missing review templates are reported as gaps, not failures.

3. Check Indexes

For files that contain an index (README, docs/Story.md, etc.):

• Every index entry has a matching section in the document.
• Every top-level section is listed in the index.
• Index links use angle brackets for any path containing spaces: [Text](<path/file.md>).
• Index hierarchy matches the document hierarchy.

4. Validate Tables and Mermaid Diagrams

For each table:

• Header row present, separator row matches column count, every data row matches column count.

For each Mermaid block:

• Syntax parses (no stray characters).
• classDef declared before first use.
• Node names with spaces use <br> line breaks: Node[Name<br>With<br>Spaces].

5. Validate ADR Structure

For every file under docs/adr/:

• File name matches NNN-kebab-title.md, numbering monotonic with no gaps.
• Required sections present: Status, Context, Decision, Consequences.
• Recommended sections noted as gaps when missing: Alternatives Considered, Stakeholders.
• ADR is linked from at least one other doc or from CLAUDE.md / README.md.

6. Check Links and Formatting

• Paths with spaces use angle brackets: [Text](<path/file.md>).
• Relative paths resolve from the file's location.
• Linked files exist on disk.
• Module docs use relative links into src/SolTechnology.Core.* only when the file is stable (interfaces, ModuleInstaller.cs, public entrypoints).

7. Fix Numbered Lists

• Use 1. for every item (markdown auto-numbers).
• Nested lists indented by 4 spaces.
• Hierarchy consistent within a document.

Ignore backtick / inline-code formatting issues unless they break rendering.

Output format

Documentation Cleanup Report

Files Validated

List with brief status.

Issues Found

Module ↔ Doc Parity

Modules without a doc, docs without a module, README gaps.

Index Issues

Table / Mermaid Issues

ADR Issues

Link Issues

Numbered List Issues

Fixes Applied

Per-file summary.

Summary

Files validated: count Issues found: count Fixes applied: count

Source: AdrianStrugala/SolTechnology.Core — distributed by TomeVault.