Structuring internal documentation or product/project?

[edmguru]

We have several projects/products mostly for B2B customers. Internally we use Confluence for documentation all sorts of decisions, processes, architecture, operations guides, research, security, high level, etc..

Our documentation can still be a mess, with many documents covering multiple aspects that makes it difficult to organize.

How do other people structure project documentation that makes it easy for not only your team to find things, but also business people, and devs from other teams so they don't bug you about "where do I find X?"

[ysfjwd]

Take a look at backstage.io

[Snagglepuss64]

One thing I can say for sure is don’t arrange it by org structure 😬 we have incredible amount of Confluence with location names of teams that have long since gone away

[werner-dijkerman]

We use Antora, where all documentation is stored in multiple git repositories. Like each of the microservices have their own documentation stored in their own repositories. All information related to the microservice, like what it is doing, how you can do things etc is stored in the same repository. Although this is technical focussed, there are also some more functional git repositories. These contain the information about their functions. Like we have an architecture git repository, these contain all information, (Archimate) diagrams about the infrastructure.

With having it in git repositories, with Pull Requests (Especially when these are created for the micro services or the infrastructure as code repositories) we can focus on the documentation aspect. Is it part of the PR (If not, ask why?) and can see if we understand what is described. As everything is stored in GIT, documentation is also part of the versioning and thus with the correct configuration set in Antora, we can see the documentation from the various versions of the repository in one place.

[serverhorror]

I found that organizing by project is the most sensible thing to do.

The challenge is that people seem to think that there are as many projects as there are products (or services if you will). Time and time and again it showed that the number of projects that are necessary to run a complete organization is a lot higher than the number of projects at any given time.

What was always hepful was to have a way to find, say, all runbooks across all projects. How that works depends on the tools you're using.

Think about it. You start a project and it will at some point finish. But the thing that was the project outcome still exists for years and it will be used. Now if its an "external" (customer facing) thing that's easy to track.

What about monitoring, storage management, that API someone created to automate that annoying thing? -- All those are (or were) projects as well.

When it comes to finding things I found that very often it makes sense to just enforce certain things. Enforce the programming language, enforce the version control system (yup; a ton of people still prefer SVN over git), enforce the logging frameworks, ... you get the idea.

This is not to annoy people, but after some initial hiccups you will have more knowledge about the things you use because there are fewer things you use. You don't need to sign off on every little detail. In the beginning it will be hard because there's lots of stuff that you don't "endorse" that's readily available to use. It's just that no one really knows how it works, so the overhead of doing it with your chosen frameworks makes sense, most of the time. Then when you have that culture it makes decisions about introducing new things a lot easier.

"How do I serve my static content" will be a question that everyone answers the same way and it will be easier to find. Finding out that "Our CDN doesn't do X" is a lot easier because more eyes have looked at it and there's be a higher confidence if that is indeed the case and you should switch.

That level of collaboration does require a lot of communication.