Style guide

Writing and formatting standards for the Siter User Guide. All contributions should follow these guidelines. For a quick-scan summary, see the quick reference at the bottom of this page.

Voice and tone

Write for end users

The audience is non-technical end users of Siter. Assume they are familiar with their own domain (facility evaluation, site analysis) but not with software terminology.

Do: "Click Save to keep your changes."
Don't: "The PUT request persists the entity to the database."

Be direct and instructional

Use the imperative mood for instructions. Lead with the action, not the context.

Do: "Click Map to open the Map View."
Don't: "If you'd like to see your facilities on a map, you can navigate to the Map View by clicking on the Map button in the navigation bar."

Use active voice

Prefer active voice over passive voice.

Do: "Siter saves your changes automatically."
Don't: "Your changes are saved automatically by the system."

Be concise

Say what needs to be said, then stop. Avoid filler phrases.

Avoid	Prefer
"It is important to note that..."	Start directly with the information
"Please be advised that..."	Start directly with the instruction
"In order to..."	"To..."
"You will need to..."	Use the imperative: "Open..." "Click..."

Maintain a professional, friendly tone

Write as a knowledgeable colleague — not a textbook or a chatbot.

Do: "You'll need at least the Viewer role to access this page."
Don't: "Hey! So you're gonna need Viewer permissions for this one."
Don't: "The user is required to possess the Viewer role to access the aforementioned page."

Headings

Use sentence case

Capitalize only the first word and proper nouns.

Do: "How to create an analysis"
Don't: "How To Create An Analysis"

Use descriptive, action-oriented headings

Headings should tell the reader what they'll learn or do.

Do: "How to export a report"
Don't: "Exporting" or "Reports"

Heading hierarchy

