Documentation Style Guide - YouNegotiate Docs

These docs are not only feature descriptions. They are product behavior contracts for product owners, QA, support, implementation teams, and stakeholders.

The goal is to explain the real user scenario, the expected flow, and what must never happen when the feature changes.

Page Structure

Every portal feature page should use this order:

Section	Use
`Real-World Example`	A practical story using a creditor, consumer, or admin situation.
`Visual Flow`	Mermaid flow showing the expected path and key decisions.
`How It Should Work`	Plain-language rules for correct behavior.
`How It Should Not Work`	Guardrails, unsafe states, and regressions to avoid.

Real-World Examples

Good examples should feel like this:

ABC Collections imports 1,000 consumer accounts. Jane accepts an offer and makes a payment. The dashboard count changes, payment metrics update, and Jane eventually moves from open activity to completed activity.

Avoid examples like this:

The dashboard updates when data changes.

The second example is true, but it does not help a person understand the product.

Visual Flow Colors

Use the same color meaning everywhere. Keep the legend compact so it supports the page instead of taking over the page.

Label	Meaning	Use it for
Actor	A user, consumer, creditor, or admin starts an action.	The first human or portal actor in the flow.
System	Normal application processing.	Saved records, background work, routing, and updates.
Decision	A rule check or branch.	Eligibility, setup completeness, payment success, opt-out checks.
Risk	Blocked, failed, unsafe, or missing behavior.	Anything the product must prevent or surface clearly.
Outcome	A successful result or updated state.	What should be true after the flow completes.

Documentation Workflow

When product behavior changes, update the matching documentation page in the same work cycle.

Naming Rules

Mirror the app sidebar as folders and files.
Use lowercase kebab-case file names.
Use the readable product label as the page title.
Prefer one page per menu item.
Keep index.md pages for navigation and portal summaries.

Screenshots

Screenshots are useful only when a visual state helps product, QA, support, or implementation teams understand behavior that is hard to explain with text and Mermaid alone. Use screenshots for:

Dense list or dashboard pages where tabs, filters, badges, and row actions matter.
Multi-step flows where the UI state affects the next system action.
Detail pages where several backend resources appear in one screen.

Avoid screenshots for simple forms, static copy, or pages that change often. If a screenshot is added, crop it to the relevant area, use demo data only, avoid PII and payment details, and include alt text that describes the state being shown.

Definition Of Done

A docs page is ready when:

A non-technical reader can understand the feature.
A teammate can understand the behavior that must be preserved.
The real-world example uses a concrete portal situation.
The visual flow shows the main path and important risks.
The should/should-not lists are specific enough to catch regressions.

​Page Structure

​Real-World Examples

​Visual Flow Colors

​Documentation Workflow

​Naming Rules

​Screenshots

​Definition Of Done

Page Structure

Real-World Examples

Visual Flow Colors

Documentation Workflow

Naming Rules

Screenshots

Definition Of Done