| [News.eclipse.foundation] Re: E4 / SWT 4.0 |
Eric,
Comment below.
Oh no. I'm not a pachyderm!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...
It wasn't supposed to be a huge investment. Ask Dave and Marcelo. The schedule just kind of kept stretching and continues to do so.
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.It's online at Safari...
That time would, IMNSHO, have been much better invested in producing online documentation of the form that has been proposed in this thread.See, I knew it was coming.
Plus, your team could have benefited from the community by providing the foundation on which the community could more easily build.It's true.
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.Yes, kind of sad hey.
Not to mention that the book is already behind (has it even been published yet?) as EMF 2.4 is on the doorstep.That's the second time it's happened. Now writing appendices to cover 2.3 things (generics was a biggy) and 2.4 things like content types and URI converter enhancements are needed... But the end is nigh!
At that point I'd have been under the impression that it would be a 2/3 of a person year investment.
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.Certainly such things were considered, but a book seems to have some value as well. It looks good on the resume too. :-P
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?Yes, we've not been so open. Though at the same time, in my personal life, I don't appreciate back seat driving...
This one will be different. It will be a best seller! :-P I'm not planning my retirement just yet though...
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).
Try nagging and complaining less. Hehehe. Just kidding!
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