Documentation Style & Clarity Standards
This document defines the clear writing guidelines for the Local LLM Server Manager user guides. All contributors and automated agents should follow these rules to ensure clarity and accessibility for everyday users.
Following clear, structured writing principles improves readability, eliminates technical ambiguity, and makes local AI tools easy to use.
Core Writing Rules
Follow these primary rules for all user documentation pages.
1. Keep Sentences Short
- Limit procedural sentences to a maximum of 20 words.
- Limit descriptive sentences to a maximum of 25 words.
- Express only one instruction or idea in each sentence.
TIP
Break complex sentences into two separate sentences. Use numbered steps for sequential instructions.
Do:
Click Settings. Select the Engine Ports panel. Change the Ollama port to
11434.
Do Not:
When you want to change the port for Ollama, you should navigate over to the settings area, find the engine ports panel, and modify the port value to 11434.
2. Use Imperative Mood for Procedures
- Start procedural instructions with an imperative action verb.
- Write direct instructions to the user.
- Do not use polite filler phrases such as "please" or "you should".
Approved Imperative Verbs:
- Click: Use for buttons, icons, and links.
- Select: Use for dropdown items, radio buttons, and checkboxes.
- Type: Use for keyboard text input.
- Open: Use for windows, dialog boxes, and directories.
- Start: Use to activate an engine, process, or service.
- Stop: Use to deactivate an engine, process, or service.
- Do: Use for required operational actions.
- Change: Use when editing an existing setting or value.
- Download: Use when retrieving files from a remote network.
- Save: Use when writing changes to disk.
Do:
Click Save Settings to store your configuration.
Do Not:
You can now click on the Save Settings button if you would like to preserve your changes.
3. Always Use Active Voice
- Make the subject perform the action.
- Do not use passive voice.
- Avoid auxiliary verb chains (for example: "has been created", "was unloaded by").
Do:
The VRAM Orchestrator unloads idle language models before diffusion jobs start.
Do Not:
Idle language models are unloaded by the VRAM Orchestrator before diffusion jobs are started.
4. Use Explicit Nouns Instead of Ambiguous Pronouns
- Do not use ambiguous pronouns such as it, this, that, these, or they.
- Always repeat the explicit noun to prevent confusion.
- Clearly identify the component, file, or setting.
Do:
Download the model file. Move the model file to the configured models directory.
Do Not:
Download the model file. Move it to this directory so it can find it.
5. Approved Vocabulary Reference
Use standard and consistent terminology across all documentation files.
| Approved Word | Disapproved Alternatives | Reason for Rule |
|---|---|---|
| Start | Boot, Launch, Fire up, Kick off | Consistent process action. |
| Stop | Kill, Halt, Terminate, Abort | Consistent process termination. |
| Show | Display, Reveal, Present | Consistent visual description. |
| Do | Perform, Execute, Carry out | Simpler action verb. |
| Change | Modify, Alter, Tweak, Adjust | Clear modification verb. |
| Download | Grab, Fetch, Pull, Snag | Use "Pull" only for Ollama CLI syntax. |
| Remove | Delete, Scrap, Erase, Purge | Consistent deletion action. |
| Send | Transmit, Dispatch, Post | Direct communication verb. |
Alert Callout Conventions
Use GitHub Flavored Markdown alerts to emphasize critical operational information. Do not stack multiple alerts consecutively.
[!NOTE]
Use [!NOTE] for background context, architecture notes, and non-blocking explanations.
NOTE
The background service runs on local port 5246 by default.
[!TIP]
Use [!TIP] for performance optimizations, optional shortcuts, and helpful recommendations.
TIP
Use NVMe storage to reduce model load times during high VRAM workloads.
[!IMPORTANT]
Use [!IMPORTANT] for mandatory prerequisites, required steps, and critical operational constraints.
IMPORTANT
You must run the installer with Administrator privileges to install the Windows Service.
[!WARNING]
Use [!WARNING] to warn against data loss, out-of-memory crashes, or security risks.
WARNING
Do not expose port 5246 directly to the public internet without an authentication proxy.
Markdown Formatting Rules
- User Interface Elements: Put UI buttons, tabs, and menu items in bold text (for example: Settings, Install, Unload All VRAM).
- File Names and Paths: Put file names, directory paths, and commands in inline code blocks (for example:
settings.json,/usr/local/bin,dotnet run). - Relative File Links: Always use relative file paths for links between documentation pages (for example:
../getting-started/index.md). - Lists: Use numbered lists for sequential steps. Use bulleted lists for non-sequential item collections.
Checklist for Technical Authors
Review your document against this checklist before submission:
- [ ] All procedural sentences contain 20 words or fewer.
- [ ] All descriptive sentences contain 25 words or fewer.
- [ ] Every instruction starts with an approved imperative verb.
- [ ] No passive voice constructs remain in the text.
- [ ] No ambiguous pronouns (it, this, they) appear in procedural text.
- [ ] UI labels match the actual application labels exactly.
- [ ] All relative links point to existing markdown files.
- [ ] Alerts use valid GFM alert syntax.