Making docs accessible to everyone in your company

[KevinFabre-ods]

Hi,

Keeping documentation locked inside the codebase makes it tough for non-technical stakeholders (like PMs, designers, and domain experts) to read or contribute, since they don't work with Git or IDEs.

But they really need this information when they're working on specs and interfaces.
Is it worth finding a way to get these docs into their hands? How do you handle this in your organization?

[starkmarkus]

Yes, I think so. The cleanest setup is usually to keep the source docs in git, then publish them somewhere the rest of the company can actually consume them.

That way engineers still own the editable source, while PMs, designers, and domain people get a surface that does not require Git or an IDE.

So I would not move the truth out of the repo, but I would definitely add a friendlier layer on top of it.

[Sampath7890]

starkmarkus is right on the separation of concerns — keep git as the source of truth. The "friendlier layer" part is where it gets interesting depending on your stack:
If you want zero setup: GitHub/GitLab both render markdown natively and have a web editor — non-technical people can read and even edit directly in the browser without touching git or an IDE. Pair this with branch protection and a PR review step so engineers still control what merges.
If you want a proper doc site: Tools like MkDocs (with Material theme), Docusaurus, or GitBook can sync straight from your repo and publish a clean, searchable site that PMs and designers can bookmark and use like any internal wiki. CI/CD handles the publish on every merge — no manual step.
If your company already uses Notion/Confluence: There are sync tools (like Notion's GitHub integration or notion-to-md workflows) that can mirror docs from the repo into the tool your non-technical folks already live in.
The pattern that works best in my experience: docs-as-code in git → auto-publish to a clean URL on merge → share that URL with stakeholders. They never need to know git exists.

[MichaelRWolf]

@starkmarkus,

Sounds like you've got the classic problem of "Mohammed is not at the mountain", which can be solved:

• Bring the mountain to Mohammed (i.e. create a system to recreate docs for non-techies)
• Bring Mohammed to the mountain (i.e. bring the non-techies into a collaborative process)

In other words, if your problem is

Non-technical folks do not know how to read the technical documentation

There are at least 2 ways to resolve this gap

• Keep non-techies with familiar translation/access to the git-as-source-of-truth
• Teach non-techies to use git

The former involves creating (and maintaining) a separate data flow for viewing (and also reviewing, and iterating).
The later involves education.

Personally, I'd rather do the later. I'd do it as a pairing (or mobbing) exercise because that has quicker feedback cycles between the two different parties, and allows for a better shared understanding. This is a social/human answer that solves a more fundamental problem than your initial post presents. It encourages a coming-together spirit instead of reinforcing a stay-apart mentality.

If the non-technical folks say that they don't understand the documentation, that's an opportunity to refine it in the source-of-truth. Providing a separate source-of-translated-forked-truth creates a cascade of unintended consequences that create waste on non-value-add activities (i.e. merging "their" refinements into "our" way -- and all the us/them-ness implied by that forking).

It may feel awkward, but if your technical staff cannot communicate with your non-technical staff, that is not a problem that can be solved by more technology. The term "non-technical" often hints at an us/them problem masquerading as something else.

[airtonix]

An option i use often is to make a confluence space that gets synced by a github action on push to master with some tool like:

• https://github.com/hunyadi/md2conf
• https://github.com/markdown-confluence/markdown-confluence

Another option is if it's a private org with enterprise access (or is teams enough) and everyone has github access, then just point them at the github link for the md files.

Github will render the md nicely for them.

honestly, everyone needs to learn how to read/write markdown. it's been 20 years now.

[jfbloom22]

Like others have mentioned. You can sync to more user friendly platforms. I am having some success with Outline Wiki and MCP. Self hosted and free version of Notion.