I generally like using a combination of the following:
* Wikis for general information, environment setups that are not project specific, etc.
* Repositories to host code and system specific information, usually in Markdown documents.
* Google Docs or Microsoft 365 for working documents that need to be collaborated on, commented on, and shared without the rigmarole of pull requests and the more static nature of wikis.
* Slack is for ephemeral information. If it contains documentation, specification, FAQ, debug steps, process explanations, etc., those should be captured and moved to the appropriate documentation location.
The one thing I really struggle with are diagrams. Cloud-based diagram tools like Visio and Lucidchart are great, but they are tough to save in a good location outside of the cloud environment. It requires exported the file and/or a PDF export. Then, these fit rather poorly into source-code control. There is the concept of "diagrams as code", but all of those systems are generally terrible at layout. There really is no good solution, as there are major trade-offs to both.
https://app.diagrams.net (formerly known as draw.io) can be exported and imported as an XML. At one company we just exported the diagram as a png/jpg and as an xml, committed both to the wiki repo or source repo under the docs/ directory. Then next time, just import the diagram xml into the app and repeat. I think that's a good enough approach if diagrams are useful but updated infrequently.
I've started using a similar approach, minus the png/jpg, for my personal markdown based wiki.git, saving the xml as a file that I can reimport in the future. I usually do this for prototyping or grokking some new system.
I definitely have made decent use of Mermaid diagrams in GitHub. But Mermaid diagrams are hard to layout, and there is only one experimental layout that's good for automatically generated diagrams. It's nice, but it's not quite there. I have tended to bounce between Mermaid and Visio.
I'm generally not a fan of exporting and importing diagrams constantly. One thing that is nice is that Confluence can support plugins for diagrams, which is okay-ish.
diagram.net also has an electron app. I realize I can just have it open the xml in the git repo directly, no separate tedious import step that way. That was quite nice and a happy accident that I discovered.
Comments
I generally like using a combination of the following:
* Wikis for general information, environment setups that are not project specific, etc.
* Repositories to host code and system specific information, usually in Markdown documents.
* Google Docs or Microsoft 365 for working documents that need to be collaborated on, commented on, and shared without the rigmarole of pull requests and the more static nature of wikis.
* Slack is for ephemeral information. If it contains documentation, specification, FAQ, debug steps, process explanations, etc., those should be captured and moved to the appropriate documentation location.
The one thing I really struggle with are diagrams. Cloud-based diagram tools like Visio and Lucidchart are great, but they are tough to save in a good location outside of the cloud environment. It requires exported the file and/or a PDF export. Then, these fit rather poorly into source-code control. There is the concept of "diagrams as code", but all of those systems are generally terrible at layout. There really is no good solution, as there are major trade-offs to both.
https://app.diagrams.net (formerly known as draw.io) can be exported and imported as an XML. At one company we just exported the diagram as a png/jpg and as an xml, committed both to the wiki repo or source repo under the docs/ directory. Then next time, just import the diagram xml into the app and repeat. I think that's a good enough approach if diagrams are useful but updated infrequently.
I've started using a similar approach, minus the png/jpg, for my personal markdown based wiki.git, saving the xml as a file that I can reimport in the future. I usually do this for prototyping or grokking some new system.
edit: just remembed, github also supports mermaid diagrams, https://docs.github.com/en/get-started/writing-on-github/wor...
I definitely have made decent use of Mermaid diagrams in GitHub. But Mermaid diagrams are hard to layout, and there is only one experimental layout that's good for automatically generated diagrams. It's nice, but it's not quite there. I have tended to bounce between Mermaid and Visio.
I'm generally not a fan of exporting and importing diagrams constantly. One thing that is nice is that Confluence can support plugins for diagrams, which is okay-ish.
diagram.net also has an electron app. I realize I can just have it open the xml in the git repo directly, no separate tedious import step that way. That was quite nice and a happy accident that I discovered.