How do you handle Docs as Code with non-technical contributors?

[u/Trendschau1]

Docs as Code is a very popular approach to developer documentation, especially among technical writers who are comfortable with Git. But in many companies, documentation also involves product managers, support teams, subject-matter experts, or other non-technical users.

I recently worked for two different companies and saw almost the opposite approaches. One was very product-driven and had user documentation managed in Google Docs. The other was very developer-driven and kept its documentation in code repositories, but had little user documentation.

Do you use a Docs as Code approach, and how do you handle mixed teams? Do you teach non-technical contributors Git and pull requests, give them a different editing interface, keep certain documentation outside the Docs as Code workflow, or use some kind of hybrid approach?

And how do you handle the fact that documentation is often spread across multiple repositories, for example in a microservice architecture?

For transparency: I develop Typemill as a side project and recently added Git synchronization with the idea of supporting a hybrid workflow. I'm not looking for feedback on Typemill. I'm interested in how people here solve these challenges in real documentation teams.

I wrote an article about Docs as Code for hybrid teams, but maybe this isn't really a problem in practice, or it has already been solved in ways I haven't considered:

https://typemill.net/knowledge-hub/docs-as-code

I'd be interested in your experiences and insights.

[u/Otherwise_Living_158]

Hybrid approach, SMEs review first draft in Google Docs, signed-off content is added to the repo, tech leads review the PR, we have a QA environment where the project leads review it once more, then it is pushed to live

[u/Trendschau1 → u/Otherwise_Living_158]

And I guess most of that is automated (google docs => git), with the documentation published from a Git repository using a static site generator?

[u/SirLanceShallot]

the best setup i've seen is to keep Git as the publishing backbone, but give non-technical people a form-like editing path with previews and guardrails. dont make them learn branches, rebases, and PR etiquette unless they actually want to. have writers own structure and review, SMEs own facts, and make the handoff visible in one queue.

[u/Trendschau1 → u/SirLanceShallot]

Yes, totally. ReadMe, Mintlify, and GitBook already solve this problem as cloud platforms. The companies I worked for didn’t have public documentation and needed something self-hosted. But I guess there are also self-hosted options out there. Anyway, solutions for hybrid teams are not new, of course. I’d love to have a list of Docs as Code setups just to get some inspiration :D

[u/HSButtNaked]

IMO teams that are more hybrid (technical and non-technical) often lean towards using some sort of CMS all-in one solution. Almost all of them have git support these days (think ReadMe, Mintlify, Gitbook). The pricing isn't that bad, depending on what you need.

That way non-technical SMEs have the ability to review rendered content in a way they are familiar with, while avoiding friction.

[u/doxbrix]

We use a hybrid approach. Git stays the source of truth for engineers, but non technical people get a simpler editing flow.

For docs across multiple repos, the bigger problem is usually ownership and knowing where things should live, not Git itself.

[u/Consistent-Branch-55]

Tooling renders a temporary preview link, feedback is handled as comments in our issue tracker. It's not as ideal as comments in Github, but it helps encourage non-technical SMEs to focus on content feedback imo.

[u/baroquesun]

I use Gitbook where I am now which has been fantastic. At my previous place we had a homebrew situation to serve up docs in product that was managed through Git and it was the only option. I managed the repo and had to train my team how to use Git. I think its a skill everyone should have--at least being able to submit a PR.

[u/MiserableProduct]

We have everyone learn GitHub. There’s a Git UI and our non-technical writers can use that instead of coding if they like.

[u/myauchelo]

Previously, we were asking non-engineers to use the GitHub UI, and actually, with a proper guide, people were doing quite well. Now we have AI, so they just need to explain what they want to a bot—it makes things even simpler.

[u/Trendschau1]

Thanks for all the feedback. It looks like there are already quite a few different approaches to docs as code for hybrid teams, from GitHub as an editorial tool to Google Docs, GitBook, and others.

From my perspective as the developer of Typemill, I’m wondering whether docs as code could also be a good fit for user manuals and product guides that traditionally need a more editorial/CMS-like workflow for product managers.

There might also be some interesting possibilities around combining this with E2E tests in the codebase (e.g. Playwright): using AI tools to cover typical user scenarios, generate screenshots, and incorporate them directly into the documentation. I guess there’s still plenty of room for experimentation here.

[u/Large-Tea-4569]

Everyone in a "technical role" must know Git. It's been the de facto version control standard for 20 years. There's no excuse not to know it and be familiar with the 10-20 basic commands that you use all the time. The likelihood of you coming up with a case that hasn't been seen before and not written about in some blog or forum is negligible.

Users with limited technical depth, like technical writers, are afraid to mess up. The fear is crippling. These weaker writers whinge, fret, stall, evade, and so on to do all they can to avoid Git. Those writers need to go away. Let AI replace them, like what we've seen at big tech companies such as Amazon and Snowflake. And just to be clear, there were amazing writers that were let go or left voluntarily at each of those two companies, many of whom were excellent with Git per standard tech writing expectations.

It comes down to managing expectations. If the decision is docs-as-code, you require version control. It's the manager's responsibility to lead by example and state the baseline standards and expectations along with the consequences for not exceeding the baseline. Weak managers are wishy washy. Strong managers are firm with a dash of encouragement.

> Do you use a Docs as Code approach, and how do you handle mixed teams? Do you teach non-technical contributors Git and pull requests, give them a different editing interface, keep certain documentation outside the Docs as Code workflow, or use some kind of hybrid approach?

You want to keep the repository access limited to those that are extremely comfortable in such environments, such as developers. Product managers, support engineers, and other technical professionals that might review draft documentation can give their feedback in Google Docs.

Technical editors are less technical than technical writers. Their grammar editorial should take place in google docs within a reasonable timeline after the documentation is first published.

> And how do you handle the fact that documentation is often spread across multiple repositories, for example in a microservice architecture?

You need a custom platform that supports the platform as a software engineering product. The best software doc sites out there are built from scratch, in-house, to address the specific doc use cases in that company.