Documentation for clients
Hi! My name is Alexander Machulin, I’m a co-founder of Gramax and a co-owner of ics-it.
We develop analytical systems for Pharma and FMCG manufacturers. Recently, our clients have increasingly requested that we write and store project documentation within their own systems: Confluence, ServiceNow, etc. However, our documentation workflow is based on our own system using the Docs as Code approach. Therefore, maintaining documentation within a client’s system creates an additional obstacle to our standard workflow.
In this article, I’ll cover:
Why clients want to store documentation in their own infrastructure.
What challenges this creates for development companies.
How to find a solution that keeps everyone satisfied.
Why clients insist on this
Security. Storing data within the client’s infrastructure provides an additional level of security, as companies often follow strict standards.
Fast access to data. Local storage improves access speed and reduces dependency on external networks and servers. It also allows the client’s employees to use a single account for authentication across systems, including documentation.
Confidentiality. Commercial or sensitive information should only be accessible to certain individuals. This is easiest to achieve when the company has full control over data storage.
Challenges for us as a development company
Authentication. The login and authentication process is usually more complex. When the team works on projects for multiple clients, they constantly have to switch between accounts.
Access restrictions. It’s hard to onboard new team members because creating an account in the client’s infrastructure can take from several weeks to several months.
Tool diversity. We aim for a unified development process and consistent toolset. If we start writing documentation in client systems, unification is lost. It becomes impossible to store and version documentation alongside code.
Solution: distributed storage via Git
Git uses a distributed version control system, meaning each developer works with their own local copy of the repository. This local copy contains the full history of changes, allowing work with Git even without constant access to the internet or a central server. If one of the remote repositories is lost or corrupted, any other repository can be used to restore the entire history.
Main principles:
Commits. When someone is ready to save a set of changes, they create a “commit.” This commit records what was changed, by whom, and when.
Push and Pull. To share changes or receive updates, developers use
push(to send commits to a remote repository) andpull(to receive commits from a remote repository).Conflict resolution. If two people edit the same file simultaneously, Git highlights the conflicting sections and asks for manual resolution.
How to apply this to our case
Deploy a Git repository for documentation within the client’s infrastructure.
Set up Git mirroring with the developer company’s repository.
Users and service providers can work in IDEs with Markdown or use WYSIWYG editors for more convenience.
The outcome
The client can review documentation changes and make their own edits to the knowledge base. They can also configure access restrictions so that only specific participants can edit or view documents.
The confidentiality issue isn’t completely eliminated, since the development company can still grant access to anyone. However, that’s already the case today — documentation is stored only with the provider. With this setup, it will be stored both on the client and provider sides.