Suggestions for Adding Documentation to a Drupal Application
Interesting question, I've been asking myself about the same thing. Read on for details ...


From your last phrase, I get the impression that you don't seem to like the "Drupal Help documentation", or that for some reason it doesn't fit your needs. I'm assuming that your talking about the Advanced Help module. If not please add an hyperlink to what exactly you mean. I've been considering actually starting to USE the Advanced Help module, e.g. in the modules I maintain, such as chart, charts and visitors. E.g. because of it's integration with Drupal searches in a site, and because it's basically HTML formatted content, which should be straightforward to use for building actual tutorial contents.

I researched a bit within some of the typical modules (in core or contrib) that do come already with such 'Advance Help' tutorial pages (like 'trigger' back in D6 I believe). It took me a while to figure out what exactly to go look for where (= "what does this 'advance help' module actually add to such module that uses it?"). After I got that, I wondered "how do they do that, or what am I supposed to do in my own module to get something similar, and what kind of options/features do I have?". I didn't quite get it at first, so then I started to just scan the code of those contribute modules (using a string that I saw in the help docu from that module). Then I figured out, as often is the case in Drupal, it is a matter of knowing how to call which hook in the advanced_help module.

Next step I started to look around for "Advanced Help" about the "Advanced Help" module (makes sense I think, no?). Too bad, couldn't find any info about "how" to get this magic to work. Now 6 to 12 months later, and rather by accident, I discovered '1' (only!) community documentation page about the advanced help documentation. But you know what: on the project home page there is no (repeat: no) Read documentation link. After I discovered it, I did 2 things:

a) create issue #2445025 . More then 1 day later now ('only?' one might say ...), no reaction at all from any of it's maintainers. Last commit to this project is from late 2013. It makes me wonder about the health of this module (sorry). Haven't checked the health of the issue queue yet ...

b) While filing that issue, I was trying to understand the available docu in that (1) community docu page. I perceived it as fairly hard to read / understand, partially because of it's poor formatting. So I did as described in my PS in that issue. There is still lots of docu about that advanced help to be added. At least (I think) for a target audience like "technical writers" who might not have the skills to go figure out how to use the available hooks (something for drupal developers, but not for site builders or something similar). Yes producing docu might be boring for the experts who wrote a module (or it's most experienced users), but it is really important for a module to be successful, i.e. lots of reported installs and as few support / docu requests as possible
OK, enough about the 'help' module (wrong name! That's another module not at all related to it), I really do want to give it a try soon to get started with it in my own modules I maintain ... How about a completely different approach (which might only fit for some modules), which is "eat your own dogfood". Which is what we did in the forena module. It's a module for reporting (and charting) in Drupal, whereas it uses XHTML to actually 'develop' your custom report (report writer if you want). Here are some sample "help" pages for that module, shipped as part of the module, which you can see at work by just following the links to this demo sample:


Forena Help: if you check it out, make sure to also experiment with that "Refine Table of contents" pull down menu near the top, and see what happens if you change the (default) value for "show chapter extract" (from no to yes).
FrxTitle: That's just one (out of many) of the links you can follow on the page in the previous bullet. After visiting that link, scroll to the top of that page where it says "Including". That's (obviously) the TOC for the subitems on the selected page. With some CSS (not shown in this sample), you could eg move that "including" to the upper right corner (to make it look more wiki style).

Voilà (oeps), here you have 2 alternatives to consider. But you know what, while writing this answer I came to realise this: for somebody who is NOT looking for a module that forena is originally designed for (= reporting about all sorts of databases), forena might ALSO be consider as a possible alternative for the "advanced help" module. To proof my point: the entire set of "help pages" I described in the previous bullet, is just a matter of some (what is called) 'FRX' files. Go checkout the forena GIT repository to go look at them to see the "source" files (in FRX format) of those tutorial pages.


What was the original question again? Did I answered it?

PS 1: For anybody wondering now "how did he do that forena tutorial?", please contact me (or 'hire us and we'll teach you') ... or just read that tutorial ...

PS 2: I actually contributed most of the work for these forena tutorials as included in the most recent version 7.x-4.x. It is a complete rework of the preio release version, in which I added tons of extra content (features that were undocumented), and introduced this new navigation links, etc. When I first shared it with the module owner (David), he asked me something like ... "How did you do that! Can't believe I never thought of that myself".