Hey documentation folks. I'd love to hear about your experience in driving documentation culture forward at your company. A recent survey in ours revealed that everyone thinks our docs suck (if they exist). I want to address that, but it's a large, amorphous problem.

We completely rebuilt our documentation into a centrally managed site where documentation is automatically sourced from the repos. In my opinion the main problem with most documentation platforms is that it requires developers to maintain two sources of documentation: the repo documentation and high-level documentation around certain functionality of a system. by building an automatically generated and compiled documentation site that comes straight from the source, the adoption of documentation skyrocketed with our company

I would love to learn more. Do you have anything written about that? Links to tools?

I would also like to learn more about the setup 🙂

We built the whole system ourselves so the only open source tool that we use is Hugo to deploy the site and so we can use a lot of the features that come out of the box with a Hugo site. We are working on an article that goes into detail about how we did it. But the simple version is, we added a portion to our manifest that lives in each repo so that service and library owners could specify how they wanted their dogs to show up if they wanted something custom and then wrote a GitHub action that repos could add to their workflows that would find all documentation and package it up and send it to a service that would unpackage it and put it in the correct spot in our repo that contained our Hugo site content. And then that repo has a GitHub action that deploys our Hugo site.

@Jon Stevens What lead you from "we don't have good/enough docs?" to "centrally managed documentation store"?

We knew for a while that we didn't have great documentation and we had gone through a couple of different products for documentation and it actually came from the fact that we loved using Hugo to deploy our engineering blog. We saw that we would be able to source all documentation from the source of Truth and populate one Central repo that used Hugo to deploy so that we could get rid of this secondary and always out of date documentation system. We always knew we had a problem with it, but it wasn't until we saw how easy it would be to do by using Hugo and just committing content to specific places in that Central repo that we decided we would move forward with it.

Hi! I'm a little late to the discussion because I just found out about this channel, but I'm researching tools for improving our documentation's organization and discoverability, and came across Docusaurus, it seems really interesting but I've not used it yet