Difference between revisions of "White Papers"
From Joomla! Documentation
m (forum link, new URL format) |
(Several markup, spelling and capitalization changes.) |
||
| (2 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | == Why a | + | == Why a White Paper Approach? == |
| − | A white paper is more or less a formal "feature request". | + | 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. |
First it's ''planned''. | First 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. | + | 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. |
Second this new mechanism is ''community driven''. | Second 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 the 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 millions of site owners. | + | 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 the 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 millions of site owners. An open and transparent process like this allows for significantly more people to have their opinions and ideas heard. |
| − | ==Who | + | ==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. | 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 | + | 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. | + | 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 | + | ==White Paper Guidelines== |
White papers must include at least the following: | White papers must include at least the following: | ||
| + | # 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.) | ||
| + | # An overview of the functional requirements or simply the goals that are to be achieved. (The 'what' needs to be done.) | ||
| + | # 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?) | ||
| − | + | These items do 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 accepted. However if you have the ability, 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 facilitates 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, consider setting realistic steps that can be achieved. Papers that would require a single effort of six 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 address these additional requirements if possible depending on your experience. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | Note that members of the Development Working Group ''will'' be expected | ||
==Submitting White Papers== | ==Submitting White Papers== | ||
| + | White Papers are submitted on a {{jforum|wp|special sub-forum|}}. 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 publicly 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 publicly 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. The forum is moderated, because experience learns that not all the feedback will be constructive. With this approach we make it possible for everyone to give input and 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 its implementation in a completely different direction that first thought. 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 different angle and having different goals). | |
| − | + | At this time, polls are not permitted. We want to encourage a process of peer review rather than anonymous voting. | |
| − | |||
| − | At this time, polls are not permitted | ||
===Special Exception for Minor Changes=== | ===Special Exception for Minor Changes=== | ||
| − | We are giving a special exception for | + | We are giving a special exception for minor issues that people might like to bring up, but that are too trivial to warrant writing a full paper on the subject. For these cases we will have a sticky thread for submitting minor issues. Moderators will monitor this thread and any issue that are deemed to need more input will be split off and a full White Paper will be requested. |
This thread will actually be closed during the review process simply to help with the logistics of processing it. | This thread will actually be closed during the review process simply to help with the logistics of processing it. | ||
==Planning== | ==Planning== | ||
| − | The process of submitting white papers when started will be an on-going process. | + | 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 | + | Authors will need to indicate that their 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. | The Development Workgroup will then perform a two-round process of accepting papers. | ||
===Round One=== | ===Round One=== | ||
| + | Each Development Working Group member picks his or 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, implementer 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 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. | |
| − | have received little or no input | ||
===Round Two=== | ===Round Two=== | ||
| + | From the 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 including the amount of effort involved. The group then assesses 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 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 result will not be accepted and ultimately damages the integrity and credibility of the consultation process itself. | |
| − | |||
| − | 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. | ||
| − | |||
| − | |||
| − | + | Accepted papers are moved to the ''Accepted'' sub-forum. During this time papers are moved to this wiki and placed in a standard format. 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. | |
| − | [[Category:Development]] | + | The remainder of the papers are moved out of ''Under Review'' back into the main white paper forum, unless they have been deemed 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. |
| + | <noinclude>[[Category:Development Working Group]]</noinclude> | ||
Latest revision as of 17:53, 1 December 2022
Why a White Paper Approach?[edit]
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.
First 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.
Second 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 the 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 millions of site owners. An open and transparent process like this allows for significantly more people to have their opinions and ideas heard.
Who Can Post White Papers?[edit]
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[edit]
White papers must include at least the following:
- 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.)
- An overview of the functional requirements or simply the goals that are to be achieved. (The 'what' needs to be done.)
- 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?)
These items do 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 accepted. However if you have the ability, 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 facilitates 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, consider setting realistic steps that can be achieved. Papers that would require a single effort of six 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 address these additional requirements if possible depending on your experience.
Submitting White Papers[edit]
White Papers are submitted on a special sub-forum. 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 publicly 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 publicly 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. The forum is moderated, because experience learns that not all the feedback will be constructive. With this approach we make it possible for everyone to give input and 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 its implementation in a completely different direction that first thought. 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 different angle and having different goals).
At this time, polls are not permitted. We want to encourage a process of peer review rather than anonymous voting.
Special Exception for Minor Changes[edit]
We are giving a special exception for minor issues that people might like to bring up, but that are too trivial to warrant writing a full paper on the subject. For these cases we will have a sticky thread for submitting minor issues. Moderators will monitor this thread and any issue that are deemed to need more input will be split off and a full White Paper will be requested.
This thread will actually be closed during the review process simply to help with the logistics of processing it.
Planning[edit]
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 their 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[edit]
Each Development Working Group member picks his or 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, implementer 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 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[edit]
From the 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 including the amount of effort involved. The group then assesses 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 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 result will not be accepted and ultimately damages the integrity and credibility of the consultation process itself.
Accepted papers are moved to the Accepted sub-forum. During this time papers are moved to this wiki and placed in a standard format. 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 back into the main white paper forum, unless they have been deemed 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.