I think that easily-available, accurate and easy-to-consume documentation really provides significant value to any tool. I think its critical to provide this on Gadget and providing it on-board is about as easy as it gets.

Most open-source, hacker-oriented tools have online wiki-based documentation, which is great until you don't have a solid internet connection (actually happens to me more than I'd like to admit... yes, even in 2016!).

I like the idea of a wiki, but such an approach often leads to outdated, inconsistent or hard-to-follow docs. I've opted to go for Markdown-based documentation stored in a public Github which I think is a good middle-ground - anyone who wants to contribute is welcome to submit pull requests, but at the end of the day there is a controlled point of entry (...me) to try and make sure it stays in good order.

My aim is to have a basic page on each major feature of Gadget, this will provide an overview of what the feature is, what it can do, as well as the pins to use and basic usage of any commands. This should provide the bare-minimum required to make someone able to use the feature in its most common use-case. Here's a sneak-peek of a section of the i2c page:

The commands should not be thoroughly documented on these introductory pages - a simple "usage" text and example invocation should be enough - this should help jog the memory of any user who has used the tool before, and provide a known-good "Hello World" for any first-time user.

From these pages, more detailed pages on particular tools can be linked if deemed necessary, however I think for a lot of cases the best thing would be to link the the respective project's own documentation (which yes, needs an internet connection).

You can view the documentation repository on Github: https://github.com/usedbytes/gadget-doc. Of course it's a work in progress and pretty empty right now. It's more of a look-and-feel proof of concept than a useful resource at the moment