[13]Modified Help System

Locked
User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

[13]Modified Help System

Post by Chris Davenport » Fri Feb 22, 2008 4:13 pm

Note: Although this paper is primarily concerned with the Joomla! help system, it also makes a proposal regarding Joomla! error handling and how it might be loosely coupled with the help system.

Introduction
The current Joomla! help system has worked remarkably well over the years and has remained essentially unchanged since Mambo days. However, there are some inherent difficulties with it that lead to consideration of an updated help system.
  • The back-end help server must be either a (remote) Joomla! installation or the local Joomla! filesystem. Non-Joomla! back-ends are not easily supported.
  • There is no flexibility in the interface to the remote help server. The URL used to access the remote system is fixed and would require a core hack to change it.
  • Similarly there is no flexibility in the interface to the local help files.
  • The table of contents page is generated from the directory of local help files that happen to be present, plus those added from third-party component help directories. A new help file added to a remote help server is effectively invisible.
  • Local help files can only be updated during the normal update cycle for Joomla! itself, whereas experience has shown that the development of help information works to a different cycle to that of the code.
This paper makes a proposal that will address these issues and also enhance access to documentation in both Joomla! itself and third-party extensions. In summary,
  • Arbitrary back-end help servers may be supported. In particular, we will be able to move the official help screens from help.joomla.org (a Joomla! instance) to docs.joomla.org (a MediaWiki instance) where they will be easier to maintain. This is perhaps the most significant reason for wanting to change the current help system as it makes it easier for the Doc WG to bring the help screens into the modular, re-usable documentation methodology that we are moving towards for the bulk of the documentation.
  • All Joomla! produced error and warning messages become potential entry-points into the documentation. This will allow the user to obtain context-sensitive help with specific error conditions and by using a wiki the Dev and Doc WG can evolve the support given in the light of experience with the software.
  • Flexible support for multi-language back-end help servers. We will have a range of options for handling multi-lingual help that are not be tied to a specific technology.
  • All these same capabilities will be available for extension developers to exploit if they wish to.
  • No changes are required to key references in the current code base.
  • Existing help servers can continue to be used if required.
JHelp
Help sites are currently listed in administrator/help/helpsites-15.xml, which can be thought of as a registry of available help sites. Currently this contains just the one entry:

Code: Select all

<?xml version="1.0" encoding="iso-8859-1"?>
<joshelp>
  <sites>
    <site tag="en-GB" url="http://help.joomla.org">English (GB)</site>
  </sites>
</joshelp>
This arrangement lacks the flexibility that will be required for this proposal, but rather than specify particular changes to the XML file the following changes to JHelp are suggested instead as this forms the API to access and manage the help sites registry. By talking about the API to the registry in abstract terms it can be left to others to decide the most appropriate physical implementation for the registry itself. This might turn out not to be an XML file.

The intention is that the help sites registry will contain information about all help sites including those used by the installed extensions.

Properties
Each registry entry has the following properties:
  • key is a unique identifier string which can be used to reference a specific registry entry. All keys beginning with an underscore are reserved for use by Joomla! itself.
  • type is a string indicating the type of the registry entry. The following types have special meaning:-
    joomla means that the help site contains full help information for Joomla! These sites are the ones that will be listed as help sites in Global Configuration and the User Manager. Help sites that provide support for extensions will use their own type string.
  • method is a string containing the name of the method used to access the help site. The currently supported methods are:- file to access files on a mounted filesystem; http to access web pages via the HTTP protocol. Support for other methods may be added in the future as required.
  • name is a string describing the help site and is for display purposes only.
  • resource is a string most likely containing a path or URL that will be used to access pages on the help site. A resource string may contain substitution codes that will be replaced before it is used (see later).
  • selected is a boolean which indicates the preferred or currently selected help site amongst entries with a given type. For example, the default Joomla! help site selected in Global Configuration will have the selected property set to true while others with type = joomla are set to false.
