Xaraya G. Rothfuss 
Request for Comments: 0019 Xaraya Development Group 
Category: Informational May 2002 

RFC-0019: Help System

Status of this Memo

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 Notice

Copyright © The Digital Development Foundation (2002). All Rights Reserved.

Abstract

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.


Table of Contents


1. Introduction

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.


2.  List of requirements for the Help System

Use ?DocBook for the help text sources [1]
Have documenation in multiple formats: HTML, PDF
Allow context-sensitive help
seamless integration of support websites / irc / phplive
full text search
user feedback ala MSDN (see rate this page stuff)
ml support
newbie -> intermediate -> pro docs integrated (cross link to MDG from the installer docs, etc)
links to developer.xaraya.com or xCommunity as appropriate
integrate feature requests / bug report links
have a support script that collects environmental data
fetch phpdoc comments for programming manuals
synchronize documenation with master copy over xmlrpc

3. Solution proposals - database tables

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.

Pro
Easier to update the manual
Easier to perform full-text searches
Easier to translate
Easier to reference manual sections (for rating, comments etc)
Contra
Harder to provide content in standalone formats: PDF, HTML
Module vars:
Enable online help: Display help links throughout xaraya

4. Solution proposals - functions

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:

documentation
surveys
downloads
nascar

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. OVERVIEW
1.1 Purpose of this module
1.2 Requirements
1.3 Authors and credits
1.4 Obtaining latest version
1.5 Collaborate and bug catching and fixing
2. INSTALLATION
2.1 Fresh install
2.2 Upgrading
3. CONFIGURATION
3.1 Module configuration
3.2 Permissions
3.3 Block configuration
4. ADMIN GUIDE
4.1 Adding new items
4.1.1 How to
4.1.2 Input Labels explained
4.2 Editing items
4.3 Delete an item
4.4 Other options
5. USER GUIDE
5.1 View items
5.2 Display details
5.3 ....
5.4 ....
6. FAQ 7. TO DO

5. Relationship of the Help System to other areas

Comments System: Used for user comments on the manual
Ratings Module: Used for rating of manuals
XML-RPC Module: Sync documentation with master copy
Tracking Module: Collect usability data (which module is used most etc)
Admin module: provide help display functionality
phpdoc parser: get API commentary for programmers reference

6. Code that will need to be rewritten

Help system in admin module

7. Basic documents for this RFC

[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


8. Tools that need to be created from scratch

Docbook parser: We need to figure out a way to keep the docbook sources synced with the help system.
phpdoc parser: Is there a php-based phpdoc parser available? Check with PEAR.

9. Retractions

We list features that were considered but rejected for this API below.


10. Changelog

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