Bjorn just posted his first draft of The Three Laws Of Eclipse, ostensibly in response (in part anyway) to my perceived piercing from yesterday. Clearly not everyone was amused by my attempt at levity, and for that I'm sorry. That was not my intent.
In my humble opinion, The Three Laws is *EXACTLY* what we need. Something simple, concise, and easily referenced. (Unlike the rambling blog entry that will now follow.) ;-)
A couple of years ago I took a course about presentation skills called Think on your Feet (developed by McLuhan & Davies -- yes, that McLuhan), and one of the big things it stressed was what I'll call 'the rule of three':
- Three bullets to a section, three items on a slide.
- Three aspects of a topic (points in time, degrees of complexity, etc.).
- Three parts of a talk (intro, content, summary).
The human brain works well with the number three, for many reasons I won't bore you with. If you have a chance to take the course, I highly recommend it.
The reason I mention it is because the 'Three Laws of Eclipse' works perfectly in tune with the guidelines from that course -- you have three major rules, and the rules break into no more than 3 subpoints. This would work great as a powerpoint (for execs, PMCs, ID people, lawyers, policy people) and also as a quick wiki/webpage, as currently formed (for the geeks). Different audiences, different format; same content, same themes.
Because it's simple, it's memorable. Because it's memorable, it will stick with people.
And because it will stick, we'll stop feeling that the rules change too often. Or that there's too many.
Just for the sake of contrast, have a look at this 29-section legal-ish-style document.
Now, look at this page, where we find an explanation and history (in the linked bug) about why the document was changed, and everything relevant is conveyed in 3 (well, 4) easily-digested sections.
As a side note, perhaps annual changes aren't too often. As David says, the need for change is normal. Perhaps, as Mik points out, the problem is communication. This is IMHO twofold:
a) announcements of changes are not communicated to Joe Average Committer -- this could be my fault for not being subscribed to the right mailing list. Should these be done on cross-projects-issues-dev@ and/or the eclipse.org-planning-council@ lists? Or as a committer-wide announcement like the notes Denis sends once in a while about outages and new infrastructure? I'd say all of the above.
b) changes (due to (a)) seem to happen without a stated reason for the change. Again, this could be just the way my brain works: I need to know WHY a change is happening, even after I've accepted it's a good thing. And I need to be able to easily look up when and why so that when I've forgotten something (as I am wont) I can be shown the error of my ways by my own search or that of a friendly reminder from Bjorn. (This works both ways -- I nag Bjorn, he nags me, and over time we both fix things and improve. Win-win.)
So while I could probably pull the CVS history of documents and see when/why, it's not nearly as friendly as having a quick note sent to the committership at large saying "this rule has been changed from ___ to ___ because of problems with ____ so we're trying a new approach this year." Or better, having a bug to point at, like this page with this bug.
Oh, and just in case anyone out there thinks that from up on this pedestal of mine I don't strive to practice what I preach, contrast before with after, when I realized that the Modeling Releng doc had gotten too big for wikipedia to handle it, much less human users. (It's still too damn big, but hopefully more manageable when chunked up into smaller docs.) I'm open to suggestions if you have a better way.
Seems that 43 years later, it's still true. The way you convey information is often more important than the information itself.