Methods
JHelp manages the repository of information about help sites and is the API for access to the registry. The JHelp class requires the following methods:-
  • addSite ( $key, $type, $name, $resource, $method='http' )
    Adds a site to the registry.
  • removeSite ( $key )
    Removes a site from the registry.
  • createUrl ( $key, $id, $extver='' )
    Returns the URL (or path) to access the resource using the given reference. This method already exists but will need to be extended to support substitution codes in the resource name and the addition of a $key to specify which help site to use. The optional $extver parameter is so that third-party extension developers can pass an extension version string for the {extver} substitution code.
  • createSiteList ( $type=null, $selected=false )
    Returns an array of help sites which match the type requested. If $type is empty or null then all help sites will be returned. In effect, the type forms a namespace for help sites and extension developers should carefully select a unique name, probably based on the name of their extension, to avoid help site name collisions. This method already exists but needs to be modified to allow selection by type. If $selected is true then only help sites with the selected property set to true will be returned. Otherwise, help sites with selected property in either state will be returned.
  • selectSite ( $key )
    Sets the select property of the entry specified by $key to true. The select property of all other entries with the same type string as the one specified by $key will be set to false.
Resource substitution codes
The following codes (at least) should be available for substitution into the resource string by the createUrl method.
  • {id} is a unique identifier for the help resource. For example, in the old-style key reference "screen.installer.15", the "screen.installer" part would be regarded as the {id}. This is just the $id parameter passed to createUrl.
  • {version} is a shortened version of the for Joomla! version number comprising the major and minor version numbers with no dot separator. For example, for Joomla! 1.6.x {version} would be "16". This is backwards compatible with the current version suffix string.
  • {major} is the major version number. For example, for Joomla! version 1.6.2 {major} would be "1".
  • {minor} is the minor version number. For example, for Joomla! version 1.6.2 {minor} would be "6".
  • {maintenance} is the maintenance release number. For example, for Joomla! version 1.6.2 {maintenance} would be "2".
  • {language} is the ISO-defined language code for the current language. For example, "en-GB" is used for British English.
  • {langcode} is the short language code consisting of the first two characters of the ISO-defined language code for the current language. For example, if the ISO language code is "en-US" then {langcode} would be "en".
  • {client} is the Joomla! client name ("site" for the front-end, "administrator" for the back-end, "installer" for the installer).
  • {extver} is the version of the extension (where relevant). This is just the $extver parameter passed to createUrl.
Example registry entries
The following two entries would give backwards compatibility with the current help server options.
key = “local”
type = “joomla”
method = “file”
name = “Local help”
resource = "administrator/help/{language}/{id}.{version}.html"

key = “joomla”
type = “joomla”
method = "http"
name = “English (GB) – help.joomla.org"
resource = "http://help.joomla.org/index2.php?optio ... }.{version}”
The following example illustrates how local help files could be located anywhere on a local area network using a mounted filesystem.
key = “lan”
type = “joomla”
method = “file”
name = “LAN file server”
resource = “/mnt/net41/joomla/help/{language}/{id}.{version}.xml”
This example illustrates how the MediaWiki at docs.joomla.org could be used as a help server back-end. This example uses language pseudo-namespaces to serve multi-lingual help.
key = “wiki”
type = “joomla”
method = “http”
name = “Joomla! official documentation site”
resource = “http://docs.joomla.org/{langcode}:{id}_{version}”
Another approach to multi-lingual help is to have separate help server instances each in its own subdomain. [Can the full ISO language code be used as a subdomain name? Would we want to do that anyway?]. This is the preferred approach for us to produce a multi-lingual documentation site.
key = “multi-lingual wiki”
type = “joomla”
method = “http”
name = “Multi-lingual documentation site”
resource = “http://{langcode}.joomla.org/docs/{id}_{version}”
We would implement a hard redirect of http://en.joomla.org/docs to http://docs.joomla.org using mod_rewrite.
For an example of a set of multi-lingual MediaWiki pages using this method see http://en.wikipedia.org/wiki/Spreadsheet

For more information on multi-language support in MediaWiki see, http://en.wikipedia.org/wiki/Help:Interlanguage_links
http://www.itia.ntua.gr/~anthony/tmp/mu ... wikis.html

Core parameter types

helpsites
The core parameter type “helpsites” should be modified as follows:-
  • default attribute will be used as the id parameter in a call to createSiteList.
  • helptype is a new attribute that will be passed as the type parameter in a call to createSiteList.
  • selected is a new attribute that will be passed as the selected parameter in a call to createSiteList. This attribute is optional.
For example, the following XML fragment will show a drop-down list of all help sites associated with a ficticious component called “com_musthave”.

Code: Select all

