The Eclipse Management Organization (EMO) does a lot of reviews. We do a review when a new project is created. We do a review when a project wants to do a release. We do a move, continuation, termination reviews and more. For each of these reviews some form of documentation is required. The documentation (often referred to as “docuware”) describes the event being reviewed and provides pertinent data so that interested parties can learn what they need to know. This gives the community an opportunity to ask questions about the event, and—at least in some cases—challenge it.
When a project wants to do a release review, for example, the release review documentation provides details about the overall fitness of the project, community development efforts, bugs fixed, etc. A very thorough description of what a release review entails is provided in Eclipsepedia. The Eclipse Development Process is annotated with little gems like this for most types of review.
At some point in the now-distant past, it made sense that our review documentation was assembled as a presentation. After all, in the past, we would hold review calls in which the the project that initiated the review would walk through their slides. Over time, this practice changed to one of simply providing the slides for all to review and then being available on a review call to answer any questions and discuss the review. More recently, this has evolved into a practice of making the slides available and inviting the community to ask for a call to discuss the review; today a review call is only held if it specifically requested.
The use of slides for review documentation has been bothering me lately. It’s just not the right format for reviews given the changes that have occurred in the review process. I’ve started encouraging projects to provide review documentation in HTML format. Actually, we’re doing better than that. Anne and I have started to create some review documentation templates that should reduce the amount of effort required to that of determining content.
I am further encouraging new projects to use their proposal document for their creation review. Wim Jongman, with his evolving proposal for the Eclipse Newsreader/Salvo project, as taken another interesting step of building the project proposal in the Eclipsepedia wiki. I still haven’t decided if this will change our workflow. As of right now, the project proposal hasn’t been handed over to the EMO. Does it just stay in wiki? What happens when the page is changed? I guess that changes are tracked and that the document “owner” can undo changes that they are not comfortable with, so this could work. Our “What’s new with Eclipse Projects” page will need some modification to handle wiki-based proposal documents, but this is relatively easy work. This is an interesting proposal, by-the-way, I encourage you to take a look at it.
HTML documents are the first step. I envision this evolving with time as there are some great opportunities for automation. But let’s take the first step. Thoughts?
