[Opensource] Expresso documentation structure

[maxxam at inetfreemail.co.za]

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).

- 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.

- 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.

- 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).

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. 

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.

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'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