<param name=”helpsites” type=”helpsites” helptype=”com_musthave” default=”” label=”Help sites” description=”Select a help site” selected=”false” />
help
While not strictly necessary, a new core parameter type, called “help”, is proposed. This will allow extension developers to add a button to any parameter screen for access to extension and context-specific help information. It has the following parameters:
  • name is the field name.
  • type is 'help' to indicate that this a help parameter.
  • helpsite will be passed as the key parameter in a call to createUrl.
  • helpid will be passed as the id parameter in a call to createUrl.
  • label will be used as a label for the button.
  • description will be used as alternative text for the button.
For example,

Code: Select all

<param name=”helpwithsomething” type=”help” helpsite=”com_musthave” helpid=”Help_with_parameter_x” label=”Help  me” description=”Click me for help with something” /> 
will present a button labelled “Help me” which when clicked will pass “Help_with_parameter_x” via the {id} substitution code to the help site registered with key “com_musthave”.

Extension Developers
Extension developers can add information about their own help servers into the registry using the $type field as a kind of namespace. Access to help for an extension can then be supported in the same way as with Joomla! itself, but without involving the official Joomla! websites. Help sites can be added to the registry using the addSite method in the com_install function (and removed using the removeSite method in the com_uninstall function).

However, a straightforward extension to the installer XML would simplify this for developers. For example, the following XML fragment could easily be supported to add a help site during component installation.

Code: Select all

<helpsites>
  <helpsite key=”com_musthave” type=”com_musthave”>
    <name>Must have component help site</name>
    <resource>http://musthave.com/help/{id}.{extver}</resource>
  </helpsite>
</helpsites>
Warning and Error Messages
Just as a user clicking on a help toolbar button can be thought of as a cry for help, the presentation of a warning or error message could be the precursor to such a cry. By adding a link in the message presented, the user can be given the opportunity to request help with the specific condition. Additionally, community experience with a particular error condition can be fed into the resource that is linked to by the error message so that feedback to the user can be improved over time.

Adding the link is easy to achieve programmatically but requires that each error/warning condition have a unique identifier that can be used to construct the URL. JHelp::createUrl is called to create the link, passing this unique id into the {id} substitution code. The following format for the id string is suggested:

Code: Select all

<package>_<subpackage>_<uid>
Where:
  • <package> is the name of the package where the error/warning occurred. This should match the @package name in the phpdoc tags for the code where the error/warning occurred. Extension developers must not use the Joomla! package names (which should therefore be regarded as "reserved").
  • <subpackage> is the optional name of the subpackage where the error/warning occurred. This should match the @subpackage name in the phpdoc tags for the code where the error/warning occurred. Extension developers are free to use subpackage names which match those used in Joomla! itself.
  • <uid> is a unique numeric identifier for the error/warning condition. This identifier must be unique within the package. In other words, the same identifier must not be used in different locations within the same package. The <package><uid> together should form a globally unique identifier. The code 99999 has the special meaning of “not yet allocated”. Prior to a release, the codebase can easily be swept for occurrences of this code so that proper codes can be assigned. Code numbers are allocated sequentially and are not re-used.
For example, an error raised in the utilities subpackage of the Joomla! Framework package might have the following id:

Code: Select all

JFramework_Utilities_1234
It is then trivially easy to create a wiki page at http://docs.joomla.org/JFramework_Utilities_1234 which explains the error, possible causes and what to do about it. This can be kept up-to-date as experience with the error condition grows.

By adding each wiki error page to a special “error” category, the wiki will automatically maintain an alphabetical contents page so that it becomes easy to assign the next sequential error code.

Tooltips
An interesting but probably impractical extension to this idea is to store tooltip text in the back-end help server and have it retrieved, perhaps via AJAX, as the user hovers over the relevant region. This would be useful because the tooltip text could then be transcluded into the help screen text. This would help to ensure that tooltip and help screen text is kept up-to-date with the minimum of effort. Raw wiki text can be retrieved programmatically using the MediaWiki API which returns it with a minimal XML wrapper. The tooltip text chunks might also be re-used elsewhere in the documentation.

The MediaWiki API is described here: http://en.wikipedia.org/w/api.php

Admin help page
At present the user is presented with an alphabetical table of contents generated from all the local help files, together with local help files found in all the installed components. Whilst quite clever, this is not all that helpful as it is merely listing the help screens available from individual screens in the software. It would be nice to find a way to present task- or goal-orientated information instead.

