The Four Modes of Documentation
Diátaxis identifies four distinct documentation needs, each best served by a different style of writing. Think of them as four corners of a square, defined by two axes: whether the reader is studying or working, and whether the content focuses on the product or on the reader’s goal.
The framework is older than Risksheet itself — it was distilled by Daniele Procida from years of observing real readers. The Risksheet documentation site adopts it because risk analysis spans both regulated-industry theory and very practical, fiddly day-to-day configuration. A page that mixes the two leaves both audiences frustrated.
Why Mixing Modes Hurts Documentation
The most common documentation failure is the page that tries to do everything at once: a few paragraphs of background theory, then a step-by-step procedure, then a half-finished reference table, and finally an unrelated troubleshooting tip. Readers experience this as noise. Consider three different people opening the documentation on a Wednesday afternoon:- A safety engineer new to Polarion wants to produce her first HARA. She needs a tutorial that holds her hand and lets her succeed. She does not yet need to know about cell decorators.
- A quality manager has been running FMEAs for years. He needs to look up the exact name of the property that controls cell merging on the failure-mode column. He needs a reference page, fast.
- A risk methodology lead is evaluating whether Risksheet can support a new ISO/SAE 21434 TARA process. She needs to understand how the configuration model is built, so she can map her methodology onto it. She needs a concept page.
How the Risksheet Site Is Organised
The site mirrors the four quadrants in its top-level navigation. The names are deliberately consistent and never substituted — “Concepts” is never called “Overview” or “Core Concepts”, and “Guides” is never called “Tutorials” or “How-To”.Getting Started — Tutorials
The tutorial section is short, narrow, and prescriptive. Its job is not to explain everything but to build confidence by producing a working result quickly. A tutorial may use a feature without explaining its full configuration surface — that is a feature, not a bug. For example, the recommended path is always to start from a Nextedy solution template rather than from a blank configuration. Templates are pre-built sheet configurations for typical risk methodologies (FMEA, HARA, TARA). Starting from a template means the new user lands on a working risksheet within minutes, then adapts it. Starting from scratch means hours of YAML editing before anything works. See Getting Started for the safe, guided introduction.Concepts — Understanding
The Concepts section answers why Risksheet is shaped the way it is. It builds the mental model you will reuse every time you configure, troubleshoot, or extend the tool. Examples of concept-level questions:- Why does Risksheet have three separate configuration files instead of one?
- What does it really mean to say Risksheet has “two data entities and N visual levels”?
- How does a saved view differ from a column’s visibility setting?
How-To Guides — Recipes
A how-to guide assumes you already understand the basic vocabulary and now have a real problem to solve. The guide tells you the shortest reliable path from problem to result. Risksheet how-to guides are grouped by feature area:- Column Configuration — adding, editing, hiding, and styling columns
- Risk Management — calculating RPNs, applying classification matrices, building mitigation chains
- Review Management — comment-based, work-item-based, and approval reviews
- Export — PDF export, Excel export, customising export templates
- Integration — linking Risksheet to upstream requirements and downstream tasks
- Administration — installation, template setup, configuration properties
- Advanced Configuration — query factories, custom Velocity panels, multi-project setups
Reference — Lookup
Reference pages are dry, complete, and structured like a dictionary. They list every property of a column type, every valid value of an enumeration, every Velocity variable available in a template. A good reference page is boring — and it should be, because nobody reads it cover-to-cover. The reference section is split by configuration domain:- Configuration — top-level sections of the sheet configuration
- Column Types — every column type and its properties
- Fields — Polarion field bindings
- Formulas — formula functions, parameters, and the
infoobject - Styling — cell decorators, CSS styles, and conditional formatting
- API — server-side and client-side APIs
- Templates — top panel and PDF export Velocity templates
- Configuration Examples — complete working snippets for common scenarios
- Compatibility — version requirements
A Worked Example: One Topic, Four Pages
To see how the framework plays out in practice, consider the topic “calculating RPN with severity, occurrence, and detection ratings”. The same topic appears in all four quadrants — but each page does a different job:
Common Misconceptions
The Diátaxis split is not about how long a page is, or how technical it is, or how much code it contains. It is about the reader’s task. Three misconceptions trip people up: Misconception 1: “Concepts pages must be theoretical.” Concept pages explain why and how the system is shaped — not necessarily abstract theory. A concept page can include code-level examples (such as the YAML snippet of alevels array), as long as the goal is to illuminate the underlying model rather than to walk the reader through a task.
Misconception 2: “If a page contains numbered steps, it is a tutorial.”
Tutorials and how-to guides both contain steps. The difference is purpose:
- A tutorial says: “Follow these exact steps and you will succeed. We chose this path because it is safe and predictable, not because it is the most efficient.”
- A how-to says: “You have a real problem. Here is the minimum-friction path to solve it. We assume you already know the basics.”
cellDecorators does not want to read three paragraphs about risk theory first — they want the property table. Reference pages start with a short description and dive straight into the structured content.
A useful rule of thumb when you write or edit Risksheet documentation: concept pages should link generously to how-to guides and reference pages. Reference pages should be self-contained — they are the destination, not the starting point.
What This Means for You as a Reader
When you arrive at the Risksheet documentation site, the sidebar gives you four entry points. Picking the right one saves time:- First contact with the product? Open Getting Started. Do not browse — the tutorial assumes you go in order.
- Trying to do something specific? Go to Guides and find the matching feature area.
- Something is broken or unexpected? Open Troubleshooting — it is the how-to mode for the error case.
- Looking up a precise detail? Jump to Reference and use the in-page search.
- Have a one-line question? Try the FAQ first.
What This Means for the Product
The Diátaxis split is not just an editorial choice — it reflects something true about Risksheet itself. The product is built on a separation of concerns:- A declarative sheet configuration (the YAML/JSON file with
columns,levels,dataTypes,formulas,styles,cellDecorators) describes what the grid looks like. - A scripting layer (the top panel Velocity template) describes how complex risk-matrix logic is calculated.
- A presentation layer (the PDF export Velocity template) describes how the result is printed.