| I don't see a comment here for MkDocs, so I'll mention it. It was started as a pet project for development knowledge, specifically migrating to local Docker-powered development environments. Initially that was all it had: the "how to set up the Dockers" page and a couple of other tidbits. Over a period of time - years, frankly - it has grown into something a bit more useful, although still woefully short of where I would like it to be. A few things have happened though: * The first principle was: if I find something I have to "re-discover", document it * The more it grows, the more useful it becomes. It's quite pleasing to be able to respond to a Slack message with "read this and tell me if you still have any questions" * It's still slow going, but after some departures ourselves, we've seen a bit more interest in adding and codifying the "tribal knowledge" The best things I like about it? * It's statically hostable: GitLab/GitHub Pages, or if you need to wrangle it, `scp`/`ftp` it from a CI pipeline with a private Apache/NGINX deployment * It's Markdown text embedded in the repository: you can grep it, or search it from VSCode/Sublime/any-IDE-of-choice * It's Markdown text embedded in the repository: there's no way I can think of to make it easier for devs to contribute and maintain it than making it part of the same commit, the same MR, the same CI pipeline * It's Python. Every Linux/OS X machine has python, so there's a minimal barrier to entry for previewing locally * A bucket-load of plugins: Mermaid, PlantUML, SVG embeds, and more: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins * The "Material for MkDocs" theme: https://squidfunk.github.io/mkdocs-material/ Nothing stops it becoming just as much of a mess as Confluence, but there's something slightly ineffable about being able to work with your docs as if they were code: refactor them! Reorganise, dedupe, and take MRs to fix stale articles/mistakes. Other commenters have mentioned incentivising the docs, but I would finally add that someone, somewhere should take a principled stand around the organisation of the docs (and of course, give them space to fail, and experiment, and try again). Broken links are better than no links in the first place, since search is pretty accessible. I was originally inspired by the documentation structure outlined at https://documentation.divio.com/ - although our organisation has evolved away from this into higher-level topics with subsections similar - but not identical - to the original idea. Edit: as for the comment about Confluence, this is one of my favourite bits. You don't need "buy-in" for this, there's no subscription plan you need to approve. If there's a concern around "split-brain" docs, I've used a guiding principle to defuse those conversations: "Do these docs make sense if you don't have a local checkout of the repository?" If the docs aren't related to the code repository - RCAs, business requirements, org charts, HR procedures - leave them in Confluence. If they are related to the repository - coding standards, test coverage generators, docker/unit test commands, migration seed data - then what's the value-add for them being in Confluence? Your CEO isn't going to read them. Marketing don't need them. Put them in the codebase, and reduce the signal-to-noise in Confluence for the rest of the business. |
People have mentioned this in other comments but it's worth repeating that this habit is the true key. Make docs part of your core workflow. The other great things is that you're making them aware of the docs site (when they see the link I bet some have said "wow I didn't know we had this!") and you're specifically asking for feedback on where the doc is lacking.