2008-07-16

Missing Books considered harmful

A very large percentage of of my customers are just starting to use Eclipse and Eclipse based technologies for their applications. So apart from having the basic 4-6 days training in RCP, EMF, GMF, etc they all have have one common and very important question: "Which books should we buy?"

And that question has become increasingly difficult to answer lately.

There are a number of absolutely good and noteworthy Eclipse books, but almost all of these are not up-to-date and that can be a major problem for people that need a good reference guide and best practices guide to Eclipse.

Almost all of the books on Eclipse are one or two versions behind the current baseline and that means the readers will not be able to take advantage of the new and improved stuff. And consequently they are rather frustrated when the only source to the new functionality is... the source.

Yes, I do know that many of the books in question are under revision and expected to be here any time soon, but even these revisions are delayed - in some cases as long as a year. And yes, I do know that the authors of technical books do not get rich from their work, so they have little incentive to update their books.


But there must be something that can be done about this. Just consider the number of books that are marketed by Microsoft on their many technologies and consider which role these books play in many developers life.
Before you start: yes, most of Microsofts software is closed source and consequently you need the books... but why should you have to read though 8-12 millions lines of code to understand just what the new and much improved APIs do?

I would suggest that we add a new criteria before an incubator project can graduate: there must be a book or at least a number of authoritative articles on the project. And for each new major release, there must be an official update of these...

Whether the foundation should be part of this work or not, I don't know. I can easily see arguments for both...

10 comments:

Chris Aniszczyk (zx) said...

Tonny, this is a real difficult problem because it takes a lot of time to write books and articles. The people most qualified to do this generally are the developers, but the developers are really busy either coding or just don't have a desire to write. A person who can do both is rare.

I'll talk to the other committer representatives about the topic of requiring a book as part of an Eclipse project graduation. I don't think it's practical to require a book be out, but maybe in the works at least. For example, I would love to have a book out on EclipseLink right now :)

Good topic :)

Chris Aniszczyk (zx) said...

And WHAT!? Jeff and I won't be able to retire after the Equinox and RCP books are out? Oh man! :P

R. Sanders said...

One thought: maybe a subscription site/service where the latest documents can be accessed. This would need to be via a third party, but if authors were encouraged to write based on receiving money, and the material kept a good balance between being up-to-date and being too disorganized... just one thought. This might also help with editorial oversight for articles: as there are lots of little articles and blog entries around, but if someone could concentrate on pulling them together it might be a big boost to new people.

nickb said...

+1 for not being able to exit incubation w/o a "Getting Started", "HOWTO" or "Newb's guide to this project" document... or three. Even a pile of wiki docs would help -- look at p2's collection of 55 articles!

Of course when you're a mature project with a shrinking number of committers, it's often hard to juggle supporting old releases, building new features for upcoming releases, and oh, yeah, writing a book. :P

Anonymous said...

@Chris, I do understand that it is very difficult to find people that can both code stuff - the right "way" - and document their work appropriately.

But having said that, I tend to consider the mentioned books and article an essential part of the end-user documentation. After all, we are not doing simple stuff that anybody could do Friday afternoon over a beer or two :-)

Regarding the pay: doesn't the work bear the payment in itself (something we say in Danish that might translate poorly to english...)???

Anonymous said...

@Robert, Getting the required documentation must be a simple one time payment for something tangible like a book.... Otherwise, I know many a IT department boss (CTO or whatever) that will back away from Eclipse...

I do see some sort of incentive for writers to be a good thing, though. Maybe the foundation could have some sort of booty for good articles. The review process can be simple +1 version currently used in bugzilla for many other things...

Anonymous said...

@Nick, maybe it is time to find a technical writer or two that can complete the books?

After all, this is what Microsoft, HP and many other wellknown software companies do to make sure the developers do what they are good for...

Kevin McGuire said...

I like the idea of requiring some level of documentation for project graduation (although a book is likely an unrealistic requirement).

Its the nature of publishing that the authors may not have time, incentive, or permission to work on new editions. So a radical idea: when people made publishing deals for books, there'd be a sunset clause where after a few years and the book sales had dwindled, the books would be posted on a wiki for others to edit. Thus the community could keep the material up to date. As I've never published a book I have no idea if such a thing can be negotiated, but from my point of view its the only realistic approach to keeping technical information up to date on an open source project.

Lee said...

@Tonny, re incentives:
How about "bonus Bugzilla votes" to community members who write an article/how-to?

Or some percentage discount on the EclipseCon registration? (Like 1% off registration for every How-To article you write that gets published on eclipse.org)

Of course, for extra Bugzilla votes to mean value, the issue that David Carver raises might have to be addressed (see: http://intellectualcramps.blogspot.com/2008/07/how-many-votes-is-enough.html)

Anonymous said...

@Lee, I think there are two types of incentives that "works" for developers: financial benefits and even more so recognition from your peers...

Regarding financial benefits: yes, but often you employer will pay for you EclipseCon participation anyway and many of the more active article writers have talks at EclipseCon and ESE and thus free participation...

Regarding recognition: one of the major driving forces of most people that work with/on OSS, is the change to be recognized by their peers as somehow exceptional in the field. So if the best articles and their writers are recognized at EclipseCon that will be of interest - a kind to how we currently recognize the best evangelist...