[Opensource] Expresso documentation structure
Peter A. Pilgrim
peterp at xenonsoft.demon.co.uk
Sun Dec 7 14:53:28 PST 2003
maxxam at inetfreemail.co.za wrote:
> I am an Expresso newbie and I though that it would be useful if I gave some feedback on my experince with the Expresso
> documentation. I know that most of you are experienced Expresso programmers and therefore probably don't pay much
> attention to the newbie documentation.
>
> Firstly the newbie documentation is great up to a point. That point is getting the framework installed and some very
> basic apps running. From then on it gets really hard. Anyone using a framework like Expresso probably wants to write
> something more sophisticated than the simple DBMaint/appWriter type apps.
>
> The major problems with the documentation as I see it are:
> 1) There are far too many documents spread all over the place. In order to find out if something is documented it
> requires looking through about 50 different documents, the faq, the forum, the mailing list, the expresso CVS full
> checkout, the examples, the javadoc and the source code. This is a most time consuming process - 1-2 hours per
> iteration.
> 2) The documentation is often incomplete, wrong/old and just plain not there.
>
> I am suggesting the following to ease the pain for new Expresso programmers (instead of driving them away after the
> first doumentation experience as I suspect happens more often than not):
>
> - Consolidate the documentation into:
> a) User Guide: contains description of what Expresso can do and installation
> b) Developers guide: contains *all* coding development related documents. I.e. all of the documents that now appear
> on the jCorporate document site and all of the other various places they can be found into *one* document. Even if it
> has appendixes. This way at least you know if you've looked through this one document and can't find what you need
> then you know it doesn't exist - so look on the mailing list or in the code.
> c) Tutorials. Yeah I know these don't exist. Name one major open source success story that doesn't have a tutorial.
> d) Examples. Expresso *desperately* needs more exmaple code. I submitted an example to Mike R just a week or so ago
> and I'm not sure if it's made it onto the website, or even if it qualifies to make it onto the website. I think
> others, especially the Expresso gurus need to contribute more examples. Also the machine generated code of appWriter
> is really not a good introduction into Expresso and it's finer points. And then most people, myself included, were
> redirected by one newbie doument to an appWriter site that doesn't exist anymore. I don't have the prot 8080 problem
> either. (I believe that the new site is at www.datafundamentals.com).
>
Open source is typically undocumented from the level of no documentation at all
to very good. I was just reading a book "Art of Web Development" by Neil
Ford, Manning. No actually skimmed it in a bookstore.
http://www.manning.com/ford/index.html
Actually this book talks about Struts / Tapestry / Velocity and my curiousity
was piqued. The author talks about the level open source, pros and cons
of the framework. Reading this book in the shop confirmed by view,
that a framework or piece of software is only as good as the core
team of committers that are involved. If you look at Linux this is
true, starting with the eponymous Torvalds, and then the lieutenants
e.g Alan Cox.
Expresso has only had one ever "Father", Michael Nash.
He wrote a lot of the code in the framework from his web application ideas.
There was a lot of good ideas, and to respect Mike Nash was
way ahead of his time 2000/2001. His HTTPController
(which no long exists and was a subclass of the
DBController) and ControllerElement idea were invented before
Struts / Tapestry. As lead developer under his auspices
the code grew and grew, the committers did not or have
contribute enough documentation of the feature. The
best example of this is DBObject. This is not anyones
fault, it just happens in software development, and it is
sylistic issue. There is no "blame-culture" here
Matter fact he left his work behind and left it here for
us to develop onwards.
I think this is the crux of the problem. There is a lot
code that is not being used, still the ideas are good.
Some refactoring is going on e.g DBObject. But the
framework has to change I agree to live in a culture
with more innovative ideas. I expect some API code will
be delegated to history, during the "great refactoring
exercise" of 2004. Hopefully we will have time to be
really "XP" about this. That means writing proper
JUnit tests that illustrate examples of the API and
also write some sample code to show what to do and
how do it with the API. There should be a definite
"test first" attitude with the framework, but in the
first generation of the framework I do not think
this was applied, hence the big complaint from
"Max"
I would advise you all (including committers) to look at this
book ( or skim it in a bookstore) the later chapter 11
"Evaluating Frameworks".
> - Indicate in the documentation what version of Expresso it covers. That way when seeing an older piece of code you
> won't necessarily spend hours try to get it to run just because something was upgraded. I have felt the pain here.
>
This is committer issue. We really need a volunteer "Technical Author" here.
> - Scrap the online faq and forum - they're useless. All they serve to do is confuse and showcase eForum and eContent.
> Not what beginners need. They also dipict such a low level of activity it caused me to rethink my choice in Expresso.
>
FAQ required updating. A Wiki would be better. The forum is still useful
for developers. Last year can you believe that forum did not have
a search facility, so it was even more restrictive than before.
> - Make the mailing list more prominant. Took me two weeks to find out about it (I thought that the Forum was the
> mailing list!).
>
> - Remove the references to the Javadoc holding more secrets than the Developers Guide because it just plain isn't
> true. I haven't had any joy out of the javadoc documentation of what functions/objects do and how they can be used
> from an architectural viewpoint (or even from a detail viewpoint come to think of it).
Javadoc does need improving, but this is born from the fact that it is
part of the "first generation" (see above). The second generation
should be much improved.
>
> I think that Expresso can be an open source hit, however the folk at jCorporate need to focus attention on reducing
> the learning curve for newbies. It's not that Expresso is hard to understand, in fact the opposite is true. It's hard
> because it's hard to find out *how* to do things. As you all know, the more people that start using the product, the
> more success it will bring to all.
Only JCorporate can answer this. However when Mike Nash was there, he was
the dedicated human resource. At the moment Expresso is largely
volunteer project.
>
> After three weeks I'm on the fence. Should I continue with Expresso or move to something else. With this lack of focus
> on comprehensive doc's, what is the future of the product? I think the experts are painting themselves into a corner
> by not focusing on this issue. If the situation doesn't change, they will find themsleves as a small island who
> understand the product and the masses have moved elsewhere. I saw a post on the mailing list from 2002 sometime of
> someone else making the same points that I am. As I haven't been around for that long I can't say if things improved
> from the time of his post or not.
>
The product is only as good as the committers involved.
> I'd like to make a contribution to the Developers Guide. From a post yesterday some of you may know that I am
> struggling with the Expresso workflow. I have since figured out the answer to my number 1) question and have written a
> section that I feel can be incorporated into the Developers Guide. You can of course do whatever you like with it, but
> if it just ends up as another discrete document in another documentation list, then I certainly won't be tempted to
> write any more because then I will just have become part of the problem. I also hope that some of the experts who
> understand this stuff better than I will spend 1/2 hour correcting me and filling in the blanks. Had I had this
> document three days ago it would have taken me an hour or two at most to get workflow working. Instead it took me
> three days of hair loss.
I am working on some of the documentation and will be involved
in the DBObject code. There is even some things in Expresso
that I do not understand, the whole Registration thing is
still a bit confusing. When I starting programming with JobQueue
that was bloody confusing too. It was not documented and I ran
into problems like you said. The search indexer code that I wrote
for the eForum uses a Job Queue so I learnt the hardway too.
This is because the Job Queue is "Generation I".
Open source is not easy, nor as I expect Linux Kernel development.
If you want to be a Linux Kernel developer then you have got to
expect "hard" as in hard-core. For Expresso Framework some of
the API should be easier to understand.
>
> I'll send the document directly to Mike as I'm not sure if Word attachments are acceptable on this list.
>
> Then again perhaps I'm completely wrong and am the only one with this problem!
>
> Thanks,
> Max
>
When Mike gets back from holiday, there should be an
"Elrond Council of War" for Expresso Framework to outline
what we want the framework to be for 2004.
> _______________________________________________
> Opensource mailing list
> Opensource at jcorporate.com
> http://mail.jcorporate.com/mailman/listinfo/opensource
> Archives: http://mail.jcorporate.com/pipermail/opensource/
>
>
--
Peter Pilgrim
__ _____ _____ _____
/ //__ // ___// ___/ + Serverside Java
/ /___/ // /__ / /__ + Struts
/ // ___// ___// ___/ + Expresso Committer
__/ // /__ / /__ / /__ + Independent Contractor
/___//____//____//____/ + Intrinsic Motivation
On Line Resume
||
\\===> `` http://www.xenonsoft.demon.co.uk/no-it-striker.html ''
More information about the Opensource
mailing list