Rebuilding the CISO Assistant Documentation

CISO Assistant has grown a lot over the past two years — new modules (TPRM, EBIOS RM, CRQ, DORA), a deeper data model, a CLI, an ever-expanding framework library. Our documentation has, frankly, not kept up at the same pace. We’ve decided to rebuild it from the ground up, and a preview is already live at intuitem.gitbook.io/ciso-assistant/product-docs.

This post is about the why behind the restructure, and how you can contribute.

What was wrong with the old docs

The previous documentation had accumulated in layers. New features were appended where there was room, reference material sat next to step-by-step guides, and conceptual explanations were scattered across pages that had grown organically. Users — and frankly, our own team — were spending too much time hunting for the right page, and too often landing on something that was either outdated or assumed context they didn’t have.

The core issues:

• No clear separation between what something is and how to use it.
• Mental models were implicit — you had to read several pages to piece together how perimeters, domains, audits, and applied controls relate to each other.
• Drift from the code — features evolved faster than the docs, with no enforcement loop.
• Hard to contribute to — the structure didn’t make it obvious where a new page should go.

What’s changing

The new documentation is organized around a few principles:

1. Mental models, first

Before diving into screens and buttons, we want users to understand the way CISO Assistant thinks about GRC: how the data model is structured, why we separate frameworks from audits, how risk assessments relate to applied controls, what a perimeter actually represents. These are short, focused pages that build the vocabulary you need before you touch the product.

2. Concepts and guides, separated

Reference material (what a field means, what a model contains, what an enum value implies) lives apart from task-oriented guides (how to run your first audit, how to import a framework, how to wire up SSO). Each has a different shape and a different audience — mixing them was the original sin of the old docs.

3. Versioned with the code

The documentation now lives inside the ciso-assistant-community repository, next to the code it describes. A feature change and its doc update can — and should — travel in the same pull request. This closes the drift loop and makes the docs a first-class part of the release process rather than an afterthought.

4. Open to contributions

Because the docs live in the same repo, contributing is exactly the same workflow as contributing code: fork, edit, open a PR. If you’ve ever hit a confusing page, found a missing example, or worked out a non-obvious configuration — please send it back. Documentation PRs are some of the highest-leverage contributions an open-source project can receive, and we’ll review them with the same care as code.

5. Smart search out of the box

We’re hosting on GitBook, which ships with semantic, AI-aware search across the whole documentation set. Instead of keyword-matching against page titles, you can ask questions in natural language and get answers grounded in the actual content. For a product as broad as CISO Assistant, this matters — most users don’t know the exact term we use internally for the thing they’re looking for.

Honest caveats

This is a work in progress, and we’d rather ship it now than wait for perfection:

• Some pages have been migrated as-is from the old documentation. They’ll be rewritten progressively to match the new structure and tone — please bear with us if you land on one that still feels stitched together.
• Coverage is uneven. The areas of the product we’ve touched most recently have the best docs; older or more stable modules are still catching up.
• The structure itself may shift a little as we learn what works. If something is hard to find, that’s useful signal — open an issue.

What you can do

• Browse the preview: intuitem.gitbook.io/ciso-assistant/product-docs
• Tell us what’s missing or confusing: open an issue on ciso-assistant-community
• Contribute a fix or a new page: PRs are welcome, and small ones are the easiest to merge

Better documentation is a long game, not a one-shot project. This restructure gives us — and the community — a foundation we can keep building on.