✨ Written with help of AI

If your wiki reads like filler episodes and your runbooks require a Sherpa, it’s time for a refactor. In 2025, documentation isn’t a chore—it’s operational muscle. Your AI copilots, on-call engineers, and auditors will all depend on the accuracy and structure of what you write. Think of it like building your own Urahara Shop: stocked with the right tools, clearly labeled shelves, and a map anyone can follow at 2 a.m.

Here’s my playbook—equal parts open source, cybersecurity, and practical craft.

Why IT Pros Need Better Docs Now

• AI-assisted support is only as good as your source material. Garbage in, hallucinations out. Structured, current docs make AI search and internal copilots actually useful ¹.
• Self-service is the new normal. IT teams are expected to publish living knowledge bases that reduce tickets and speed onboarding ².
• More formats, more audiences. From users to auditors to SREs, each needs different depth and structure ³.
• Distributed teams demand repeatability. Good document management—versioning, naming, access controls—keeps chaos at bay ⁴.

A Simple Framework: Audience → Outcome → Action Before you type a word, answer three questions:

1. Who’s this for? Help desk, developers, finance, auditors?
2. What outcome do they need? Resolve a VPN issue, deploy a service, pass a SOC 2 audit?
3. What action will they take now? Follow a runbook, configure a client, check a dashboard?

This is step zero in most modern guides for technical documentation in 2025: define audience and scope, then choose the right format (runbook, SOP, architecture note, user guide, postmortem) [^2 ] ³.

Build A Docs Toolbox You’ll Actually Use (Open Source FTW) Pick a docs-as-code stack so you get version control, review, and CI for free:

• Static site generators: MkDocs (Material theme), Docusaurus, Sphinx, Asciidoctor. All play nicely with GitHub/GitLab CI.
• Diagram-as-code: Mermaid or PlantUML. Keep diagrams in the repo so they’re diffable.
• Linting and link checking: Vale for style, markdownlint for formatting, lychee for links.
• API docs: OpenAPI + Redoc or Redocusaurus.

Example quickstart:

• MkDocs

  • pip install mkdocs mkdocs-material
  • mkdocs new it-docs && cd it-docs
  • mkdocs serve (local preview) → mkdocs build (publish)

• Docusaurus

  • npx create-docusaurus@latest it-docs classic
  • npm run start (dev) → npm run build (publish)

Trends for 2025 emphasize structured authoring, content reuse, and omnichannel publishing—areas where docs-as-code and componentized docs shine ¹.

A Lightweight Template That Scales Use a standard template per doc type. Here’s a Markdown runbook you can copy:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

Title: Restore Access to Corporate VPN (OpenVPN)

Last updated: 2025-09-15
Owner: NetOps (on-call: @netops-oncall)
Risk level: Medium
Time to complete: 10–15 minutes

Prerequisites
- User account active in Okta
- Laptop on corporate-managed image
- On-call permissions in JumpCloud

Symptoms
- User reports “AUTH FAILED” on OpenVPN macOS client
- Logs show TLS handshake succeeded, MFA rejected

Root Causes (Common)
- Okta factor drift after device change
- Revoked cert due to offboarding error

Resolution Steps

1. Verify user status in Okta (Active). If Suspended, coordinate with HRIS. Do not reactivate without ticket.
2. Re-enroll MFA: Send enrollment link; confirm factor push succeeds.
3. Regenerate VPN client profile (ovpn) from Access Gateway; confirm fingerprint with user.
4. Test connection on user device over mobile hotspot (bypasses captive portals).
5. Rotate user cert if prior cert mismatch in logs.

Validation

• User connects; server log shows TLS + MFA OK
• Zabbix VPN dashboard shows session active

Rollback

• Revoke issued cert and disable profile
• Revert group membership in Okta (snapshot: TICKET-12345)

Security Notes

• Never request or view user’s OTP codes
• Redact usernames in screenshots
• Do not paste logs with tokens into tickets

References

• Access Gateway docs
• Okta group mapping policy

Making Docs Runnable and Testable Nothing rots faster than untested examples. Adopt practices communities have refined over years:

• Validate code blocks and config snippets. Use doctest/pytest for code; shellcheck for scripts; kubeval/kubeconform for YAML; tf validate for Terraform.
• Compile or render your docs in CI. Broken links and images should fail the build.
• Keep examples close to source. In language ecosystems like OCaml, doc comments and examples compiled with the build keep docs honest—a best practice seasoned folks emphasize so examples don’t drift [^7 ] ⁵.

Example GitHub Actions workflow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

