Documentation Style Guide - YouNegotiate Docs

These docs are not only feature descriptions. They are product behavior contracts for non-technical readers, product owners, QA, and developers.

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

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.
`Developer Notes`	Optional. Add when the feature has special implementation rules.
`Related App Areas`	Optional. Add source hints when developers need a starting point.

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.

Developer Notes

Add Developer Notes when a feature has hidden behavior, background jobs, payment effects, cache counts, access rules, or status transitions. Examples:

Sidebar badges depend on cached counts.
Payment retries should not duplicate charges.
Consumer data must stay scoped to the creditor and sub-account.
A page appears only for parent accounts or only when setup is incomplete.

Add Related App Areas when developers need a source starting point, but keep it light. Good:

## Related App Areas

- Routes: `routes/creditor/index.php`
- Background schedule: `app/Console/Kernel.php`

Avoid turning docs into technical implementation notes. The codebase remains the source of truth for exact implementation.

Screenshots

Screenshots are useful only when a visual state helps developers, QA, or product 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 developer can understand the behavior they must preserve.
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

​Developer Notes

​Related App Areas

​Screenshots

​Definition Of Done

Page Structure

Real-World Examples

Visual Flow Colors

Documentation Workflow

Naming Rules

Developer Notes

Related App Areas

Screenshots

Definition Of Done