The suggestion here is that the left-hand list merely comprises a list of registered help sites that are currently selected. Clicking on any of the links will bring up a page with a standard id, perhaps “Start_here”. This page must be present on all registered help sites for this to work. The content of this standard page can be anything but in the case of the Joomla! help sites should be lists of tasks or goals, perhaps grouped by user type (eg. editor, publisher, administrator, etc). Extension developers can choose to organise their help sites in other ways if they choose.

The top item on the help sites list should always be the help sites for Joomla! itself, followed by registered extension help sites. When the help page is first presented, the “Start_here” page for Joomla! will therefore be shown.

Impact on performance
Having the createUrl method retrieve the resource from the help sites registry could have a performance impact depending on how the registry is implemented. However, the resource can easily be cached to mitigate this.

The proposal regarding tooltips clearly adds network latency to the time taken to show tooltip text to the user. Whether this will be acceptable is uncertain.
You do not have the required permissions to view the files attached to this post.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
newart
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 3177
Joined: Fri Sep 02, 2005 10:06 am
Location: Solar system - Earth - European Union

Re: Modified Help System

Post by newart » Tue Mar 11, 2008 7:41 am

I've found this project as a very interesting one! Complete and useful, I hope to see good news on that idea as it's important to "collect" info & help for your site system, it's another way for being "close to the users"...
former Q&T WorkGroup Joomla member - Italian Translation Team Member

User avatar
masterchief
Joomla! Hero
Joomla! Hero
Posts: 2247
Joined: Fri Aug 12, 2005 2:45 am
Location: Brisbane, Australia
Contact:

Re: [13]Modified Help System

Post by masterchief » Sat Apr 19, 2008 3:52 am

Andrew Eddie - Tweet @AndrewEddie
<><
http://eddify.me
http://www.kiva.org/team/joomla - Got Joomla for free? Pay it forward and help fight poverty.

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: [13]Modified Help System

Post by Chris Davenport » Wed Apr 23, 2008 6:25 pm

Since this White Paper was first written a couple of points have surfaced which suggest minor amendments to the specification.

Firstly, the help server registry should also contain a field for parameters to be passed to the window that will popup when a help toolbar button is pressed. Currently such parameters are hard-wired into Joomla! and would require a core hack to modify. A user/administrator might want to modify the parameters if, for example, the help screen pages have a different aspect ratio. This is likely to happen when non-Joomla! back-end help servers are used.

Secondly, the current proposal includes support for the following substitution codes:
{language} eg. "fr-CA" for Canadian French
{langcode} eg. "fr" when {language} = "fr-CA"

It has become apparant that we also need to support the region code separately:
{region} eg. "CA" when {language} = "fr-CA"

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
Roman Blanty
Joomla! Explorer
Joomla! Explorer
Posts: 372
Joined: Thu Aug 25, 2005 5:32 pm
Location: Internet
Contact:

Re: [13]Modified Help System

Post by Roman Blanty » Tue May 27, 2008 8:59 pm

This is well written paper indeed. However, I have to disagree with the basic idea behind it.
You say Joomla! can't handle its own help system so we should make it use external solution. Sounds reasonable, however it needs considerable amount of work to make it happen. Work that could, and IMHO should be invested in making Joomla! powerful enough to handle help system itself... Or maybe we should use Drupal to handle joomla.org sites, since it is much faster, more flexible and reliable than Joomla! 1.5?
Proud Polish Joomla! Team Member > http://www.joomla.pl
Hardcore Translator ;)
Joomla! Translation Coordination Team
Jobs in IT: http://www.workita.com

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: [13]Modified Help System

Post by Chris Davenport » Tue May 27, 2008 11:28 pm

The changes being suggested to Joomla! would make it possible to use *anything* as a back-end help system. That could be a local filesystem, Joomla! itself, MediaWiki, a different wiki, a Drupal instance, a Plone instance, even your friendly internet-enabled toaster. It gives documentors, translators and third-party developers complete freedom in choosing how they want to host their help systems, where previously we/they have been tied to using Joomla! only.

I don't think I said that Joomla! could not handle its own help system and if people want to host help pages on a Joomla! instance they can continue to do so. But we want to reduce the effort involved in creating and maintaining documentation (which includes the help pages) by making it modular and re-usable. So help pages and other "documents" will in future be assembled from re-usable "chunks".

