This is an experimental port from a C# server/database application - to a GitHub repo/VS Code extension. A concept driven by transformational conversations with a robotics firm - HAL Robotics.
This site is built with Docs Assembler and hosted on GitHub Pages. You can view the source code and documentation structure in the Docs Assembler Demo repo.
Escape Documentation Hell
Docs Assembler:
- A tool for authoring documentation in structured text files.
- Builds guides that adapt their content based on user choices.
- Ensures consistency by reusing text components instead of copying them.
It is designed for scenarios where traditional manuals fail: documenting intricate systems, or complex troubleshooting.
This website is built with it. The ‘Vertical Kitchen Garden Planner’ embedded below is a single guide that illustrates the depth of complexity possible.
The Problem with Traditional Manuals
Most organisations rely on traditional manuals, PDFs, and wikis, yet these static resources cannot capture the branching logic of expert troubleshooting or the situational nuances users face. This gap forces companies to rely on expensive, person-to-person training, creating a fragile system that hinges on a few key people. The result is an organisation perpetually one retirement away from a crisis: a true documentation hell where essential knowledge is unrecorded, scattered, and ultimately unusable when it matters most.
The Cycle of Dread and Delay
It’s not just about writing documentation - it’s about maintaining it, a task that becomes a source of dread that teams actively avoid until an update is urgently needed. Why?
- Sprawling, duplicated content - across guides, manuals, and wikis, making it impossible to know what’s accurate or current.
- Error-prone updates - you make a critical edit in one place, only to miss that same information duplicated in other files, instantly introducing inconsistencies.
- Brittle, unmanageable docs - resulting from the struggle to document similar-but-diverging scenarios without creating redundancy and contradictions.
Scaling Clarity, Not Complexity
The true power of this approach is that it scales.
Consider managing emergencies at an oil refinery. The variables are endless: fires, explosions, earthquakes, power loss, IT failures, medical crises. The number of internal teams - incident commanders, operators, maintenance, security, medical, PR, IT, legal, HR - is large, and each needs tailored, timely steps. External stakeholders like emergency services and media introduce more jurisdiction-specific requirements. Add in site variability like equipment locations and local laws, and the complexity is staggering.
Now imagine capturing all of that in a single, decentralised, maintainable system. Each team builds and maintains their own domain-specific body of knowledge, yet for the end-user, the experience is seamless and unified. The result is a single source of truth - validated, up-to-date, and turning collective knowledge into decisive action when it’s needed most.