documentation-expert

To restructure project documentation accurately, verify claims against the repository, remove duplication, and organize content around reader needs rather than internal convenience. This ensures docs stay skimmable, correct, and aligned with the actual code.

Add Mermaid diagrams to technical documentation selectively, only when they clarify architecture, workflows, or data relationships better than prose or tables. Avoid overusing diagrams where simple text sufficiently explains the concept.

The best way to organize a docs folder for developer onboarding is splitting content by clear boundaries: tutorials, how-to guides, references, and explanations. This reader-first structure helps developers quickly find what they need to do.

Fix README inaccuracies by checking source code and commands directly, then rewriting content to match verified repository state. Prevent documentation drift by removing duplicated information and maintaining strict boundaries between reference and explanation content.

Yes, you can update runbooks and architecture docs using a reader-first approach by tightening their scope, verifying commands against the repository, and reporting exactly what changed and why to maintain operational accuracy.

Documentation triage requires splitting different types of technical writing to prevent content overlap and drift. Separating tutorials, how-to guides, references, and explanations ensures each document serves a distinct reader need without bloating.