Feature entry template
Use this template when writing a new feature page for the User Guide. Each section below explains what to include and shows an example. A copy-paste template is at the bottom of this page.
All feature pages should follow the Style Guide.
Template structure
Every feature entry should follow this structure, in order. Omit a section only if it genuinely does not apply to the feature.
Frontmatter
---
sidebar_position: [number]
title: [Feature Name]
---
Set sidebar_position to control ordering within the Features category. Use title if the sidebar label should differ from the page heading.
Page heading and overview
Start with a level-1 heading matching the feature name, followed by 1-3 sentences explaining what this feature does and why a user would use it. Write for someone who has never seen the feature before.
A good overview answers two questions: "What does this do?" and "Why would I use it?"
Example:
# Map view
The Map View displays your facilities on an interactive map, letting you visualize geographic distribution and quickly navigate to any facility. Use it to identify regional clusters, spot coverage gaps, or get a high-level picture of your portfolio.
Prerequisites
List anything the user needs before they can use this feature — required roles, permissions, setup steps, or dependent features. Use a bullet list. If there are no prerequisites, omit this section entirely rather than writing "None."
Example:
## Prerequisites
- You must have the Viewer role or higher
- At least one facility must exist in the system
- Facility addresses must be geocoded (see Geocoding)
How to [action]
Name this section "How to [verb phrase]" that describes the primary action — e.g., "How to use the Map View," "How to create an analysis," "How to export a report."
Use a numbered list for the steps. Include screenshots at key decision points or when the UI may not be self-explanatory. See the Style Guide for screenshot standards.
Example:
## How to use the Map View
From the main navigation, click Map
The map displays all facilities in your current project
Click a facility marker to see a summary popup
Click Go to Facility in the popup to open the facility detail page
If the feature supports multiple distinct actions, use separate "How to" subsections:
## How to filter facilities on the map
1. ...
## How to export the map view
1. ...
Each "How to" section should cover one task. If a feature supports several independent tasks, give each its own section rather than combining them into one long procedure.
Troubleshooting
Include common problems users may encounter. Use an H3 heading for each problem, followed by Cause and Solution lines. Include at least 2-3 entries when possible. If the feature is straightforward and unlikely to cause confusion, you may omit this section.
Example:
## Troubleshooting
### Facilities are not appearing on the map
Cause: Facility addresses have not been geocoded.
Solution: Navigate to the facility and click Geocode Address, or ask your administrator to run a batch geocode. See Geocoding.
### Map is blank or tiles are not loading
Cause: The browser cannot reach the map tile server.
Solution: Check your network connection. If you are in an air-gapped environment, verify that the offline tile server is configured. Contact your administrator if the issue persists.
Related features
End with a bullet list of links to related feature pages. This helps users discover connected functionality and navigate between related topics.
Example:
## Related features
- Facility details — view and edit individual facility information
- Analysis — run evaluations on facilities visible in the map
- Exporting data — export facility data including map coordinates
Copy-paste template
Copy everything below into a new .md file and fill in the bracketed placeholders.
---
sidebar_position: [number]
title: [Feature Name]
---
# [Feature name]
[1-3 sentences: what this feature does and why a user would use it.]
## Prerequisites
- [Required role or permission]
- [Any setup or dependent feature]
## How to [action]
1. [Step one]
2. [Step two]
3. [Step three]
:::tip
[Optional tip for a common shortcut or best practice.]
:::
## Troubleshooting
### [Problem description]
**Cause:** [Why this happens.]
**Solution:** [How to fix it.]
### [Problem description]
**Cause:** [Why this happens.]
**Solution:** [How to fix it.]
## Related features
- [Feature name](./[filename].md) — [brief description]
- [Feature name](./[filename].md) — [brief description]