| I totally feel you. When I joined my current department it was pretty much the same. The engineering team transitioned from Jira to another Jira to a company specific PLM solution, and all formatting of existing docs in the process. When I was on boarding I had to talk to so many people to get a brief understanding on all processes, tools, etl, deployment methods, APIs and so on. I made some notes on my way and felt the need to share them with the others because everyone was struggling with that topic. The only one source of truth was a 80 page pdf file maintained by one architect. The solution I went for was markdown docs in Gitlab plus pretty HTML pages generated by mkdocs. The mkdocs material theme is really nice. This has been so successful that we have over 3000 commits after 18 months and over 1000 merge requests to the docs. The main benefits are: * easy to use, markdown is easier that rst. Especially for non dev people.
* wysiwyg editor in the gitlab webide. Most changes are made in gitlab itself. From change to merge request in 4 clicks without the need to understand git.
* it is just text. In the beginning many people said that they wont contribute anything because the next tool migration will loose everything. But now the docs are in markdown and easily portable.
* gitlab ci automatically lints the changes on every commit so that mkdocs doesn't break because of malformed syntax and broken links. You can only merge to master when the pipeline is green.
* possibility to peer review. We have regulatory requirements for 4 eye principle of some parts, with merge requests we can easily approve and discuss merge requests. The biggest problem is in my opinion to get our very non technical management onboard. They basically ignore to comment on merge requests or discuss changes in gitlab because it's a developers tool. Therefore they stick to stupid mailing lists and are left out in the process. But everyone from dev to ops, tst, sec is really happy. It would be nice to have a technical writer maintaining and cleaning up the docs, but there is no budget for that, so it's will probably stay my side job. |