I’ve struggled for some time with long-form tutorial style documentation for various bits of things in our platform. It feels out of place in the reference documentation (since it’s not reference documentation) and often it doesn’t fit neatly into one module or another.
In 2013 the GNOME foundation sponsored my attendance at OpenHelp and the documentation hackfest in Cincinnati. We talked about this problem for a while and I laid out a few simple criteria that I had at the time for making it less painful to write docs:
- must be a non-xml markdown style language
- must not involve using version control tools (git, etc.)
- must not involve getting patches reviewed
- needs to go online instantly (and not after the next tarball is released)
The best possible solution that we could think up at the time was to make use of the wiki to launch a new experiment called “HowDoI”. A HowDoI is a wiki page that describes how to make use of a specific GNOME technology or platform feature. The target audience is generally developers who know their way around but are not yet familiar with a particular new feature, or for those looking for the latest “best practice”.
There is a How Do I HowDoI? page that you can read for more information.
A couple of years on, this has been a moderate success. We have HowDoI pages on a reasonable range of important topics and they have been very popular with the people who have used them.
In general, it is my opinion that we should be aiming to write these pages for new technologies as they appear in GNOME. I just wrote one that makes use of the new type declaration macros, for example.
If you didn’t know about these, check them out — they contain some helpful hints. If you did know about these, and you are writing new GNOME technologies, please write one!
Wikis! Aargh!