[RndTbl] Help and Documentation System Development

[Adam Thompson]

*MkDocs, not McDocs.  It’s not fast food.  (Oops)


From: Roundtable <roundtable-bounces at muug.ca> On Behalf Of Adam Thompson
Sent: Saturday, January 21, 2023 11:25 AM
To: Continuation of Round Table discussion <roundtable at 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 at muug.ca<mailto:roundtable-bounces at muug.ca>> On Behalf Of Brock Wolfe
Sent: Saturday, January 21, 2023 10:34 AM
To: roundtable at muug.ca<mailto:roundtable at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://muug.ca/pipermail/roundtable/attachments/20230121/948fecdb/attachment.htm>