Hi Derek,
Yep. Saw the newsletter too :)
I would add to that that as important as documentation (both breadth and
depth) is, it is equally important to have ready access to the
documentation. This includes "roadmaps", "trails" and indexed search
engines. Having a wizbang tutorial on interacting with web services in
CForms (as an example) is of little use if the people who would benefit
from such a tutorial don't even know that it exists, let alone how to find
it.
Ian
It's better to be hated for who you are
than loved for who you are not
Ian D. Stewart
Appl Dev Analyst-Advisory, DCS Automation
JPMorganChase Global Technology Infrastructure
Phone: (614) 244-2564
Pager: (888) 260-0078
"Derek Hohls"
<[EMAIL PROTECTED] To:
<[email protected]>
a> cc:
Subject: How much is enough?
02/25/2006 09:28
AM
Please respond to
users
This question has come up before, and will no doubt come up again -
how much is "enough documentation" for a web application development
platform? A recent Ellipse newsletter* asked this question and they
argue that trust and confidence in its usage come from understanding:
"the one benefit here that a lot of developers value, even if the framework
isn't perfect, is that they feel confident in their ability to maintain the
framework and fix bugs. They know exactly where the ResourceBundle
loading is done, so there is no search necessary. They know to open up
LeakyResourceBundleUtil.java and fix it, and because of this they feel
confident; they can be accountable. What scares a lot of developers is
using some well known framework and having the inevitable bug show
up and then having no idea how to fix it. Mailing lists can help, but
ultimately the bug could be in your huge mess of code which you
can't share with anyone else to look at. Scary."
I wonder if many people know and respect Cocoon as a stable and trusted
framework; if yes, why, and if no, why not??
"How do you get them to feel confident enough in the platform that they
can throw all their eggs into the basket and say "We are in this through
thick and thin, I love you."? You provide documentation. In fact, you
provide so much documentation that your documentation could kill a
small horse. You document everything, not just Javadoc, but features,
how-to's and styles of coding. You try to provide so much documentation
that someone could search for "Splash screen", and not just find the
Javadoc on Windows, but actually find a document on how to write a
splash screen using your framework."
"When you make things accessible to developers, don't waste their time.
Grease the wheels and give them the controls, they will love you for it.
Is this too little too late for everyone else? God no. Keep it up I say,
mush
mush! The more documentation out there the more everyone is going to
strive to improve and reuse these frameworks. At the end of the day, all
we as developers want is something that we can trust our next app on."
Food for thought here...
Derek
*EclipseZone Weekly Newletter, dated 2006-02-24
--
This message is subject to the CSIR's copyright, terms and conditions and
e-mail legal notice. Views expressed herein do not necessarily represent
the
views of the CSIR.
CSIR E-mail Legal Notice
http://mail.csir.co.za/CSIR_eMail_Legal_Notice.html
CSIR Copyright, Terms and Conditions
http://mail.csir.co.za/CSIR_Copyright.html
For electronic copies of the CSIR Copyright, Terms and Conditions and the
CSIR
Legal Notice send a blank message with REQUEST LEGAL in the subject line to
[EMAIL PROTECTED]
This message has been scanned for viruses and dangerous content by
MailScanner,
and is believed to be clean.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
