Preamble

This page details the procedure that should be followed when creating new pages and reviewing existing pages of the Joomla! Developer Documentation. This procedure was originally written at a time when the Developer Documentation was held on the official Joomla! help site, but has since been revised now that the documentation has been moved to the developer documentation wiki. The procedure is essentially the same, but the details differ, mainly because the "internal review" is now conducted in public. Although originally written to support the activities of the API/DB Reference mini-team it may well be adopted by other teams although some of the references given will be specific to the API/DB Reference mini-team only.

Step 1: Planning

For each new page to be written (or each new group of pages), a new task should be created in the Joomla! Forge task manager with the basic details required. It is the Team Coordinator's responsibility to do this. Status of the task should initially be set to "Not started" and the priority set to whatever is deemed reasonable at the time.

If anyone feels that the priority associated with a given task should be adjusted then they should post a message in the private Developer Documentation forum or send a private message to the Team Coordinator. The Team Coordinator will make a decision and adjust the priorities as necessary.

Step 2: Authoring

At the present time any member of the Documentation Team can choose to become an author for a new page and assign it to themselves, but please be aware of the priority codes given to each task so that higher priority pages should tend to get written first. When an author begins to write the new page(s), they should set the task manager status to "OK" and assign the task to themselves. This is so that authors can work on new pages without fear that work will be duplicated. So always check the task manager before starting work on a new page in case someone else has already started work on it.

For API Reference pages each page should include a standard header table with "Last reviewed" set to "Not reviewed" and "Doc status" set to "Work in progress". See this page for a typical example.

For non-API Reference wiki pages, the page title should include "[Work in progress]" in the title. For Joomla! content pages, the page title should include "[Work in progress]" in the title and the page should be set to "Public/Unpublished" state.

Authors should be aware of the following documents when writing new pages:

Joomla! Editorial Style Guide

Guidelines for creating and reviewing an API Reference page

specifically for API Reference pages.

When the author has completed the page(s) the task manager status should be changed to "Warning" and the word "Finished" and the date entered into the "Accomplishments" box. The "Warning" status will be used to mean that the Team Coordinator needs to make a decision concerning the task. Using the status codes makes it easier to use the filters to manage work in progress. Leave the "Assigned to" field as it is.

Step 3: Internal Review

As a basic quality assurance step each page must undergo an internal review by someone other than the author. This is intended to merely spot obvious mistakes. It is not as detailed as a full review and in particular it is not necessary to test example code. It is the Team Coordinator's responsibility to assign the task to a reviewer, change the task status to "OK" and change the "Doc status" field in the standard header table to "Internal review".

In the case of non-API Reference wiki pages and Joomla! content pages the "[Work in progress]" should be changed to "[Internal review]" in the page title.

Reviewers should be aware of the following documents when reviewing pages:

Joomla! Editorial Style Guide

Guidelines for creating and reviewing an API Reference page

specifically for API Reference pages, but note that it is not necessary to test the example code or perform detailed checking against the Joomla! codebase.

Once the internal review is complete the reviewer should change the task manager status to "Warning" and enter the word "Reviewed" and the date into the "Accomplishments" box. Leave the "Assigned to" field as it is. For API Reference pages the reviewer should also update the "Last reviewed" date in the standard header table in the page itself, but leave the "Doc status" as "Internal review".

Step 4: Public review

The Team Coordinator will set the task manager "Assigned to" field to "Unassigned", the status to "OK", the "End date" to one month from the publication date, and enter the word "Published" and the date into the "Accomplishments" box. For API Reference pages the "Doc status" in the standard header table will be changed to "Public review". For non-API Reference wiki pages and Joomla! content pages the "[Internal review]" in the page title will be changed to "[Public review]". For Joomla! content pages the page status will be changed to "Public/Published".

The Team Coordinator will make an announcement in the Developer Documentation Forum to the effect that the page is available for public review.

The public review period is set at one month. Corrections reported during or after the public review period should be entered into the Joomla! Forge tracker. Any member of the Developer Documentation Team may check the report for accuracy and apply the corrections to the page. They should assign the tracker item to themselves and ensure that it is updated and closed appropriately. The Team Coordinator is responsible for ensuring that such tracker items do not remain open for an unreasonable time.

The Team Coordinator is responsible for monitoring the public review process and for updating the task manager and the pages themselves at the end of the public review period. If the "End date" in the task manager was set correctly then Joomla! Forge will automatically send an alert email when the public review period ends.

The task manager status should be changed to "Complete". For API Reference pages the standard header table "Last reviewed" date should be updated and the "Doc status" should be changed to "Published". For non-API Reference pages and Joomla! content pages the "[Public review]" should be removed from the page title.

Step 5: Periodic Review

The Team Coordinator is responsible for arranging periodic reviews of existing 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. The Team Coordinator will assign tasks to reviewers and change the status of each to "OK". For API Reference pages the "Doc status" in the standard header table of each page will be changed to "Periodic review".

Reviewers should be aware of the Joomla! Editorial Style Guide

For API Reference pages the primary purpose of this review is to check to see if any changes have been made to the Joomla! codebase that need to be reflected in the documentation. For this reason it is necessary to check syntax and functionality against the source code and to verify that example code still works as described and produces the same output. Reviewers should refer to the Guidelines for creating and reviewing an API Reference page.

Once the review is complete the reviewer should change the task manager status to "Warning" and enter the word "Reviewed" and the date into the "Accomplishments" box. Leave the "Assigned to" field as it is. The reviewer should also update the "Last reviewed" field in the page itself.

The Team Coordinator will then change the task manager status to "Complete" and set the "Assigned to" field to "Unassigned". For API Reference pages the "Doc status" in the standard header table of each page will be changed back to "Published".

Summary