I am looking at alternatives to the Adobe Robohelp help/documentation system development software.
Are there any recommendations over the many open source packages that exist?
I have looked briefly at Sphinx. Has anyone got any experience with this package?
Many thanks in advance for your suggestions and comments.
Regards
Brock
I've used sphinx for several years to document (collections of) items for myself. I find it useful although limited in its presentation. To get a feel how it works, look at my page of asymptote examples:
http://linearalgebra.math.umanitoba.ca/asyinfo/
Note the option "Show Source" below the table of contents to get a feel of the markup language the sphynx uses.
Cheers, Michael ------------------------------------------------------------------ Michael Doob Telephone: (204) 474-9796 Professor Emeritus Department of Mathematics University of Manitoba Winnipeg, MB, Canada R3T 2N2 Email: michael.doob@umanitoba.ca ------------------------------------------------------------------
________________________________________ From: Roundtable roundtable-bounces@muug.ca on behalf of Brock Wolfe obwolfe@shaw.ca Sent: January 21, 2023 10:33 To: roundtable@muug.ca Subject: [RndTbl] Help and Documentation System Development
Caution: This message was sent from outside the University of Manitoba.
I am looking at alternatives to the Adobe Robohelp help/documentation system development software.
Are there any recommendations over the many open source packages that exist?
I have looked briefly at Sphinx. Has anyone got any experience with this package?
Many thanks in advance for your suggestions and comments.
Regards
Brock
Whether I like it or not (NOT!) pretty much everything nowadays just opens a browser to a webpage when you click the Help button, so your options are manifold. I would stick with something standard like ReadTheDocs.org’s format, even if you don’t host the content there. They support both Sphinx and McDocs.
Just… if you do this and host the content externally, PLEASE (a) version your help files in lock-step to the software version, even if that means lots of duplication, and (b) don’t remove old documents OR in-document anchors. People out there will use friggin’ ancient versions of your software, but that doesn’t mean the don’t deserve documentation. With a giant banner telling them they’re now “7 YEARS OUT OF DATE”, sure, but at least leave the docs online!
Tangentially, ReadTheDocs has some decent Sphinx resources…
-Adam
From: Roundtable roundtable-bounces@muug.ca On Behalf Of Brock Wolfe Sent: Saturday, January 21, 2023 10:34 AM To: roundtable@muug.ca Subject: [RndTbl] Help and Documentation System Development
I am looking at alternatives to the Adobe Robohelp help/documentation system development software.
Are there any recommendations over the many open source packages that exist?
I have looked briefly at Sphinx. Has anyone got any experience with this package?
Many thanks in advance for your suggestions and comments.
Regards
Brock
*MkDocs, not McDocs. It’s not fast food. (Oops)
From: Roundtable roundtable-bounces@muug.ca On Behalf Of Adam Thompson Sent: Saturday, January 21, 2023 11:25 AM To: Continuation of Round Table discussion roundtable@muug.ca Subject: Re: [RndTbl] Help and Documentation System Development
Whether I like it or not (NOT!) pretty much everything nowadays just opens a browser to a webpage when you click the Help button, so your options are manifold. I would stick with something standard like ReadTheDocs.org’s format, even if you don’t host the content there. They support both Sphinx and McDocs.
Just… if you do this and host the content externally, PLEASE (a) version your help files in lock-step to the software version, even if that means lots of duplication, and (b) don’t remove old documents OR in-document anchors. People out there will use friggin’ ancient versions of your software, but that doesn’t mean the don’t deserve documentation. With a giant banner telling them they’re now “7 YEARS OUT OF DATE”, sure, but at least leave the docs online!
Tangentially, ReadTheDocs has some decent Sphinx resources…
-Adam
From: Roundtable <roundtable-bounces@muug.camailto:roundtable-bounces@muug.ca> On Behalf Of Brock Wolfe Sent: Saturday, January 21, 2023 10:34 AM To: roundtable@muug.camailto:roundtable@muug.ca Subject: [RndTbl] Help and Documentation System Development
I am looking at alternatives to the Adobe Robohelp help/documentation system development software.
Are there any recommendations over the many open source packages that exist?
I have looked briefly at Sphinx. Has anyone got any experience with this package?
Many thanks in advance for your suggestions and comments.
Regards
Brock
-
Adam Thompson -
Brock Wolfe -
Michael Doob