Configuration Documentation Style Guide

Authoring standard for all configuration articles in the Meridian knowledge base. Every team producing config documentation follows these rules. Consistency across 400+ articles is what makes the KB usable at scale.

Voice and Tone

Second person. Present tense. Active voice. You are telling the reader what to do and what the system does in response.

Rule	Correct	Wrong
Use "Go to" for navigation	Go to Admin > System Variables.	Navigate to the System Variables page.
Use "displays" for system responses	The Variable Detail panel displays.	The Variable Detail panel opens / appears / is shown.
Use "select" for discrete choices	Select Enabled from the Status dropdown.	Choose Enabled from the Status dropdown.
Use "enter" for free text	Enter the endpoint URL in the Base URL field.	Type in the URL where indicated.

Do not hedge. Do not write "you may want to" or "it is recommended that." State the action. If a step is conditional, state the condition: "If your organization uses SSO, configure the Identity Provider field."

Article Structure

H2 headings divide content. No H3 for major sections. No horizontal rules.

• H1: Article title. One per article.
• H2: Major sections (Overview, Prerequisites, Configuration Steps, Related Articles).
• H3: Subsections within an H2. Use sparingly.
• H4: Reserved for system variable names and feature toggle names only.

Standard section order:

1. Overview: one to three sentences. What the config controls and who it affects.
2. Prerequisites: roles, dependent configs, environment requirements. Omit if none.
3. Configuration Steps: numbered procedure, step/result pattern.
4. Related Articles: links to adjacent configurations. Five max.

The Step/Result Pattern

Every procedure uses this pattern. Numbered step describes a single user action. Indented result immediately follows, describing the system response.

Correct:

1. Go to Admin > Care Programs > Program Settings.

   The Program Settings list displays all active programs.

2. Select the program to configure.

   The Program Detail panel displays.

3. Set the Auto-Enrollment toggle to On.

   The Enrollment Criteria section displays below the toggle.

Wrong:

1. Navigate to Admin, then Care Programs, then Program Settings.
2. You will see a list of programs. Find and click the one you want.
3. There is a toggle for Auto-Enrollment. Turn it on and the
   Enrollment Criteria section will appear.

Rules:

• One action per step. Never combine two clicks into a single numbered item.
• Results are indented. They describe what the system does, not what the user should feel.
• If a step has no visible system response, omit the result line.
• Bold all UI element names: field labels, button text, menu paths, toggle names.

System Variable Template

Variable name as H4 heading. Description paragraph. Field/Value table before any steps.

#### ENABLE_CARE_GAP_ALERTS

Controls whether the system generates care gap alerts for members
who have not completed scheduled assessments within the configured
time window.

| Field         | Value                    |
|---------------|--------------------------|
| Variable Name | ENABLE_CARE_GAP_ALERTS   |
| Data Type     | Boolean                  |
| Default Value | False                    |
| Scope         | Organization             |
| Restart Req.  | No                       |

To enable care gap alerts:

1. Go to Admin > System Variables.

   The System Variables list displays.

2. Search for ENABLE_CARE_GAP_ALERTS.

   The variable row highlights.

3. Select the variable row.

   The Variable Detail panel displays.

4. Set the Value field to True.

5. Select Save.

   Confirmation toast displays. Takes effect immediately.

Every system variable article must include the Field/Value table. No blank cells. Use "N/A" if not applicable.

Feature Toggle Template

Same rules as system variables, plus two additions:

• Availability row in the table: which edition includes the toggle (Standard, Professional, Enterprise).
• Dependent Toggles section: parent/child toggles that must be in a specific state for this one to work.

If the toggle controls UI visibility, state what the user sees on vs. off in one sentence. No screenshots of both states.

Anti-Patterns

Articles containing these are returned without further review.

Anti-Pattern	Why It Fails	Fix
Walls of text	Paragraphs over four lines get skipped entirely.	Break into lists or step/result sequences.
Passive voice	"The setting is configured by the administrator" hides the actor.	"Configure the setting."
Screenshots without context	A screenshot with no preceding step is visual noise.	Place after the step it illustrates. Caption if the relevant area is not obvious.
Undated version references	"In a recent release" means nothing in 6 months.	Specific version: "Available in Meridian 2024.3 and later."
Conditional steps without conditions	"You might need to restart" leaves the reader guessing.	"If you changed the Scope field, restart the Configuration Service."
Workarounds documented as procedures	Workarounds rot without warning.	File a backlog item. Document the intended path only.

Pre-Publish Checklist

Run through every item before submitting. Articles that fail any item are returned without review.

1. Voice: No passive voice. No future tense. No "Navigate to." No "please."
2. Structure: H2 for major sections. No HRs. Standard section order.
3. Steps: One action per step. Results indented. System response only.
4. Variable/toggle table: Present. All rows populated.
5. Version references: Specific release number. No "recently" or "soon."
6. Links: All cross-references point to published articles. None to drafts.
7. Screenshots: Follow a step. Have context. No empty-state screenshots unless documenting a default.
8. Metadata: Title follows naming convention. Tags include domain area and module.

If you are unsure whether something violates this guide, it does. Simplify. When a config article is clear, support does not get tickets about it. That is the standard.