I'd also like to clarify a few things.
First off, I hope that the Eclipse Rich Ajax Platform (RAP) guys don't feel like I'm picking on them. My RAP examples are just that: examples. To those of you who stopped by and replied: thanks for taking criticism in stride; it is a mark of a true professional. Kudos.
I hoped that by contrasting the documentation of RAP and the Google Web Toolkit (GWT), I could highlight exactly one thing. Good documentation is the single best investment that a development team can make in usability. In fact, when I propose that my team choose between competing technologies, the choice has oftentimes come down to discoverability rather than technical merits.
If we choose a sparsely-documented technology, senior developers first take a crack at it, taking a week or three to dissect the technology and learn everything they can about it. They then take it to junior developers, teaching them hands-on. After that, implementation still takes a great deal of handholding by our senior people - people that, all things considered, have much better things to do with their time. Eventually, the team splits up into gurus and neophytes and only certain developers are willing to touch certain parts of the code base. Ultimately, the result is rarely clean and often buggy, requiring an extra iteration to clean up before going live.
A well-documented technology, in contrast, puts developers on a much more even level. Junior and senior developers can learn simultaneously. Code develops an extra sense of mobility as everyone feels confident with the entire code base, and the end result is a more cohesive, more robust product.
In short: good documentation allows developers to focus on solving an actual business problem.
Unfortunately, most open source projects I've used have been badly, badly documented. I understand that documentation is difficult and extremely un-sexy. I still can't stress enough that for me, as a user, the next major step forward for open-source - to promote usability, gain legitimacy and increase productivity - is to focus on documentation.
And for the record: I am more than happy to help contribute. Unfortunately, there's a bit of a catch-22: I can't document what I don't know, and I won't know until there is documentation. That said: if anyone ever feels that there is something that I can do to help, this is an open invitation to get in touch with me.
As for the systemic problem of community-wide documentation, I do have some ideas. I've already started writing that post and will publish as soon as I can.
No comments:
Post a Comment