| Re: [cross-project-issues-dev] plan best practices |
First, thanks to everyone who has contributed to the standard plan format effort. This has been a great example of the community coming together to achieve a common goal for the good of everyone. I read through
http://wiki.eclipse.org/Development_Resources/Project_Plan
some of the plans already available, and the various related bug reports in particular
https://bugs.eclipse.org/bugs/show_bug.cgi?id=215301
A few questions came up while putting together the Equinox plan...
- What is the intended use/audience of these plans? In my projects we have always attempted to address the consuming community and attempted to paint a general picture of the kinds of significant new directions, functions, etc that are on the table for the next release. In looking over the DSDP and DASH plans I was struck by how detailed they are. There are a great many items (bug reports) listed. Given the volume and the format (many entries starting with the same [tag]), the document is not very consumable IMHO. People can find out what is going to be worked on in any given milestone by doing a query but that is raw information, not a considered and crafted plan.
- What should the community expectations be wrt the plans changing? Our plans have always changed say 4 times as the dev cycle goes on. This IMHO a positive attribute as it more accurately reflects reality as reality unfolds. However, where the plan is composed of bug queries for particular [tag]s (or the like) there appears to be a danger of anyone in the community unknowingly putting something on the public plan simply by putting [tag] in the summary line. Change is good but too much churn and fluidity undermines confidence.
- To address the above two concerns I propose that we explicitly state a best practice for project teams to use the "plan" keyword (or any other explicit and relatively exclusive marking mechanism) to clearly and explictly mark bug reports as being for the plan. Following this approach we would likely end up with fewer plan items and less churn. Both changes would increase the consumability of and confidence in the project plans.
- What do we think plan readers want to see and should expect? I saw some discussion about having more text related to the plan items in the plan itself but no real conclusion. Currently the rendering shows only the summary (I suppose that is a conclusion :-). Again, from a consumability point of view this is less than optimal. It requires a lot of clicking and makes it hard to see the big picture. I've been to countless meetings where people sit down with a printed copy of the plan and talk about the different items. If all the real content is had only by following a link, ... In part this is a rendering question but from a best practice point of view, what do we think plan readers want to see and should expect? If you walk up to a project about which you know little, what do you expect from their plan document? I expect to see some sort of digested form of the raw information that tells me the intent, direction, challenges and what problem is being addressed. Imagine trying to get funding based only on your plan document. Again, we can have links to all the gory details. Make the simple thing simple and the hard things possible...
- Should it be easy or hard to create a plan document? (sucker question) The main plan wiki page
http://wiki.eclipse.org/Development_Resources/Project_Plan
highlights a plan template designed for "little HTML" and implies that the "lost of HTML" approach is for legacy folks. From a best practice point of view, should plan authors be producing rich plans or machine generated queries? I guess my point here is that while people are free to choose which xml tagging scheme they use, we should be encouraging them to create good looking, easy to read plans. Guiding them towards archane XML namespace markup and "prefix"ing is likely to make crafting such a plan appear unattractively hard. I suggest that we reorient the main plan page to guide folks through the simple path first with off-shoots for the non-XML-averse folks.
Again, I very much like the path we are on. These comments/questions are intended to expose and refine the plan crafting best practices with the end goal being more consumable and informative plans that are produced more easily.
Jeff
_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev