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

[Huan Truong via TriLUG]

I feel that Pandoc does a lot of things correctly.

It can export to whatever format you like,
HTML/PDF/book/Word/ebook/LaTEX. Syntax highlighting is no problem.
You can edit a pandoc document wherever that has a text editor. If
your document isn't confidential to you, upload it to github and edit
wherever you have a browser. The only pain point is to track changes
and commenting. Tracking changes you can do with git, but commenting
is hard.

Cheers,
- H.
On Wed, Dec 19, 2018 at 4:45 AM Dewey Hylton via TriLUG
<trilug at trilug.org> wrote:
>
> 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?
> --
> This message was sent to: Huan Truong <webreg at tnhh.net>
> To unsubscribe, send a blank message to trilug-leave at trilug.org from that address.
> TriLUG mailing list : https://www.trilug.org/mailman/listinfo/trilug
> Unsubscribe or edit options on the web  : https://www.trilug.org/mailman/options/trilug/webreg%40tnhh.net
> Welcome to TriLUG: https://trilug.org/welcome