gurujim - Thu, 2017/09/21 - 04:08

As I begin developing library-related appliances, I need to consider how to provide end-user documentation.

Am I correct in thinking that the Turnkey design philosophy is to stay minimal, providing only the documentation that is internal to the application ( built-in help files etc ) plus links to the application website from the Turnkey Linux appliance's page?

The reason I ask is that for more remote libraries in developing countries, comprehensive documentation, such as manuals in pdf form ,  may be more usefully delivered along with the appliance on a physical CD or built into the iso.  Are such 'bloated' appliances better kept as separate projects altogether?

Thoughts?

Forum: 
General
Jeremy Davis's picture

Jeremy Davis - Thu, 2017/09/21 - 06:09
TBH, we have no issue with in depth documentation, it's more that we don't really have the time and energy to create and maintain it.

So if you would like to provide improved docs, be it for a specific appliance, or more generally, we'd be totally happy with that. Having said that, assuming that you aren't writing all these docs yourself, perhaps it's worth downloading the relevant docs at build time? Hopefully that way it will be easier to keep them in line with the version of software that is included.

The biggest issue with including docs within the appliances, is that when it's time to update and rebuild (i.e. release a new version) statically included docs sometimes get forgotten and not updated. And IMO, the only thing worse that no docs, is the wrong docs!

FWIW, we write most of our docs in rst (e.g. TKLDev docs). The beauty of rst is that it renders nicely on GH, it's easy to read as raw text (e.g. from commandline) and can also easily be converted to html for rendering by a web server (the 'rst2html' tool which is part of the python-docutils package).

Hope that helps...

Add new comment