[News.eclipse.foundation] Re: E4 / SWT 4.0

[Eric Rizzo <eclipse-news@xxxxxxxxxxxx>]

Ed Merks wrote:
<lots of good stuff>

I agreed with and appreciated so much of what Ed has said in this 
thread, but this part jumped out at me:

> When I consider this issue closer to home, I stop and think about how 
> many times folks have complained about the need for more and better 
> documentation about EMF.  I end up listening until I get frustrated but 
> being ultra diplomatic and wanting to avoid controversy I keep silent.  
> Oh wait, that's an idealized version of me!  :-P I point out somewhat 
> bitterly that I have a tiny team of people who just can't keep up.  No 
> matter what we do, someone will complain it's not enough.  If I have my 
> two developers spending 3 person years working on a book, you can be 
> guaranteed that I'm taking documentation seriously, and that it's 
> happening at the expense of development work.  Of course I fully expect 
> to get complaints that the book costs money and what horrible exploiters 
> of open source we are to dare to charge money for a book that ought to 
> be free.  And that's on top of complaints that the wish list isn't all 
> getting done.  Oh well, if folks aren't complaining about your project 
> then either your work is be done or more likely your work is irrelevant, 
> because relevant work is never done.

Right you are; you and your team should be glad there are so many 
requests and personal priorities thrown at you. It's kind of like the 
saying, "I welcome growing old, because the alternative is very 
unpleasant" ;-)

However, the choice you describe to dedicate 3 man-years to writing a 
book is an excellent example of the kind of opaqueness that I think 
needs to be addressed. Ed, if you'll indulge me, put on your thick skin 
for a moment as I blatantly criticize a decision you made...

Why was that huge investment made into an effort that is largely 
obsolete? I mean, my perception is that books are no longer the source 
of choice for most developers because the production cycle is just too 
long and their accessibility is just too limited. That time would, 
IMNSHO, have been much better invested in producing online documentation 
of the form that has been proposed in this thread. Plus, your team could 
have benefited from the community by providing the foundation on which 
the community could more easily build. What I mean is that one of the 
biggest hurdles to writing docs is building the momentum, the outlines 
and other fundamental structure to give people an idea of how to write 
the details, examples to look at, and a list of what remains unfinished 
(and thus what needs their help). By doing it in book form, your 2 
people were on their own with almost no community help.
Not to mention that the book is already behind (has it even been 
published yet?) as EMF 2.4 is on the doorstep.

To fit this into my broader point, I'd say that if the decision of how 
to spend team's time on documentation had been more open and advertised, 
I would undoubtedly have made the argument above to try to influence the 
decision. Maybe you considered the points in my argument on your own, 
maybe you didn't; I don't know. Unfortunately, I also don't know of any 
mechanism that would have allowed me, as an interested and motivated 
community member, to contribute to that particular decision. See what 
I'm getting at?

BTW, I'm guessing that the choice for doing a book instead was not based 
on financial motivations, since every author I've ever asked tells me 
that you don't make money writing a book (especially a technical book).


> So absolutely we need better documentation.  We need better getting 
> started information and better website organization to make it easier to 
> find.  We need a constant stream of more and better.  But please 
> consider the extent to which the community itself can help with these.  
> Repeating the same message over and over will not help.  I can't stand 
> to hear complaints about EMF documentation anymore, so folks might not 
> like my reaction, but let them walk in our shoes for a few miles...

Please don't let the endless stream of requests and "psuedo-bugs" 
discourage any Eclipse project team members. I think that is a message 
that the community should send to the project teams, in exchange for the 
project teams' listening to what we have to say about this topic and others.
I wonder how I (and other community members) can broadcast that message 
to the project teams, so they don't think all we do is ask, nag, and 
complain...

Eric