Although there are proprietary solutions to document re-usability available which are widely used in the corporate world, we chose MediaWiki to host the documentation because it supports modular, re-usable documentation "out of the box", it is GPL-licensed, very powerful, and includes features which help us lower barriers to participation. By hosting the official English help files for Joomla! 1.6 onwards on the same wiki, we leverage re-usability of the documentation and move to a position where the help files are entry-points into the bulk of the online documentation. This should provide the end-user (mainly Joomla! administrators) with a better experience as the help files are not isolated from the rest of the documentation but are merely specialised views of parts of the available documentation.

The work involved in implementing a new help system as described in this white paper is, I would argue, much less than would be required to implement transclusion (the principal technical feature of MediaWiki which helps us achieve document re-usability) in Joomla! and by continuing to host the help files in Joomla! we would also have failed to lower the barriers to participation.

I couldn't possibly comment on your comparison with Drupal as I've never used Drupal. :p

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
downunder
Joomla! Intern
Joomla! Intern
Posts: 83
Joined: Sat Aug 20, 2005 9:56 am
Location: Gaven (QLD) Australia

Re: [13]Modified Help System

Post by downunder » Fri Jun 27, 2008 3:30 am

I whole-heartedly agree with the concept. I have been moving a product from a wrapper environment to a 1.5 component and the help system flexibility is the only thing missing from a truly great MVC framework.
Left to their own devices, developers (generally) would make the whole Joomla help experience less professional from a UI stand-point (remember Windows 3.1). The more consistency with flexibility... the stronger Joomla will become...

Chris, I would loved to get involved in this but time is my enemy at present... but it will happen.
Never doubt that a small group of thoughtful, committed citizens can change the world. Indeed, it's the only thing that ever has... Margaret Mead

User avatar
pedrofilho
Joomla! Apprentice
Joomla! Apprentice
Posts: 10
Joined: Sun Jan 25, 2009 7:43 am
Location: Recife, Pernambuco, Brazil
Contact:

Re: [13]Modified Help System

Post by pedrofilho » Sun Jan 25, 2009 9:08 am

Hello Mr. Chris,

I am the http://www.amazingfriends.org owner and developer. Get involved with Joomla a few months ago, since September last year.

Co-founder member of http://www.ibdi.org.br which is the Politics and Cyber Law Brazilian Institute since 1999, now I am working on OSIs documentation to some Open Source based project and our website was almost build under Oursourcing concepts, where I give legal time and knowledge in Ciber Law in trade for Open Souce coding learning and implementing under an Apache server based provided by ULTRA Website Hosting.

I do need nothing special from Joomla, except to contribute to documentation Legal Review and compliances with Open Source Regulations.

As I read in the appropriate topic in this forum, to join the team I need an invitation and I am asking you to invite me, of course, I'll provide all personal information and my resumè inconditionally.

This is not only a statement, but a love declaration for the Joomla project and the magnific social and digital integration it provides giving to many a chance to have an exceptional reliable system for developing aplications trought the www.

I do some volunteers services here in Brazil, especially with http://www.cdi.org.br which is a commitee for computers democratization that borns in a Rio de Janeiro "Favela" and are a world reference in social and digital integration.

I'll be very honored to be part of doc developer team of Joomla and hope you contact me to make this a real thing in my life.

Thank you very much !

Pedro Torres Filho
Administrator - Lawyer
Pedro Torres Filho
AmazingFriends.org
Lawyer - Webdeveloper

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: [13]Modified Help System

Post by Chris Davenport » Mon Jan 26, 2009 8:39 pm

Hi Pedro,

Welcome to the Joomla project. :)

You don't need an invitation to join in. Take a look here: http://www.joomla.org/about-joomla/cont ... oomla.html for some ideas on how to get started.

For the developer documentation, take a look here: http://docs.joomla.org/API_Reference_Project where we are trying to document the 1.5 Framework API and here: http://docs.joomla.org/Developers where we are assembling more general developer documentation. The documentation is held in a wiki and you just need to register on the wiki to be granted write access. No need to ask permission; just get started!

Thanks for volunteering. I hope you enjoy contributing to Joomla.

Regards,
Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/


Locked

Return to “Accepted - Archived”