Documentation Style Guide

This guide establishes standards for all ekx documentation to ensure consistency and clarity.

Audience

Primary audience: End users - electrical engineers and technicians who build and analyze single-line diagrams in the application.

Assume readers:

Have electrical engineering knowledge (don't explain basic EE concepts)
May be unfamiliar with the software interface
Want to accomplish tasks efficiently
Prefer practical examples over theoretical explanations

IMPORTANT: User-facing documentation only

Document ONLY features and changes visible to end users:

✅ New UI features, buttons, panels
✅ Changed workflows or procedures
✅ New calculation capabilities
✅ Settings and configuration options
✅ Bug fixes that change user behavior

Do NOT document internal changes:

❌ Code refactors (unless they change user workflow)
❌ Internal API signatures
❌ Database schema changes (unless they enable user features)
❌ Performance optimizations (unless user-noticeable)
❌ Developer tooling or build system changes

When in doubt: If a user wouldn't notice the change while using the application, don't document it in user-facing docs. Technical implementation details belong in AGENTS.md (for developers) or code comments, not in docs/ (for users).

Voice and Tone

Direct and professional - Write in second person ("You can add a bus by...")
Task-oriented - Focus on what users need to do, not how the system works internally
Concise - Avoid filler words and unnecessary qualifications
Confident - Use definitive language ("Click Save" not "You might want to click Save")

Avoid

Marketing language or superlatives
Internal implementation details unless relevant to the user
Passive voice when active is clearer
Jargon specific to our codebase (e.g., "server actions", "React Flow")

Document Structure

Page Organization

Title - Clear, action-oriented when possible
Overview - 1-2 sentences explaining what this page covers
Prerequisites (if any) - What the user needs before starting
Main content - Organized by task or concept
Related topics (if helpful) - Links to related documentation

Headings

Use sentence case: "Adding a transformer" not "Adding a Transformer"
Be specific: "Configuring cable ampacity" not "Cable settings"
Limit to 3 heading levels (H1, H2, H3) - deeper nesting indicates poor organization

Terminology

Use consistent terms throughout all documentation:

Use	Don't Use
single-line diagram (SLD)	one-line diagram, schematic
component	element, node, object
canvas	workspace, diagram area
connection	edge, wire, link
bus	busbar (unless specifically about physical equipment)
protection device	protective device, breaker (unless specific)
power flow analysis	load flow, power flow calculation

Electrical Standards

Reference NEC 2026 as the default code book
Use standard electrical abbreviations: kV, kVA, MVA, A, MW, MVAR
Write units with a space: "13.8 kV" not "13.8kV"

Formatting Conventions

UI Elements

Bold for clickable UI elements: "Click Save"
Use exact text as shown in the UI
Describe location when helpful: "In the Properties panel, click Apply"

Values and Inputs

Use code formatting for values users type: 13.8
Use code formatting for field names when referencing data: rated_voltage

Use arrows for navigation sequences: > Settings > Project > Defaults

Warnings and Notes

Use blockquotes with labels:

> Note: Additional helpful information that isn't critical.

> Warning: Information about potential data loss or incorrect results.

> Important: Critical information the user must understand.

Procedures

Step-by-step Instructions

Number each step
Start with an action verb
One action per step (unless trivially related)
Include expected results when helpful

Example:

Select the bus on the canvas.
In the Properties panel, enter the rated voltage in kV.
Click Apply. The bus updates with the new voltage.

Screenshots

Include screenshots when the UI is complex or unfamiliar
Annotate with numbered callouts for multi-step explanations
Keep screenshots focused - crop to relevant area
Update screenshots when UI changes

Tables

Always include a blank line before AND after tables
Never leave table cells empty - use - or "N/A" instead
Always include the header separator row
Keep tables simple - if more than 5-6 columns, consider a different format

Code and Formulas

Electrical Formulas

Use LaTeX-style formatting where supported, or clear ASCII:

I = P / (√3 × V × PF) for inline
Display complex formulas on their own line

Configuration Examples

When showing settings or configuration:

Voltage: 13.8 kV
Rated Current: 1200 A
Installation Type: Underground

File Naming

Use lowercase with hyphens: adding-components.md
Be descriptive: cable-ampacity-calculations.md not cables.md
Group related docs in folders: analysis/power-flow.md

Review Checklist

Before publishing documentation:

[ ] Tested all procedures in the current version
[ ] Screenshots match current UI
[ ] All links work
[ ] Terminology is consistent with this guide
[ ] No internal/developer jargon
[ ] Spelling and grammar checked