Ask HN: What tools do you use to write techinal documents
In such common cases as
- writing specifications for new software
- writing documentation for a client on how to use software and/or how it architechured internally
- writing an API reference with usage examples
I've seen most of times people use just a plain Google Documents/Word file and share it. Some write markdown files and convert to HTML/PDF. Nowadays many start to use Notion too.
But I feel like those tools are not featured enough. Like, what good technical docs can be without some squares and arrows?
I want to be able to:
- split my documentation into tree-like structure of sections/pages, add linking between them and even include blocks from one page to another
- add and edit right in-place: diagrams, mindmaps and other schemes (PlantUML is my loved choice, but drag-n-dropping mouse-clicking editor if fine too), tables and charts (with referencing external sources like CSV), math notation (LaTeX)
- connect it somehow to code repository, so I can reference classes, function names and signatures, code parts -- main reason here is when I refactor the code, documentation is updated on commit, and therefore always kept is sync.
- all done with WYSIWIG in web, so I can easily share work in progress with my (maybe less technical) coworkers, so they can edit too or leave comments.
For me, there is AsciiDoc, which is less-known alternative to markdown, having a lots of features out of the box (plantuml and other embedding, better tables, etc). But hard to collaborate - you can only preview it locally; syncing changes only via storing it in git; other writers should be familiar with syntax too. And there is still Notion, which is very easy to collaborate on, but not extendable, so I need to copy-paste my diagrams as pictures from somewhere else.
I still struggle to find something like a mix of those two, and I wonder if I'm alone on this. Is this because my use-case is rare? Or do others too feel a lack of such tool?
What do you use? I am working on fifthtry.com to solve exactly this problem. We organise stuff in tree. Eg you can see my person blog hosted on it: www.fifthtry.com/amitu/. We are working integrating with diagram tools. Regarding sync: we connect with github and block pull request till it is documented and approved on fifthtry. Would love to demo it to you if interested, email in my profile. In my experience, companies mostly use Confluence, Atlassian's Wiki, for this sort of thing. It has a bunch of plugins for diagrams, from Visio-like stuff, to more Photoshop-style. The problem is that it's simply awful to use. I completely agree! I'd love if you check out our competitor; it's a hosted version of Wiki.js that's a lot easier to use than Confluence. It also supports direct diagramming in SVG (Draw.io built-in). http://miki.mimix.io We make a tool for exactly this[0]. Hey you should checkout mdbook it’s a great tool for writing technical documentation I started using Dropbox paper for these. JIC I need to collaborate on one.