HACKER Q&A
📣 klkvsk

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?


  👤 amitu Accepted Answer ✓
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.


👤 __d
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.


👤 mimixco
We make a tool for exactly this[0].

[0] http://miki.mimix.io


👤 mraza007
Hey you should checkout mdbook it’s a great tool for writing technical documentation

👤 skydhash
I started using Dropbox paper for these. JIC I need to collaborate on one.