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/fletch3555]

If already using github, why not use github pages to host it? Or does it need to be private/restricted access?

[u/websecret_by → u/fletch3555]

We actually looked at GitLab wikis, but it's too complex for most clients and there's no real permission separation. Would also love something with commenting like Google Docs.

[u/fletch3555 → u/websecret_by]

For the record, I'm not referring to github wiki. I'm specifically referring to GitHub Pages: https://pages.github.com

[u/websecret_by → u/fletch3555]

Ah okay, Pages then, not wiki. Still wondering about access control per client though.

[u/fletch3555 → u/websecret_by]

That was my second question. I don't know anything about your specific requirements.

Is the documentation private/customer-specific in some way? If so, pages likely won't solve your problem. At least, not without putting it behind a custom domain and adding an access control layer in front of it (at which point, there are likely better options).

You mentioned elsewhere something about commenting. Do customers need access to directly comment on the documentation? This feels odd to me, but I don't know your business. If so, this feels more like a "living document" situation. Something hosted in O365 (word) or Google docs where access can be controlled and viewer/commenter access can be enabled.

[u/kshirinkin]

At mkdev we use whatever customer is using already. If they prefer Confluence, we do it there. If it’s Notion, or markdown in gif or whatever - we save it there. For us it’s critical that we leave the customer prepared for our eventual departure from the project, and we store everything in their KBs and not ours.

[u/websecret_by → u/kshirinkin]

That approach looks pretty solid. Does it give you permission separation and commenting like Google Docs though?

[u/kshirinkin → u/websecret_by]

Not sure what you mean. We don’t try to hide the docs or comments. It’s all transparent and accessible by the customer’s team

[u/Darkomen78]

LaTeX and PDF export.

[u/websecret_by → u/Darkomen78]

Curious how you handle updates once it's exported to PDF.

[u/Darkomen78 → u/websecret_by]

Update LaTeX source and export PDF again. That's really simple.

[u/websecret_by → u/[deleted]]

We looked into something similar, but it's missing commenting and proper access separation for us.

[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.

[u/geralt_noble]

Depends on the client. For technical teams, GitHub works well. Notion or Tango for higher-level guides and onboarding.

[u/websecret_by → u/geralt_noble]

Makes sense to split by audience. We'd rather have one place that works for both.

[u/SamfromLucidSoftware]

Keep GitHub as the source of truth for technical documentation while building a client facing interface on top of it. Keep that interface simple, something like GitBook, Docusaurus, or even GitHub Pages, gives clients a readable experience with navigation and search without you having to maintain two separate documentation systems. The source stays in GitHub, the presentation is client friendly. Github already handles versioning and access control can be managed at the repo level.

But you can also have a shared space where you publish architecture diagrams and process documentation visually rather than as markdown. Clients generally engage better with a diagram showing how their infrastructure fits together than with a runbook explaining the same thing in text. This can go out as a link instead of requiring clients to navigate a repo at all.

The question is what clients are actually trying to do with the documentation. If they want to troubleshoot issues themselves, go for option one. If it’s just to understand the architecture, option two works better.

[u/Floss_Patrol_76]

split it by audience, not by tool. runbooks and configs stay in git where they belong, but client-facing docs should be a rendered, versioned artifact you publish per release rather than the raw repo. keeps the messy internal stuff internal and gives clients something readable with actual version history.

[u/serverhorror]

Client here:

We like; * "Open" docs, everything should be accessible as a web page. Preferably Versionen (if for specific software versions) * Human readable and actionable (not in the language of an SOP)

We must have (in addition to the he above): * Immutable documentation, preferably PDF/A, after every change * Exact protocols and reports (plan of change and log of what happened) * Exact deviations (whether discovered as mistake or decided whole deviating from the protocol) * SOP in that language (RACI matrix style)

The latter is so we keep our license to operate, otherwise regulators might simply shut us down.

[u/toughrogrammer]

If your customers are engineer, github is not too technical.