H1 (#): Page title only — one per page, matching the feature name
H2 (##): Major sections (Prerequisites, How to..., Troubleshooting, Related features)
H3 (###): Subsections within a major section
Never skip heading levels (e.g., don't go from H2 to H4)

Terminology

Consistent feature and UI names

Always refer to UI elements and features by their exact label as shown in the application. Use bold for UI element names the user must interact with.

Do: Click Analysis in the sidebar.
Don't: Click the analysis section on the left.

Standard terms

Use these terms consistently throughout the docs:

Use	Don't use
click	press, hit, tap (unless on mobile)
select	choose, pick
enter	type in, input
sign in / sign out	log in / log out, login / logout
navigate to	go to, visit, browse to
Siter	the application, the system, the tool

Avoid jargon

Do not use developer-facing terminology in user-facing docs.

Avoid	Prefer
API, endpoint	(omit — users don't interact with these)
database, query	(omit or describe the user-visible effect)
deploy, container	(use only in Environment Management section)
null, undefined	"empty" or "not set"
boolean, string	describe the value ("yes/no", "text")

note

The Environment Management section is an exception — it targets administrators who work with Docker and configuration, so technical terms are appropriate there.

Formatting

Bold

Use bold for:

UI element names the user interacts with: Click Save
The first mention of a key term being defined

Do not use bold for emphasis in running text. Restructure the sentence or use an admonition instead.

Italics

Use italics sparingly for:

Introducing a term for the first time when not using bold
Referencing titles of external documents

Code formatting

Use inline code for:

File names: docker-compose.yaml
Environment variable names: ASPNETCORE_ENVIRONMENT
Command-line input: docker compose up -d
Exact values the user must type or that appear in configuration

Use fenced code blocks for multi-line commands or configuration. Always include a language identifier (yaml, bash, json, etc.).

```yaml title="docker-compose.yaml"
services:
  siter-api:
    image: siterapi:latest
```

warning

Code formatting is typically only appropriate in the Environment Management and Contributing sections. Feature pages aimed at end users should rarely contain code blocks.

Lists

Use numbered lists for sequential steps (instructions, procedures).

Use bullet lists for unordered collections (prerequisites, related features, notes).

Keep list items parallel in structure. If one item starts with a verb, all items should start with a verb.

Do:

Click Map to see the overview
Click a marker to view facility details
Click Export to download the data

Don't:

You can see the overview by clicking Map
Facility details are shown by clicking a marker
Exporting is done with the Export button

Tables

Use tables for structured reference data (environment variables, configuration options, field descriptions). Every table must have a header row.

Keep table cells concise. If a cell needs more than one sentence, consider using a list or a separate subsection instead.

Admonitions

Use Docusaurus admonitions for callout boxes. Choose the type based on the content:

Type	When to use
`:::tip`	Shortcuts, best practices, or "nice to know" information
`:::note`	Additional context that supplements the main instruction
`:::info`	Background information or explanations
`:::warning`	Actions that could cause unexpected results or require caution
`:::danger`	Actions that could cause data loss, security issues, or are irreversible

Rules:

Maximum 2 admonitions per page section (H2 level)
Do not stack admonitions back-to-back — separate them with body text
Do not put core instructions inside admonitions — they are supplementary
Keep admonition text brief (1-3 sentences)

Screenshots and images

When to include screenshots

Include a screenshot when:

The user must find a specific UI element that is not obvious from the text
A multi-step configuration involves a complex form or dialog
The result of an action is visual (e.g., a map, chart, or status indicator)

Do not include a screenshot when:

The instruction is a single click on a clearly labeled button
The screenshot would show a generic text field or simple dialog
The UI is likely to change frequently (prefer text descriptions that remain accurate)

Image guidelines

Guideline	Standard
Format	PNG for screenshots, SVG for diagrams
Width	Resize to a maximum of ~1200px wide
File size	Compress PNGs before committing
Location	Place in an `img/` folder alongside the markdown file
Naming	Descriptive, kebab-case: `map-view-filter-panel.png` not `screenshot1.png`
Annotations	Red rectangle outline only (2px, `#FF0000`). No arrows, circles, or numbered callouts

Alt text

Always provide descriptive alt text. Describe what the image shows, not just the feature name.

Do: ![Facility markers displayed on the interactive map](./img/map-view.png)
Don't: ![Map](./img/map-view.png)
Don't: ![Screenshot](./img/screenshot1.png)

Links

Internal links

Use relative paths to link to other pages within the User Guide:

See [Facility details](./facility-details.md) for more information.

Cross-references

When referencing another feature by name, link it on first mention within a section. Do not link every subsequent mention.

External links

Avoid linking to external sites unless the user needs to visit them to complete a task (e.g., Azure Portal for SSO setup). Do not link to general reference material or background reading.

Page structure

Every feature page should follow this order. See the feature entry template for a detailed breakdown with examples.

Frontmatter (sidebar_position, title)
H1 heading (feature name)
Overview paragraph (what it does, why to use it)
Prerequisites (if applicable)
How to [action] sections (numbered steps with screenshots)
Troubleshooting (if applicable)
Related features (links to related pages)

Do not reorder the standard sections. Additional sections specific to a feature (e.g., "Configuration options" or "Permissions") should go between the How-to and Troubleshooting sections.

Writing checklist

Use this checklist before submitting a new page or update:

Quick reference

An abbreviated version of this guide for quick scanning:

Sentence case for headings — capitalize only the first word and proper nouns
Bold for UI elements: click Save, select Analysis
Imperative mood for instructions: "Click," not "You should click"
Active voice: "Siter saves your changes," not "Your changes are saved"
Numbered lists for steps, bullet lists for non-sequential items
Screenshots only when the UI isn't self-explanatory — always include alt text
Admonitions sparingly — max 2 per section, don't stack them
No jargon — write for non-technical end users
Consistent terms — "click," "select," "enter," "sign in," "navigate to"
Troubleshooting uses Problem / Cause / Solution format
Page structure follows the feature entry template
Preview with npm start before submitting

Voice and tone​

Write for end users​

Be direct and instructional​

Use active voice​

Be concise​

Maintain a professional, friendly tone​

Headings​

Use sentence case​

Use descriptive, action-oriented headings​

Heading hierarchy​

Terminology​

Consistent feature and UI names​

Standard terms​

Avoid jargon​

Formatting​

Bold​

Italics​

Code formatting​

Lists​

Tables​

Admonitions​

Screenshots and images​

When to include screenshots​

Image guidelines​

Alt text​

Links​

Internal links​

Cross-references​

External links​

Page structure​

Writing checklist​

Quick reference​