Forum Posts Feed
App for making a hypertext (self-contained) software manual
< Next Topic | Back to topic list | Previous Topic >
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!
Posted by Andy Brice
Jun 18, 2020 at 07:49 PM
Jeffrey
To clarify, I am only recommending https://www.helpandmanual.com/. The other 2 applications are my products that I use Help & Manual to write the documentation for.
Jeffery Smith wrote:
I do have Windows by way of Parallels, so that isn’t completely off the
>table. I’ll give your suggestions a look. They *sound* promising.
>
>Andy Brice wrote:
>For writing use help documentation for
>>https://www.easydatatransform.com/ and
>https://www.perfecttableplan.com/
>>I use the excellent https://www.helpandmanual.com/. It can output in
>>PDF, CHM, HTML and various other formats. It only runs on Windows.
>Might
>>be worth a look.
Posted by Jeffery Smith
Jun 18, 2020 at 09:06 PM
I did understand that. And it is helpful to see what the finished product looks like. I’m not sure I can justify the price of your recommended product (this manual may be the last piece of paid work I do).
Andy Brice wrote:
Jeffrey
>
>To clarify, I am only recommending https://www.helpandmanual.com/. The
>other 2 applications are my products that I use Help & Manual to write
>the documentation for.
>
>Jeffery Smith wrote:
>I do have Windows by way of Parallels, so that isn’t completely off the
>>table. I’ll give your suggestions a look. They *sound* promising.
>>
>>Andy Brice wrote:
>>For writing use help documentation for
>>>https://www.easydatatransform.com/ and
>>https://www.perfecttableplan.com/
>>>I use the excellent https://www.helpandmanual.com/. It can output in
>>>PDF, CHM, HTML and various other formats. It only runs on Windows.
>>Might
>>>be worth a look.
Posted by Jeffery Smith
Jun 18, 2020 at 09:17 PM
Thanks for the replies. I fiddled around with several things, and I may untimately use what I have used in the past for this sort of project…Filemaker Pro. I even used Nutshell, the distant ancestor of FMPro over 3 decades ago. I make a framework for the title, writing, and any pictures on a template, fill in the information on one screen, and make another layout to print to PDF. But I’m also going to use Adobe Acrobat to create links in the manual that jump to major pages referenced.
Posted by MadaboutDana
Jun 19, 2020 at 09:22 AM
Hey Jeffery,
Before committing to what sounds like a remarkably clunky process (I use and adore FM Pro, but would never use it for a project like the one you’ve described, not least because of the post-editing required), I’d suggest you look at Versatil Markdown in the Mac App Store, which is a very powerful editor (a bit like Typora on steroids). It also exports to PDF, HTML or Web Archive format, which seems to me ideal for something like help files or hypertext notebooks.
It also supports document aliases (transclusion, as I was kindly reminded in a previous post). It’s not well known - not because it’s not actually very easy to use (it is), but perhaps because it comes across first and foremost as a programmer’s tool (it can be).
Which reminds me that it would also be worthwhile exploring Quiver as a possible solution (now that does describe itself as a programmer’s notebook, but is a lovely piece of software, although the author appears, alas, to have given up on developing an iOS version). Quiver (also in the Mac App Store) also has an impressive range of output options, including PDF, HTML, Markdown, JSON and others.
Cheers!
Bill
Jeffery Smith wrote:
Thanks for the replies. I fiddled around with several things, and I may
>untimately use what I have used in the past for this sort of
>project…Filemaker Pro. I even used Nutshell, the distant ancestor of
>FMPro over 3 decades ago. I make a framework for the title, writing, and
>any pictures on a template, fill in the information on one screen, and
>make another layout to print to PDF. But I’m also going to use Adobe
>Acrobat to create links in the manual that jump to major pages
>referenced.