I am in the process of setting up a documentation architecture for a company, and one of the challenges I am facing is how to represent a “document” on said website. To give a bit more context.
Let’s say that we have thee types of repositories containing documentation:
The first type is “meta documentation” that decribes the entire eco system of documentation, what types of documents exist, what purpose they serve, how to read them etc.
The second type is a software component. It contains a mix of documentation and code. The code is the literal implementation, the documentation describes what the component is capable of, and how one should implement / apply the component in the greater context.
The third type is a software system. The software system is a collection of “infrastructure as code” and documentation what the intended use of the system is, and how it has been designed to meet that intended use.
What I want to do is create a website that “centralizes” all of this documentation:
We expect to have to support around a 100 systems, where each system consists of 2 or more software components, of which most components are reused across multiple systems (just configured differently).
when I envision the documentation, my mind goes to something like:
- The default “portal” to the documentation is the meta documentation part. It introduces the reader to our systems, explains how to use the documentation, and helps to guide them to the appropriate system or (generic) component.
- Each system and each component has their own “site”, i.e. when navigating to - for example - a software component, you only see information that is about that component, including the navigation pane entries. Same for the systems
- Cross references are present - a system’s documentation will contain references to the (generic) components it relies on, so people can freely jump around the entire hierachy of systems and components easily.
My question is: how would you suggest building and “merging” all of these documents into a coherent whole, taking into account things like updating a generic component without having to publish everything all the time, and managing cross references between documents in a way that makes it easy to maintain them? I have ideas, but as I have learned in my Hugo journey so far: rarely is my idea the most convenient / maintainable / simple way of achieving my goal.
Feel free to point me towards generic concepts within hugo that could help me, or other resources that can help me learn to deal with complicated documentation eco systems like the one I am describing. Thanks a lot! 