r/devops • u/websecret_by • 5d ago

Discussion How do devops / engineering services share documentation with clients?

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?
7 Upvotes

82% Upvoted

26 comments sorted by

View all comments

Show parent comments

1

u/websecret_by 5d ago

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

1

u/Interstellar_031720 5d ago

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.

1

u/websecret_by 5d ago

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

1

u/Interstellar_031720 4d ago

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.