I have a few tools I live by when it comes to documentation/diagramming. I like to keep things very simple. Plaintext wherever possible, change management everywhere.
I write docs in GitHub-flavored Markdown and put them in a Git repo for change tracking/collaboration.
I usually make a set of docs a dedicated Obsidian Vault for easy editing.
I use mdBook to create PDFs and searchable webpages from those docs. Bonus points for Pages integration with the Git host.
I use Mermaid for diagramming when I can, and Excalidraw when I can’t.
That’s basically it for me. But what do you love in the realm of documentation?
Related to obsidian but I really liked the addition of canvas / json canvas in general. Helps me relate notes for mind mapping and in general just gathering related stuff. I think it could be used for diagramming too, but I don’t really use it like that. I find the relation mapping helpful for learning, and the gathering scratch pad useful since you can embed all sorts of web content
I also loooove Canvas and use it frequently for my own private notes. I don’t feel like I can get a larger team to adopt it as a standard, though. Mermaid does seem to have enough juice to get that done.
I’m obsessed with Obsidian. The markdown formatting, the canvas module for diagrams/mind maps, the bases feature for tagging notes and making a database. It’s all chef’s kiss
Also, the plugin to export to PDF helps make generating documents from a report much easier.
Obsidian is my go-to for note-taking, research, task list, or general scratchpad stuff. I keep the vault in my OneDrive so it will sync between my desktop and laptop. It’s all very disorganized though and I get the impression I’m not using it right.
When I need to make readable documentation out of it I will move it to an on-prem hosted Bookstack and edit it further from there with pictures, diagrams, etc as required.
I used to swear by LibreOffice Draw for Network/infrastructure diagrams but I’ve falled out of love with it in recent years because you have to install the whole LibreOffice suite now and all I want is Draw, and they’ve made some UI and functional changes that I don’t like. I haven’t really found a dedicated replacement yet and use draw.io because it’s easy, but I am looking for a replacement.
For a daily driver I’ve used Notepad++ for many years. It’s a bit of a Swiss Army Knife for me. I’ve some macros for doing things like making a URL un/safe or converting a carriage return infested list to a comma separated list and the other way. I also use plugins to beautify things like JSON and JavaScript files.
For more permanent storage of text like things I’ve used Standard Note since before Proton acquired them. Wanted a place to store sensitive things that was E2E, supported a variety of formatting including markup, and was easy to use on any device including mobile.
For more complex things, and OSINT especially, I use Obsidian Canvas. For example, earlier this year it was necessary to get a better handle on this (as you likely know):
However, I have concerns with Obsidian as a platform. Since Canvas is by far my most used feature of Obsidian, would Mermaid be a suitable replacement? Are there any others I can look at as well?
Of course work wants me to put everything into SharePoint Wikis. That’s fine. I’m not in love with it, but I don’t hate it. And at least the company has a “permanent” repository that is at least subject to DLP - maybe. (You can always tell a Microsoft product because it was obviously designed by engineers and they never have to use it as a daily. Don’t get me started on Attack Simulator…)
There is also still a “need” to dust off Visio every once in a while. That kind of goes hand in hand with the SharePoint Wiki requirement. What will be, will be.
I use typst a lot for pretty everything which should be documented, for the following reasons:
It generates modern PDF on the fly (the HTML-target is in public beta)
It’s a modern and lightweight LaTeX-alternative with batteries included (excellent utf8/font support, drawing, citations) and an easy to access package and template universe.
It includes it’s own deterministic scripting language which allows to load data from several sources (csv, jsaon, xml, yaml and more) and use it to generate any kind of visualization you can imagine.
It’s open source (and therefore trustworthy) and is easily backed by any kind of VCS.
To give one example i use it for hardware documentation and created some small scripts to let me maintain the docs as versioned yaml like this:
I really like Typst as well! I’ve used it for my resume and a few other things. I haven’t used it for documentation because I don’t think I’d get adoption from others at this point. But it’s a lovely tool and I am trying to use it in lieu of LaTeX whenever that might come up.
