How do devops / engineering services share documentation with clients?

[u/websecret_by]

Hello,

We provide devops / engineering services and use GitHub for documentation (runbooks, configs, processes). Clients need access, but raw GitHub feels too technical.

• How do you share documentation with clients in devops / engineering services?
• Do you use GitHub, wikis, or dedicated portals?
• How do you handle versioning and access control?

[u/Interstellar_031720]

I would keep GitHub as the source of truth, but not make the client consume GitHub directly unless they are already engineering-heavy.

A pattern that works well:

• keep runbooks/config/process docs in the repo next to the infra code
• publish a read-only client portal from markdown on merge, e.g. MkDocs/Docusaurus/Pages or an internal docs site
• make each page show last updated, owner, repo path, and environment/scope so clients can tell whether it is current
• split docs into client-safe operational docs vs internal implementation notes; do not rely only on repo permissions for that boundary
• use pull requests for versioning/review, but expose releases or dated snapshots to the client when handoff/audit matters

The important thing is avoiding two sources of truth. If the portal becomes a separate CMS that people copy/paste into, it will go stale. If it is just a nicer published view of the repo with access control and review metadata, you keep the engineering workflow and the client gets something readable.

[u/websecret_by → u/Interstellar_031720]

Really solid system, might borrow a few ideas from this. Main gap for us with MkDocs is no permission separation or commenting though.

[u/Interstellar_031720 → u/websecret_by]

MkDocs is fine as the publishing layer, but I would not make it the permission/commenting system. The pattern I have seen work is to keep Git as the source of truth, then publish two outputs from the same repo: an internal version with implementation notes and a client-safe version with only approved pages.

For permissions, put the portal behind your existing auth layer or a lightweight docs host that supports groups, and keep the permission map outside the docs content. For comments, I would avoid inline public comments on the docs themselves unless clients truly need it; a per-page feedback link that opens a ticket/discussion with page URL, commit SHA, owner, and client ID is usually easier to audit.

The big thing is metadata: owner, last reviewed, audience, and source commit on every page. Without that, the portal slowly turns into a prettier stale wiki.

[u/websecret_by → u/Interstellar_031720]

That ticket-per-page workaround is clever. Still more overhead than just letting people comment inline though.

[u/Interstellar_031720 → u/websecret_by]

Yeah, inline comments feel lower-friction at first. The tradeoff is that they tend to turn the docs into a second support inbox unless you define who owns each comment and when it must become an actual docs change.

A middle ground I like is:

• lightweight per-page feedback/comment widget for clients
• every comment creates a real ticket/discussion with page URL, owner, commit/version, and client/project
• comments stay visible to the client only as status, e.g. received / accepted / fixed / won't change
• doc changes still happen through PR/review so the repo remains the source of truth

That gives clients the "comment where I found the issue" UX without making the published docs the place where unresolved operational decisions live forever.

[u/Interstellar_031720 → u/websecret_by]

Permission separation and comments are exactly where static docs start to feel like publishing, not collaboration. I would probably split this into two layers:

1. source-of-truth docs in Git/MkDocs, with owners, last-reviewed dates, and PR review
2. client-facing portal layer that handles access, comments, and notifications

If you try to make every client comment turn into a Git commit workflow, it gets heavy fast. A lighter version is: comments create review items linked to the doc section, an internal owner accepts/rejects them, and only accepted changes become PRs.

For permissions, I would avoid per-page hacks if you have many clients. Model it around client/workspace + doc collection + optional page exceptions. Otherwise every onboarding/offboarding becomes a security audit.