I think this misses the biggest need (which one might not consider if coming from Confluence):
- consolidation of wiki together with your code's READMEs and generated docs (e.g. sphinx, mkdocs, swagger, etc., anything that outputs documentation from your codebase)
Note on the "integrated diagram editor", this brings up another feature (though less critical than above):
- by standardizing on a docs-as-code abstraction like mermaid or kroki, you can then leverage (a) diffable diagrams as code, and (b) quite a few relevant OSS editors.
See VSCode extensions for a few different implementations, but that said, if you pick mermaid, then the same diagrams work in the wiki tool as on GitHub, as well as local-first open content format tools like Foam, Dendron, or Obsidian.md, which is nice.
The diagrams as code is not a one size fit all. I'd use mermaid for some technical things, but it's failing for communication/presentation purposes. You need to have the ability for arbitrary placement, annotations, flow. Mermaid is all fun until you want to connect two previously distant boxes and everything explodes - for long-term documentation purposes it may not even matter, but if I'm about to show it to anyone, I'm going to Excalidraw.
I work on the Mermaid Chart product team and your comment here is extremely relevant to a big project I'm working on that will solve a lot of the problems you mentioned! Would you be willing to tell me more and give your thoughts on our plan for solutions?
If you're open to it, please send me an email at dominic@mermaidchart.com!
I'd be happy to exchange an Amazon gift card for your time too!
- consolidation of wiki together with your code's READMEs and generated docs (e.g. sphinx, mkdocs, swagger, etc., anything that outputs documentation from your codebase)
Note on the "integrated diagram editor", this brings up another feature (though less critical than above):
- by standardizing on a docs-as-code abstraction like mermaid or kroki, you can then leverage (a) diffable diagrams as code, and (b) quite a few relevant OSS editors.
See VSCode extensions for a few different implementations, but that said, if you pick mermaid, then the same diagrams work in the wiki tool as on GitHub, as well as local-first open content format tools like Foam, Dendron, or Obsidian.md, which is nice.