> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Documentation Framework
> Nextedy RISKSHEET documentation is organized around the **Diátaxis framework** — a systematic approach to technical writing that recognises a simple truth: people read documentation for different reasons.
export const LastReviewed = ({date}) => {
if (!date) return null;
const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
timeZone: "UTC"
});
return
Last reviewed on {formatted}
;
};
Understanding this framework helps you reach the right answer faster. It also explains why a page about exporting to PDF will not teach you what an FMEA is, and why the page that explains Risk Priority Number (RPN) does not walk you through configuring a severity column step-by-step. Those are deliberately separated concerns.
## 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**.
Each quadrant answers a different question:
| Quadrant | Question it answers | Risksheet section |
| ---------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Tutorial** | "I am new — show me a safe path." | [Getting Started](/risksheet/getting-started/index) |
| **How-To Guide** | "I have a real task — how do I do it?" | [Guides](/risksheet/guides/index), [Troubleshooting](/risksheet/troubleshooting/index) |
| **Concept** | "Why does it work this way?" | Concepts (you are here) |
| **Reference** | "What does this property do? What are the valid values?" | [Reference](/risksheet/reference/index), [FAQ](/risksheet/faq/index) |
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.
A single combined page would frustrate all three. By separating modes, each reader can land where they need to be and ignore the rest.
If a page makes you feel like you are reading the wrong thing, you probably are — the right page exists in a different quadrant. Use the sidebar groups (Getting Started / Concepts / Guides / Reference) to jump.
## 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](/risksheet/getting-started/index) 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?
These pages contain very few step-by-step instructions. When they do reference a procedure, they link out to the relevant how-to guide — for example, the [Configuration Hierarchy](/risksheet/concepts/configuration-hierarchy) page explains the inheritance model and links to the [Configuration Management guides](/risksheet/guides/configuration/index) for the procedural side.
### 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](/risksheet/guides/columns/index) — adding, editing, hiding, and styling columns
* [Risk Management](/risksheet/guides/risk-management/index) — calculating RPNs, applying classification matrices, building mitigation chains
* [Review Management](/risksheet/guides/reviews/index) — comment-based, work-item-based, and approval reviews
* [Export](/risksheet/guides/export/index) — PDF export, Excel export, customising export templates
* [Integration](/risksheet/guides/integration/index) — linking Risksheet to upstream requirements and downstream tasks
* [Administration](/risksheet/guides/administration/index) — installation, template setup, configuration properties
* [Advanced Configuration](/risksheet/guides/advanced/index) — query factories, custom Velocity panels, multi-project setups
[Troubleshooting](/risksheet/troubleshooting/index) lives under Guides too, because "fix this broken thing" is a goal-oriented task — not a concept and not a property lookup.
### 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](/risksheet/reference/configuration/index) — top-level sections of the sheet configuration
* [Column Types](/risksheet/reference/columns/index) — every column type and its properties
* [Fields](/risksheet/reference/fields/index) — Polarion field bindings
* [Formulas](/risksheet/reference/formulas/index) — formula functions, parameters, and the `info` object
* [Styling](/risksheet/reference/styling/index) — cell decorators, CSS styles, and conditional formatting
* [API](/risksheet/reference/api/index) — server-side and client-side APIs
* [Templates](/risksheet/reference/templates/index) — top panel and PDF export Velocity templates
* [Configuration Examples](/risksheet/reference/examples/index) — complete working snippets for common scenarios
* [Compatibility](/risksheet/reference/compatibility/index) — version requirements
The [FAQ](/risksheet/faq/index) is, structurally, also reference content — short, focused answers to single questions.
## 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:
| Reader need | Reader's question | Where to look |
| -------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------- |
| Build a first FMEA | "I have never used Risksheet — get me to a working risk score." | Getting Started tutorial |
| Adjust thresholds | "Our process uses 100/200 as RPN thresholds, not the template's 150/250 — how do I change them?" | How-to guide on conditional formatting |
| Understand the model | "Why is the formula in one file and the visualization rule in another?" | Concepts (this section) |
| Find a property | "What is the exact name of the property that styles a cell red?" | Reference for cell decorators |
## 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 a `levels` 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."
**Misconception 3: "Reference pages need an introduction."**
Reference pages should not warm up. A reader looking up `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:
1. **First contact with the product?** Open [Getting Started](/risksheet/getting-started/index). Do not browse — the tutorial assumes you go in order.
2. **Trying to do something specific?** Go to [Guides](/risksheet/guides/index) and find the matching feature area.
3. **Something is broken or unexpected?** Open [Troubleshooting](/risksheet/troubleshooting/index) — it is the how-to mode for the error case.
4. **Looking up a precise detail?** Jump to [Reference](/risksheet/reference/index) and use the in-page search.
5. **Have a one-line question?** Try the [FAQ](/risksheet/faq/index) 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.
This three-file architecture exists because regulated industries (medical devices under ISO 14971, automotive under ISO 26262, industrial under IEC 61508, cybersecurity under ISO/SAE 21434) need to validate each layer separately. The documentation mirrors that structure — concepts explain the separation, guides show how to work within each layer, and the reference catalogues every property in each layer.
In other words: the Risksheet documentation is shaped like Risksheet. Once you internalise the four-quadrant model, both the product and the documentation become easier to navigate.
If this is your first concept page, read [What is Risksheet?](/risksheet/concepts/what-is-risksheet) next, followed by [Architecture](/risksheet/concepts/architecture) and [Configuration Hierarchy](/risksheet/concepts/configuration-hierarchy). Together they give you the full mental model in under thirty minutes of reading.