As you all are aware, I've been putting most of my recent Hackystat energy into
documentation: not just at the level of explaining the current system, but also at the
level of developing a Hackystat documentation framework that allows documentation about
future extensions to the system to be seamlessly integrated with the existing
documentation.
Here's an article from a person who claims one reason Eclipse has been so successful is
because of the quality of the documentation, and that the amount and quality of
documentation is a key success indicator for frameworks in general. If he's right, then
it seems like we're on the right track!
Cheers,
Philip
------------ Forwarded Message ------------
Date: Friday, February 24, 2006 1:24 PM -0500
From: EclipseZone News <[EMAIL PROTECTED]>
To: [EMAIL PROTECTED]
Subject: Choosing a framework you can rely on
The real motivation for picking a framework is based on two things: trust and
accountability. I know this sounds ridiculous, we are techies, we choose things
based on
their technical merit, sometimes even their whizz-bang! Do we though? Do we
really think
that is enough when your boss comes to you and says "Ok, I need you to build an
absolutely bullet proof application for a government agency where security and
stability
are of the utmost importance.” Do you even consider using that cool
SourceForge or
JavaForge project? Are you too scared to even imagine what would happen if the
system
crashed, kept crashing, or got hacked?
Let's say you took the risk; the XYZ Framework project is just too cool to pass
up and,
besides, you want to learn it. What happens when you get past the design stage
and get
into the heavy coding stage? What happens when you are 3/4 of the way through
it and find
out that there is a huge design problem with how sessions are handled? Maybe
you find
it's impossible to totally secure access based on how the framework handles
flow control?
Now what?
Now, keep in mind I'm not equating commercial to stable; I'm only making a line
in the
sand between "new, cool project" and "old, robust, tested project". I've been
giving this
a lot of thought recently, as I am currently in this position, and I think a
lot of
developers go through this same internal dialog. You want to know the real
reason why so
many developers "grow their own"? Because they don't understand what is out
there. I
write Riyad RCP because I don't understand how Eclipse RCP works. That is,
until I get
months into Riyad RCP and go "Oh, now I understand why they do that with
Composites... go
figure." Now it's too late to stop, too much work has gone into it.
Think of the jobs you have worked at where you inherited some legacy framework.
Isn't
everyone's explanation for it something along the lines of "When we started
this project,
none of the options out there did what we wanted.” Now you're left
sitting there
staring at basically a text book app and thinking "Yes they did...” So
what
happens? Accountability and trust is what happened.
If a developer has to put his trust in something and he's relatively sure of
his skills,
I think a lot choose to put their trust in themselves. "I will write a
fine-tuned
framework specifically for this app; it will be so much more efficient then
general-case
frameworks." What really ends up happening is that his intentions start off
good enough,
but as the framework stage of development drags on, and managers want to start
seeing
demos the inevitable happens. The project gets rushed out the door in a very
incomplete
state. However, 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 develo! pers 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.
If you sat someone down in front of a huge framework, say the Eclipse platform
with no
documentation and they banged out an email client that threw a NPE every 10th
time
checking mail and asked them to fix it, a lot of developers would balk at that.
"Oh god,
I have no idea where to look. I should have written my own framework."
How do you combat this? How do you get people to stop reinventing the wheel?
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
Window, but
actually find a document on how to write a splash screen using your framework.
This is exactly what the Eclipse developers have done and continue to do. This
is the #1
complaint against using alternative frameworks like NetBeans even from the
Eclipse 1.0
days. There was no contest when it came to the level of documentation provided
by the
Eclipse group to learn their platform, every tiny part of it, in and out.
I have to say with a certain level of confidence that this is 85% of the reason
that
Eclipse steam rolled the competition out of the gate. 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. I can certainly see the bulleted lists, the framework
comparisons
and the mailing list arguments: "NetBeans has supported that forever! Spring
RCP has
supported that forever! MyRandom RCP has supported that since its pre-alpha
release!" The
point is, no one knew that. There were one, two or three "Getting started"
guides, maybe
a "Starter tutorial" here and there, but where were the "Splash screen how-to"
or the
"View synchronization" tutorials or even the random 10 "Sample application"
guides that a
developer could read and extract just enough from each one to map it to his own
needs?
Well, a few years ago, this style of! documentation was no where except in the
Eclipse
camp. Now NetBeans and the other frameworks are pumping out some excellent
tutorials.
Folks like Roman Strobl are spending their days creating web casts, screen
casts, quick
tutorials and blog entries covering all the nooks and crannies I'm talking
about. This is
what we need: giving people editable appetizers of information that they can
convert to
bigger apps, or just have fun with.
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.
When I originally wrote this article it had a strong web framework undertone to
it. I
believe this is because the barrier to entry in the web framework arena is much
lower
compared to a good client side framework like NetBeans or the Eclipse platform.
That's
not the type of thing you spec out in a weekend and have a beta running by the
next week,
but all the arguments apply. Think back to around 1998. Was there even any
framework that
people could consistently suggest to one another to use for any client side
app? I'm not
aware of one. Because of this, I can only imagine the number of legacy
frameworks that
have been created over the years to solve this problem in-house that we are
never made
aware of. At least with web frameworks, most of them end up in easily
searchable arenas
because of their generic nature (handling requests). Client side apps can be
fine tuned
for an extremely specific purpose, as we saw with early Eclipse releases where
the
platform wa! s clearly tuned to an IDE. It takes work, a lot of work, to try
and dream up
and expand the support for something like that to encompass all the possible
use cases.
As we move forward it's nice to know we have a few mature choices so we don't
need to go
down that path again and again.
Well, we are at the end. I appreciate you reading this article and I hope you
take
something away from this. The key is documentation. The reason I think this is
important
is because I am a sucker for homegrown frameworks. I like writing them, I like
using them
and frankly every great framework we use right now was born out of an open
source startup
at some point. Because of this, I want to encourage people to still create
them, don't
hang your head and think "Oh it's been done before" and give up. If you do plan
on
writing it, don't forget to document it. Give us examples, tutorials,
explanations and
screenshots. God knows we love screenshots. Who knows, you might be writing the
next
Hibernate, Spring or Struts right now and not even know it.
Until Next Time,
Riyad Kalla
[EMAIL PROTECTED]
