Xaraya | G. Rothfuss |
Request for Comments: 0019 | Xaraya Development Group |
Category: Informational | May 2002 |
RFC-0019: Help System
This memo provides information for the Xaraya community. It does not specify an Xaraya standard of any kind. Distribution of this memo is unlimited.
Copyright © The Digital Development Foundation (2002). All Rights Reserved.
The contents of this RFC contain the literal content of the old plain text version of RFC-0019
When time is a less scarcer good, someone might convert the plain text into structured XML so we can benefit from it.
All ?xxx numbers refer to the basic documents in section 7.
We read through the articles on http://www.postnuke.com, its forum threads, feature requests on sourceforge and the developers mailing list.
The following RFC is a first summary and contains some solution proposals either compiled from the basic documents or from general definitions concerning comments systems / forums.
It remains to be determined if the contents of the help system are better stored in the file system according to the module directory structure standard, or in a table. There are pros and cons for storing the data in the database.
xarModHelpURL(string module,string type, string topic) [2] provide a way to call into the help system (syntax very rudimentary, not final)
A proposal for a help module with articles, categories, ratings and comments almost in place, its time to leverage them for a kick ass online help system.
http://www.drupal.org/node.php?id=284 has some nice ideas.
i suggest we create a help utility module that does the following:
- maintain global / module specific manuals - allow for notes on the manual - provide feedback links to bug trackers - allows for rating of content
this could be achieved by storing manuals as articles in the article module, with a category indicating that it is documentation. each module would add articles on module install.
the categories would look like this:
these categories would be set with permissions indicating they can only be seen by administrators.
the help utility module would leverage the articles module by calling its API to display articles, call the comments modules to add coments, same for ratings. additionally, the help module could add a hook for feedback, sending feedback to the module author (data collected from xarversion.php)
A propsal for the help structure
Good documentation is essential not only for Xaraya "core" but also for modules. While installing, upgrading, removing a module should be intuitive, configurig right permissions to get the best from the script or understandig some tricky points or... require a good documentation. On the other side often good developers aren't good manuals writers ;-)
In my experience the most difficult part in writing manuals is organizing informations and guidelines: when you have done such a difficult work is only metter of filling in infos... more or less ;-)
So my idea: what about adding a "modules manual schema" in xardocs so that mods developers have only to fill in the section (and/or of course deleting/adding sects) ?
It could be just like a checklist or a summary with only chapter names. We could also add a reference to it in MDG chapter 7.12 and consider the implication with RFC 19 - Help System.
The first schema that comes to my mind is something like this:
[1] RE: ?xardev DOCUMENTATION: Preview PDF now available. xardev post 04/26/02 gregorrothfuss
[2] RE: ?xardev READ: New Block Stuff & Revamp xardev post 05/13/02 Veres Ferenc
We list features that were considered but rejected for this API below.
0.1 (May 13, 2002) gregorrothfuss
Initial Version
0.2 (July 9, 2002) gregorrothfuss
Module Schema from Stefano Garubi added
Help System implementation notes added