docs: reorganize documentation into generated and handwritten#165
Merged
Conversation
Split doc/ by content origin so the FirstClassErrors.Documentation project surfaces the whole documentation set instead of only the user-facing part: doc/generated/ CI/CD living documentation (GenDoc target) doc/handwritten/for-users/ former doc/* (guides, analyzers, images) doc/handwritten/for-maintainers/ former maintainers/* (ADRs, workflows) The Documentation project's glob is rooted in doc/, so the sibling maintainers/ tree was invisible in the Solution Explorer; moving it under doc/handwritten lets the single project cover everything. The project and the root README.md stay in place; the README is linked under handwritten/for-users next to its French translation. Every reference to the old paths is updated: root docs (README, CONTRIBUTING, SECURITY, CLAUDE, AGENTS), the PR template and prompts, CI workflow notes, the analyzer IDE help-link base URL (HelpLinks.cs), the shipped RequestBinder NuGet readme, the adr-check context script (a functional path), and every relative link inside the moved Markdown. Structural move only; no content rewritten. Refs: #164 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YCDL8WVukKYb2mVUnsyPKZ
Twenty English user-guide pages under doc/handwritten/for-users linked their footer "Table of contents" entry to README.md#-next-steps, an anchor that never existed: the root README's section is "## Documentation" (slug "-documentation"). Point them at that anchor, matching the five sibling English pages and every French page that already use it. This pre-existing broken anchor was surfaced while reorganizing the documentation tree; the change is limited to the dead fragment. Refs: #164 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YCDL8WVukKYb2mVUnsyPKZ
This was referenced Jul 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reorganize
doc/by content origin so theFirstClassErrors.Documentationproject surfaces the whole documentation set (users and maintainers), instead of only the user-facing part. The project's glob is rooted indoc/, so the siblingmaintainers/tree was invisible in the Solution Explorer; moving it underdoc/handwrittenfixes that with no project change.New layout:
The root
README.mdstays at the repository root (convention) and is linked into the project underhandwritten/for-users, next to its French translation.Type of change
Changes
doc/*→doc/handwritten/for-users/andmaintainers/*→doc/handwritten/for-maintainers/(viagit mv, history preserved).doc/generated/with a README and agendoc/output target for the CI/CD living documentation.README.md,CONTRIBUTING.md,SECURITY.md,CLAUDE.md,AGENTS.md), the PR template and.githubprompts, and CI workflow comments;FirstClassErrors.Analyzers/HelpLinks.cs;FirstClassErrors.RequestBinder/README.nuget.md;tools/adr-check/collect-context.sh— a functional path read by the ADR-check CI;.csprojcomment and place the linked README underhandwritten/for-users.README.md#-next-steps(no such heading); they now point to#-documentation, matching the pages that already did.Structural move only — no documentation content was rewritten.
Testing
dotnet build FirstClassErrors.sln— clean (0 warnings, 0 errors)dotnet test FirstClassErrors.sln— 823 passed, 0 failedFirstClassErrors.Analyzers.UnitTests— 85 passed)Additional verification: a relative-link check reports no new broken links versus the pre-move baseline (checked with a nested-badge-aware pass after one blind spot was found and fixed), and an independent multi-angle audit (residual paths, functional CI/script dependencies, anchors, EN/FR parity, solution/project wiring) surfaced no remaining breakage. Commits after the test run touch Markdown only (doc moves, ADR prose, the footer anchor) and have no build or runtime surface.
Documentation
doc/updatedThe English and French trees moved identically; French language-switch and README links were re-based in sync.
Architecture decisions
Checked against the ADR base: this is an organizational/layout convention, not one of the ADR-triggering categories (public API contract, cross-cutting invariant, platform floor, dependency/security policy), so no ADR was drafted. @Reefact — happy to record the doc-layout convention as an ADR if you'd prefer it captured.
Related issues
Closes #164
🤖 Generated with Claude Code
https://claude.ai/code/session_01YCDL8WVukKYb2mVUnsyPKZ
Generated by Claude Code