Skip to content

Content Structuring Rules

Below is a clear, reusable rule set you can adopt for your infrastructure documentation. It is written to be practical, mkDocs‑safe, and compatible with your existing template.

I will define:

  1. What a procedure is
  2. What configuration is
  3. Hard separation rules
  4. mkDocs‑specific formatting rules
  5. A quick decision checklist

No stylistic emphasis, no bold used.

1. Definition: Procedure

A procedure describes actions that are performed in a defined order to achieve a result.

A procedure answers:

  • What do I do?
  • In which order?
  • Where do I click or what do I run?
  • When is the step considered complete?

Typical characteristics:

  • Time‑bound
  • Order‑dependent
  • Often UI‑ or CLI‑driven
  • Executed by a human

Examples:

  • Installing Keycloak
  • Creating a realm
  • Importing a configuration file
  • Regenerating client credentials
  • Navigating through admin UIs

2. Definition: Configuration

Configuration describes static or semi‑static settings that a system consumes.

Configuration answers:

  • What values does the system expect?
  • Where are these values stored?
  • What do they control?
  • What happens if they are missing or wrong?

Typical characteristics:

  • Order‑independent
  • Declarative
  • Environment‑specific
  • Often stored in files, environment variables, or databases

Examples:

  • oauth.properties parameters
  • docker‑compose.yml values
  • Groovy configuration blocks
  • Realm settings (issuer, audience, scopes)
  • Password policy regex

3. Hard separation rules (non‑negotiable)

These rules are meant to avoid both conceptual confusion and mkDocs rendering issues.

Rule 1
Procedures live only in the “Step‑by‑Step Setup” section.

Rule 2
Configuration never appears inside a numbered list.

Rule 3
A procedure may reference configuration, but must not define it inline.

Example (allowed):

  • Step: Configure oauth.properties
  • Reference: See Configuration Details → OAuth Parameters

Example (not allowed):

  • Step 3: Set oauthHost=10.0.58.1, oauthPort=8180, issuer=…

Rule 4
If a section can be executed twice in a different order, it is not a procedure.

Rule 5
If removing step numbers does not change meaning, it is configuration.

4. Formatting rules for procedures (mkDocs‑safe)

Use numbered lists only for procedures.

Rules:

  • Maximum 5–7 steps per list
  • Each step is one action
  • No code blocks inside list items unless unavoidable
  • No images inside list items
  • No admonitions inside list items

Good pattern:

### Import the Realm

1. Open Keycloak.
2. Select Create realm.
3. Choose Import file.
4. Upload the generated realm file.

Bad pattern:

  • Long explanations inside steps
  • Embedded screenshots or warnings inside the list
  • Configuration snippets inside steps

If a step needs explanation, put the explanation before or after the list.

5. Formatting rules for configuration (mkDocs‑safe)

Configuration belongs in “Configuration Details” or application‑specific subsections.

Rules:

  • Use headings, not numbering
  • Group by purpose, not by execution order
  • Use code blocks for examples
  • Explain parameters outside code blocks

Good pattern:

### OAuth Parameters

oauthHost  
DNS name or IP address of the Keycloak host.

oauthPort  
Port exposed by Keycloak.

Example:

```yaml
oauthHost=10.0.58.1
oauthPort=8180

```

Bad pattern: - “Step 4: Set the following values” - Mixing explanation and values inside one long list item

6. Where common Keycloak topics belong

Realm creation
Procedure (generation + import)

Realm structure and purpose
Configuration

Client secret regeneration
Procedure

Where the secret is stored and used
Configuration

Password regex
Configuration

Click path to add password policy
Procedure

oauth.properties file location
Configuration

Placing the file in the directory
Procedure

7. Decision checklist (quick)

Ask these questions:

  1. Does order matter?
  2. Yes → procedure

  3. No → configuration

  4. Is a human clicking or running commands?

  5. Yes → procedure

  6. No → configuration

  7. Would this make sense without step numbers?

  8. Yes → configuration

  9. No → procedure

  10. Would mkDocs break if I add a code block here?

  11. Yes → move to configuration section

8. One‑sentence rule to remember

Procedures tell the reader what to do.
Configuration tells the system how to behave.

Changelog

Date Author Message
2026-03-04 aresnikowa qc-0: postediting
2026-03-04 aresnikowa QC-47927: aligned with the template, mkDocs formatting alignment