Creating a new API Reference page

It is important to keep a consistent style across the API reference pages so always start by using an existing page as a template. Familiarise yourself with the HTML used as you will probably need to modify it directly. The WYSIWYG editors tend to make a mess of some things so be careful (but don't be afraid to experiment; it's the only way to learn!) In particular, watch out for '&' being changed into '&' when this is not always appropriate. The only workaround for this at the moment is to select "No WYSIWYG editor" and correct the error directly in HTML.

All pages should initially be set to "Public" access and "Unpublished" state. The "Last reviewed" field at the top right of each page should initially be set to "Not reviewed". Remember to adjust the order of the page after you've created it so that the contents pages show the individual reference pages in alphabetical order. Except that a class overview page should always precede all other pages in the class and the class constructor page should always immediately follow the class overview page. Functions/methods that are not part of any class should simply be listed in alphabetical order along with everything else.

All pages should if possible include at least one example. Where more than one example is included they should be graded so that the most basic example is first with the examples becoming increasingly sophisticated. If possible each example should be self-contained so that a simple cut-and-paste should give the user a working example without needing to make amendments or add additional code for it to function. For example, if the code sample uses the $database object then include a 'global $database;' statement in the code sample too.

Editing an API Reference page

If you are not sure that a change is required, or if you do not feel confident in making the change then please create a new artefact in the Joomla Documentation Project tracker.

If you make the change yourself be careful when using a WYSIWYG editor as they can and do mess up the code samples. In particular, watch out for '&' being changed into '&' when this is not always appropriate. The only workaround for this at the moment is to select "No WYSIWYG editor" and correct the error directly in HTML.

At any given time there are likely to be two Joomla branches active: the stable branch and the latest development code. Whereas the API Reference pages must reflect the current stable release they may also include information on upcoming releases. Naturally such information must be approached with some caution as it is likely to be provisional, but documenting early can be of real benefit as it provides advance warning to developers of likely changes to the API as well as spreading the load on the Dev Doc Team.

Reviewing an API Reference page

Joomla is under continuous development and so to ensure the highest quality documentation we need to carry out periodic formal reviews of the API Reference pages. Although reviews can be carried out at any time there is a particular need to carry out a formal review just prior to each major stable Joomla release. A formal review might also be done prior to publication of a new API Reference page. So, for example, if the current stable release is Joomla 1.0.2 then the next formal review will be triggered just prior to the release of Joomla 1.1.0 (but not Joomla 1.0.3).

Refer to the current Joomla Editorial Style Guide for advice on grammar, spelling, style and so on. Check for plain English but remember to preserve technical accuracy.

Validate all links and references.

Classes When checking the class overview page, check that no new functions/methods have been added which need to be documented. Functions beginning with an underscore are "private" and do need to be documented in the API Reference. Watch out for deprecated functions/methods.

Functions/methods

compare function syntax with the current stable release code.

check that arguments are of the correct type (eg. int, string, boolean).

check that all arguments are listed and described.

check that optional arguments are described as such and that the default value is described.

check that the argument description is correct.

watch out for any new (undocumented) arguments.

Check examples by, if possible, actually executing them in the current stable code. Examples should comply with current coding standards if possible.

If you come across references to Mambo then be aware of the Guidelines for Mambo -> Joomla Transition.

Once a review is completed you should update the "Last reviewed" field at the top right of the page to read, for example: "Last reviewed: 4 Oct 2005, Joomla 1.0.2". The date should use the three-letter month abbreviation (since this avoids misintepretation of date formats) and the Joomla version against which it was checked.