Joomla! Documentation™

Why a white paper approach?

A white paper is more or less a formal "feature request". The idea behind this is to change the mechanics of how development is done.

Firstly it's planned.

When a white paper is accepted everyone knows what is supposed to be achieved and there is a clear milestone that can be achieved. With this approach we also can interact more effectively with the other working groups like documentation earlier in the process rather than later.

Secondly this new mechanism is community driven.

This simply means that all input into the next release will come from anyone in the community, not just Development Workgroup Members. This is done to prevent scope creep mid-release, and also to actually get a feel for what community wants. Joomla! is an effort from a group of developers. It is important to embrace the talents that are in this group. But equally important is the opinion of, and the social responsibility we have to the many of the millions of site owners. An open and transparent process like this allows for many more people to have their opinions and ideas heard.

Who can post white papers?

Anyone can submit a white paper. You don't have to have a coded solution, you don't have to be a developer.

However, white papers must actually specify a goal that can be achieved, and present use-cases and reasons for this being a good idea. You can't just say "I want better ACL", or "we want more user features". You have to define exactly what you mean and want Joomla to achieve. Using those examples, you might want a particular granularity of ACL which could be used in a particular way; or you want the ability to have an "agree to terms of service system" for user registration...and so on.

A white paper is best compared with a functional requirements document. Collaborative work is also encouraged if a group of people want to work together on the same paper. However, you may also work on your own paper individually even if the topic is being looked at by others providing you are taking a different direction. The only restriction we have is you can do exactly the same thing if someone else is already working on it. In such cases, the authors of duplicate papers will be asked to merge their topics.

White paper guidelines

White papers must include at least the following:

1. A summary of the background of the issue you are trying to solve or feature request you are requesting (the 'why' does this need to be done)
2. An overview of the functional requirements , or simply the goals that are to be achieved (the 'what' needs to be done).
3. Thoughts on how your proposal will affect change management (does it affect backward compatibility, does it change the UI such that training would be required, etc)

These items to not have to be technical in nature. They can describe the issues from a users perspective in user language provided that there is enough information for the Development Working Group to be able to write a technical addendum to the paper if acceptance. However, if you have the ability, then the following additional items are also welcomed in any paper:

• A detailed assessment of change management issues
• An overview of the impact on the existing architecture
• A functional description of API or UI elements (the 'how')
• Any dependencies that the proposal has. For example, it might rely on another white paper being accepted which facilitate a change that you need. This might also include additional libraries that need to be included with the Framework.
• A planning outline with milestones for delivery. For "large scale" changes you should consider setting realistic steps that can be achieved. Papers that would require a single effort of 6 months of development will not be accepted. However, if the paper breaks that into steps that can occur over three or four versions, this would be looked upon favourably.

Note that members of the Development Working Group will be expected to attempt to address these additional requirements if possible depending on your experience.

Submitting White Papers

White Papers are submitted on a specical sub-forum; http://forum.joomla.org/index.php/board,500.0.html. This is open to the public. It has sub-forums for "Accepted", "Under review" and "Not Accepted" into which threads are moved during the review process.

A white-paper topic would be started as a thread. The author(s) must briefly outline what it is in the thread-starter, but from there the actual content of the paper can be anywhere, provided it is publically available. Examples would be a public Google Doc, a wiki page, a content item on a website, a downloadable PDF, or text within the thread itself. The media doesn't really matter providing that drafts are publically viewable. A simple approach is to keep the master text in the original topic, and make changes to it as you received feedback.

The community can then comment on any white paper they are particularly interested in. The forum is moderated, because experience learns that not all the feeback will be constructively. With this approach we make it possible for everyone to give input an feedback and we get a chance to chip away at some of the "oh, I didn't think about that" issues. People might even find that the idea for a new feature is great, but user comment would take it's implementation in a completely different direction that first though. Authors are encouraged to self-moderate their topics but if they find themselves drowning in criticism or unproductive discussion should contact a moderator for assistance.

People with duplicate papers will be asked to merge with existing topics unless they can provide a good reason (like examine the same approach from a difference angle and having different goals).

At this time, polls are not permitted as we want to encourage a process of peer review rather than anonymous voting.

Planning

The process of submitting white papers when started will be an on-going process. Anyone will be able to submit and work on one at any time. However, closing dates will be set by which papers will need to be ready if they are to be considered in the next release. Those dates will be shown in a sticky topic in the forum.

Authors will need to indicate that there paper is ready to be reviewed and any that are after the closing date will be moved into the "Under Review" sub-forum.

The Development Workgroup will then perform a two-round process of accepting papers.

Round One

Each Development Working Group member picks his/her top ten white-papers and score score them from 1 to 10 (1 being the best) we collate and sum these results.

Group members should choose wisely and take into account backward compatibility issues (either from user, trainer, implementor or developer points of view), community interest and what they feel would be of best value to the next release of Joomla!. Papers that have received little or no input, as a guide, should not be ranked highly. Group members, in their ranking, must balance between what the community most wants and the necessary work to achieve this.

Round Two

From these results of round one, the ten lowest aggregate scores are selected for detailed analysis. The Development Working Group then writes the technical specification based on the white papers (some may need little or no work, others may need a lot), including the amount of effort involved. The group then accesses whether it can actually fit that amount of work into the next version. If it can't, items drop a few. If it can fit more in, then the next five ranked papers (as a guide) are examined.

Proposals may be scaled down, may be scheduled to be included over several versions in steps, or may be altered slightly based on the way in which differing points of view from the community input can achieve a best fit result. However, the original point of the paper must still remain. Taking an idea and mutating into a desired but different end-result will not be accepted and ultimately damages the integrity and credibility of the consultation process itself.

Accepted papers are moved to the Accepted (link?) sub-forum. During this time papers are moved to this wiki and placed in a standard format (that we will need to devise). Once the group is happy with the specifications, and the milestones for the next version have been set, they are officially published and development cycle for the next version starts.

The remainder of the papers are moved out of Under Review (link?) back into the main white paper forum, unless they have been deemed to be something that can't or won't be implemented, in which case they are moved to Not accepted. Over time guidelines for what things are likely not to be accepted will be established, and also templates by which people can submit white papers.