App for making a hypertext (self-contained) software manual

Posted by Glen Coulthard
Jun 18, 2020 at 03:39 PM

I also write software documentation, and moved away from Word a few years ago to markdown and then, more recently, to asciidoc. If you are comfortable writing in markdown, there are many online tools that you can use to create, collaborate, and publish/deploy your help files (both HTML+PDF). Here are a few of my favourites. (Note that “ssg” stands for static site generator.)

- Typora - https://typora.io/ - for offline writing/notetaking
- HackMD - https://hackmd.io/ - for online writing/notetaking
- MkDocs - https://www.mkdocs.org/ - ssg for documentation sites
- Docusaurus - https://v2.docusaurus.io/ - ssg for docs by Facebook

If you want more control over your content (i.e., images, callouts, tables, admonitions, footnotes, etc.), check out asciidoc:

- Asciidoctor - https://asciidoctor.org/ - documentation publishing toolchain (HTML/PDF)
- Asciidoctor Tutorial - https://www.vogella.com/tutorials/AsciiDoc/article.html

Asciidoctor publishes a “toilet-paper-role-with-toc” webpage and PDF (if that’s what you want); however, I break the content into chapters and then combine them as needed. As an author/writer, I appreciate the added features that Asciidoctor provides, yet it’s as simple as markdown if that’s what you want.

Another benefit of markdown and asciidoc is that text-based source files allow me to use GitHub/GitLab for version control and quick/easy updates and deployments. I’ve even moved my outlining/notetaking away from Evernote to markdown-based Joplin (https://joplinapp.org/).

Hope that proves helpful.
Glen
p.s. Over the past several years, I have been moving my ConnectedText content to markdown, since I don’t ever want to worry about being in a “walled-garden” again. Something to consider with documentation as well!