Review Documentation Format Changes

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?

This entry was posted in Community. Bookmark the permalink.

2 Responses to Review Documentation Format Changes

  1. Dave Carver says:

    Actually, Wayne, the wiki has been used as a colaboration point for a variety of proposals before they get submitted to the EMO officially. With WikiText one could even go through and PDF up the official proposal so you have a snapshot of it from a point in time.

    I would actually probably encourage the use of the Wiki for project docuware as well. For many of the same reasons, once it’s ready it can be PDF’d using wiki text, and the community and committers can help with the maintainenance of the documentation.

    I still prefer DocBook, but wiki text is an easier sell.

    A simple google search on: wiki eclipse proposal

    will turn up many proposals that are in various stages on the eclipse wiki.

  2. John Arthorne says:

    I actually like the slideware format (PDF), at least for annual release reviews. The review material is a frozen in time snapshot of a project, so a dynamic medium like the wiki doesn’t add much value (except for the 3-4 days when the data is being prepared). And, although we don’t present these at release review calls, the slides still do get presented in other venues – at conferences, internal company reviews, etc. A slide also forces the author to be concise, and not produce some rambling or exhaustive content that makes the material take a long time to read. I can skim through the review slides for a project and very quickly get a good idea of the state of the project. PDF’s are also easy to store/archive, easy to read offline, print nicely, etc.

    Perhaps it would help if you explained the advantage of HTML over PDF for review material – is it supposed to be easier for the author, for the consumers, or who?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s