name: docs-ci
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install mkdocs mkdocs-material
      - run: mkdocs build --strict
      - run: pip install vale
      - run: vale docs/
      - run: curl -sSfL https://github.com/lycheeverse/lychee/releases/latest/download/lychee-linux.zip -o lychee.zip && unzip lychee.zip -d lychee
      - run: ./lychee/lychee --verbose docs/**/*.md

Information Architecture and Reuse (Without Going Full Yak-Shave)

• Topic-based structure: small, standalone topics (task, concept, reference). This supports reuse across audiences and channels ¹.
• Reuse patterns: shortcode snippets, shared includes for repeated warnings, variables for environment names.
• Metadata matters: tags, owners, last-reviewed date. This boosts search and helps triage.
• Document management basics: version naming conventions, clear permissions, check-in/out or branch workflows, and retention policies. These reduce risk and keep people from reading the wrong thing under pressure ⁴.

Diagrams-as-Code for Clarity That Ages Well Stop uploading stale PNGs. Keep diagrams in Git:

• Mermaid example:

1
2
3
4
5

flowchart LR
  User -->|MFA| Okta
  Okta --> VPN[OpenVPN GW]
  VPN -->|TLS| Server
  Server --> SIEM[SIEM]

• PlantUML for sequence/architecture diagrams in complex systems.
• Regenerate visuals in CI so they’re always current.

Editorial Discipline: The Boring Stuff That Wins Incidents

• Define a style guide (Google Developer or Microsoft). Enforce with Vale in CI.
• Set review cadences: critical runbooks reviewed monthly; others quarterly. Good documentation practices stress accuracy, peer review, and controlled updates ⁶.
• Track metrics: search queries with no results, time-on-page for key runbooks, internal ticket tags. IT knowledge base platforms highlight reduced ticket volume and higher self-service as core KPIs ².

Security Considerations (Because Attackers Read Docs Too) Documentation can leak secrets, create blueprint-level detail for attackers, or train the wrong AI model.

Practical safeguards:

• Secret hygiene
  • Scan repos with gitleaks or trufflehog. Treat docs like code—fail builds on secrets.
  • Use redaction filters in screenshot tools; scrub EXIF data before upload.
• Principle of least privilege in examples
  • Provide minimal scopes in IAM snippets; never copy-paste admin roles as “quick start.”
  • Ship secure-by-default configuration examples and call out risky toggles.
• Audience segmentation
  • Classify docs: public, internal, restricted. Gate restricted content with SSO. Maintain audit logs on access.
• Threat modeling your docs
  • Assume an attacker has your public docs. Do you expose sensitive topology, vendor versions, or incident playbooks that reduce your defensive uncertainty?
• AI/content tools
  • If using AI to draft docs, ensure prompts and snippets don’t include sensitive data, and prefer on-prem or compliant vendors for internal knowledge bases ¹.
• Compliance
  • Maintain review trails, approval metadata, and retention rules aligned to frameworks (SOC 2/ISO 27001). Solid document management practices make audits smoother [^5 ] ⁶.

Community Angle: Docs as an Onramp, Not an Afterthought Open-source communities thrive on approachable docs—examples that build, quickstarts that actually quickstart, and issue templates that invite contributions. Borrow what works:

• Good first docs issues: label typos, missing examples, or outdated screenshots for newcomers.
• CODEOWNERS for doc folders ensures timely review.
• “Examples are tests”: wire example code into CI so contributors see failures early—an approach widely discussed in language communities and forums focused on keeping examples in sync [^7 ] ⁵.

Mini Checklist: Tips and Tricks That Compound

• Start with the user’s first task, not the system’s first concept.
• Put the “happy path” first; move edge cases to a later section.
• Show commands, then explain them. Use copy-paste blocks.
• One page, one job. If a doc does three things, split it.
• Add “Last reviewed” and an owner. Stale docs are worse than no docs.
• Prefer diagrams-as-code and text over binary assets.
• Lint, link-check, and build in CI. Fail fast.
• Log search queries; write the docs people are trying to find.
• Keep a “Doc Debt” board in your backlog and burn it down like tech debt.
• Write like future-you at 03:00 will thank present-you.

Putting It All Together If you adopt docs-as-code, keep examples executable, and apply a security lens, your documentation stops being a brittle liability and becomes operational superpower. The tools are open source, the habits are learnable, and the payoff is immediate: fewer tickets, faster incidents, smarter AI assistants, happier teams.

What’s the one doc you wish existed at your company right now? Drop your pain point (or favorite tool) in the comments—let’s build a community checklist and share templates. And if you’ve got a killer Mermaid diagram or Vale config, I’m all ears. Believe it!

References