Context
Paige audited docs/ and found a thin nav (4 published pages out of ~12 docs files), several orphaned architecture and example sub-pages, and a handful of content bugs. John, Sally, and Winston weighed in on scope and information architecture.
Immediate Bug Fixes
docs/index.md — duplicate word: "With With LLVM-based" (line 6)
docs/compiler.md — stale LLVM version reference (7.0.0); currently supported versions are Clang/LLVM 14, 15, 17 (per h5cpp-compiler CI matrix)
docs/compiler.md — broken Doxygen-style @ref link_h5cpp_install link; replace with valid MkDocs-relative link
Nav Wiring (publish what already exists)
Wire the following orphaned files into mkdocs.yml:
architecture-types.md → under Architecture
architecture-integration.md → under Architecture
architecture-parallelism.md → under Architecture
compiler.md → top-level nav entry
examples/attributes.md, examples/datasets.md, examples/groups.md, examples/container.md, examples/sparse-matrix.md → under Examples
architecture.md (top-level monolith) intentionally excluded until the type-engine refactor (branches 89, 92, 114) settles — per Winston.
Content Work
docs/stl.md — rewrite from scratch; currently rough notes with typos and placeholder text ("code: 6487")
docs/compiler.md — refresh prose to match current LLVM support and link to vargalabs/h5cpp-compiler
Information Architecture (Sally + John)
Target nav structure reflecting three user personas (evaluator, integrator, deep diver):
Overview | Design | Architecture | Type System | I/O Operations | Compiler Tool | Examples
Sally's recommendation: surface the examples/ sub-pages as real nav children, not a single flat page.
Out of Scope
- New content for
architecture.md (blocked on type-engine refactor)
- Any changes to the MkDocs theme, CSS, or JS
Refs: #128 (README badge PR, same branch candidate)
Context
Paige audited
docs/and found a thin nav (4 published pages out of ~12 docs files), several orphaned architecture and example sub-pages, and a handful of content bugs. John, Sally, and Winston weighed in on scope and information architecture.Immediate Bug Fixes
docs/index.md— duplicate word:"With With LLVM-based"(line 6)docs/compiler.md— stale LLVM version reference (7.0.0); currently supported versions are Clang/LLVM 14, 15, 17 (per h5cpp-compiler CI matrix)docs/compiler.md— broken Doxygen-style@ref link_h5cpp_installlink; replace with valid MkDocs-relative linkNav Wiring (publish what already exists)
Wire the following orphaned files into
mkdocs.yml:architecture-types.md→ under Architecturearchitecture-integration.md→ under Architecturearchitecture-parallelism.md→ under Architecturecompiler.md→ top-level nav entryexamples/attributes.md,examples/datasets.md,examples/groups.md,examples/container.md,examples/sparse-matrix.md→ under ExamplesContent Work
docs/stl.md— rewrite from scratch; currently rough notes with typos and placeholder text ("code: 6487")docs/compiler.md— refresh prose to match current LLVM support and link tovargalabs/h5cpp-compilerInformation Architecture (Sally + John)
Target nav structure reflecting three user personas (evaluator, integrator, deep diver):
Sally's recommendation: surface the
examples/sub-pages as real nav children, not a single flat page.Out of Scope
architecture.md(blocked on type-engine refactor)Refs: #128 (README badge PR, same branch candidate)