[TriLUG] authoring tools for technical documentation ... ?

Dewey Hylton via TriLUG trilug at trilug.org
Wed Dec 19 07:44:53 EST 2018


I've been writing unix-related technical documentation for the past 15 years in moinmoin (a simple python-driven, file-backed, web-based wiki) for a lot of different reasons. I attach (and scale) screenshots, make heavy use of block quotes (to show example shell sessions), provide syntax-highlighted code snippets, include a TOC, and include links. I work from either a mac or linux (and sometimes a chromebook), directly in firefox, and the result is easily available to essentially any device with a web browser. It works really well, and the wiki syntax is easy and capable.

However, I currently work with (nearly 100% windows) team which expects its documentation to be stored on team drives in google - supposedly so that documents are easy to find/maintain and are easily searchable. Of course moinmoin provides all that, but whatever. 

At first glance, google docs appears to be quite anemic. There may be plugins and such to add to my browser to fill in some of the missing functionality, but I certainly don't want to end up with documentation which requires plugins to view.

I've considered continuing with moinmoin and using something like fireshot to capture the entire wiki page into a single pdf and storing that in google drive to make them happy. But I believe that works by essentially stitching together a series of screenshots, resulting in a giant graphic, and therefore would not be searchable. Print-to-pdf works, somewhat. Both of these solutions of course preclude the other users from editing, and require the "real" documentation to be stored elsewhere.

I'm not necessarily opposed to storing the original document elsewhere and simply rendering it in an appropriate format for the team, but figured it would be worth my time to ask for recommendations from this list before I sink all my time into learning something new. I'm not opposed to using some new tool (like Atom or Sublime) that works on both mac and linux, but a big win would be the ability to do this with a chromebook as well.

Recommendations?


More information about the TriLUG mailing list