We provide DevOps and engineering services and currently keep runbooks, configuration details, and processes in GitHub. Our clients need access to this information, but many of them are not comfortable navigating repositories, pull requests, or diffs. How do you share documentation in a way that is readable for clients while still preserving version history and access control? Do you use GitHub directly, a wiki, a documentation portal, or a customer-owned knowledge base? We would also like clients to be able to comment on or discuss specific pages without creating a second source of truth.
4 Answers
Organize the documentation by audience rather than trying to make one tool serve everyone. Keep runbooks, configuration, and implementation details in Git, while publishing a simpler, versioned client artifact for each release. A separate architecture overview with diagrams can work especially well for nontechnical stakeholders. The main rule is to avoid manually copying content into a second system, because it will eventually become stale.
Some clients need formal records in addition to a browsable website. Give them readable web pages for day-to-day use, then generate a PDF or PDF/A snapshot after approved changes. Include the exact change plan, execution report, deviations from the plan, applicable procedures, and responsible roles. This provides an immutable audit trail while the online documentation remains searchable and easier to update.
Use the customer’s existing knowledge base whenever possible. If they already operate Confluence, Notion, or another internal system, putting the final documentation there leaves them prepared to manage it after your engagement ends. Git can still hold the technical source material, but the customer-owned copy should include clear ownership, permissions, update dates, and an agreed process for comments and approvals.
That is appealing for handoff, but maintaining a version in our system and another in the customer’s system can create synchronization problems. We would need a reliable publishing workflow.
A good compromise is to keep GitHub as the source of truth and publish a client-friendly site from the Markdown whenever changes are merged. Tools such as MkDocs, Docusaurus, GitHub Pages, or GitBook can provide navigation and search without forcing clients to use the repository directly. Show the owner, last-updated date, scope, and version on each page. Keep client-safe operational material separate from internal notes, use pull requests for review, and publish immutable releases or snapshots when an audit or handoff requires them.
That approach fits our engineering workflow, but the missing pieces for us are page-level permissions and comments on the published version. Clients do not want to open a separate issue for every question.
The audience split makes sense. Our clients tend to comment directly on the rendered pages, though, so we would need a portal that supports discussion while still syncing from the repository.