[rglullis]

> it's easy for them to get out of sync with the actual system, and this can require too much coordination.

I don't follow. How much do you have of your non-techies updating your knowledge base and how do they get to know if what they are updating is "in sync" with the system if the changes are making are orthogonal with the functionality?

It seems your case is mostly about documentation of the technical product, specs, requirements. Yeah, this can go to your version control, and I would bet that you could find a Confluence plugin that would generate the documentation from version control and sync with the rest of your Confluence pages if you wanted.

But I really, really doubt your method can scale beyond the IT side of any middle-to-large organization. The moment you ask Business/Customer Support people to actually go look at anything like Gitlab/Github's interface is the moment you lose 90% percent of buy-in from both non-techies and management at any company that is not absolutely dominated by Software Engineers.

Requiring integration with version control is a convenience for engineers, but it is so far from the tooling from those that live on Excel sheets that you might as well ask them to never touch the documentation side.

[phixiuz]

Granted, we're still a fairly small organization (+- 10), but our business and customer support people are also using Gitlab to maintain our knowledge base: once you properly guide them on how to use it, they are definitely able to handle this. All the actual git operations happen under the hood of the web interface. So we do strongly believe this is scalable, at least for our use case. This has been working fine in fact for long-lived information across multiple departments (not only technical docs, but also e.g. sales/customer support guidelines). For short-lived information we use Google Docs (e.g. meeting summaries).

[rglullis]

> All the actual git operations happen under the hood of the web interface.

The interface is not so much what I object to it. It is the fact that you mentioned "being in sync with the system", which I assume you mean "being in sync with the codebase/released code".

There are plenty of things that happen on any company that have no relation to the code, and you are telling me that you have people on the non-tech side which are expected to understand on what branch of the repo their contributation with documentation is supposed to go? Are their milestones and projects always dependent on the codebase? This is the part that makes no sense to me.

> So we do strongly believe this is scalable, at least for our use case.

I am not telling you that what you are doing is wrong, but scalable it is not. Beware the usage of the Royal We when you say "our use case": are you speaking on behalf on the whole company or just the tech team? This is key difference that you will learn as the organization grows.

[phixiuz]

> There are plenty of things that happen on any company that have no relation to the code

Some more details about our approach that addresses your concerns: (1) for content changes unrelated to code, anyone (tech or non-tech) is able to open a new MR, and after approval it automatically gets merged into our reference branch and deployed (2) for content changes related to new (unreleased) code, the input from non-tech people (e.g. customer support) is usually requested via an already existing merge request (via a mention), they can then add their input/content via gitlab's interface straight into the markdown files (and see a live preview), this way we ensure this sort of content goes live along with the code and requires no extra coordination

> I am not telling you that what you are doing is wrong, but scalable it is not.

I hope with my clarification above it makes more sense.

> when you say "our use case": are you speaking on behalf on the whole company or just the tech team?

On behalf of the whole company: we have a single product/platform that is continuously increasing in complexity, and it really helps to have a single process in order to maintain a knowledge base that covers as many aspects as possible (tech and non-tech). We believe this approach will also minimize replication of content across departments (facilitates cross-linking), and we're intending to also create an aggregated search (next to the individual search) across all categories of our knowledge base (product/engineering/support/sales/..), in order to more easily retrieve relevant content.

> Beware the usage of the Royal We when you say "our use case"

I am not implying this is set in stone, we (as a whole team) thought long about this flow, and for now it seems to work great, and I hope (responsible for maintaining this technically) that it scales up to some point far enough in the future. I'd say we were mostly inspired by Gitlab, they seem to adopt a similar approach, and that seems to be scaling quite okay over there :). We've noticed ourselves that the general "documentation mindset" has definitely grown among the team because of this specific process and the ease of adding content, updating content and retrieving content.

[rglullis]

So essentially you are saying that the tech side still works as gatekeepers of the documentation - need to approve MR's, requesting input via mentions - which is fine until the organization is skewed to the tech side.

As for Gitlab, their work processes are interesting, but I assume that most of the non-technical work there goes to issue tracker and the wiki? I am failing to see where there a strong connection to the code repository is required there.

[phixiuz]

Afaik, Gitlab's wiki/knowledge base is also a separate repository and content is added/updated via regular MR flow. Our knowledge base is still part of the main codebase due to practical reasons (CI/CD related), but we'll eventually also migrate this to a separate repository as well, to avoid the unintentional gatekeeper aspect as you mention ;).