[Opensource] Expresso documentation structure

[Max]

Hi Mike, Sandra

> 
> Actually that would be a false assumption.  I actually spend several hours 
> a week working on documentation.  With this version of Expresso we have 
> successfully continue to improve the Java documentation, filled out quite a 
> few sections in the developers guide, and added a brand-new tutorial thinks 
> to Tino.  And I'm not the only one that has been adding documentation.  I 
> see several commits per week going into EDG or other documentation.  Now I 
> won't argue that documentation could continue to use serious 
> improvements.  But any veteran of Expresso knows that it is nowhere near as 
> bad as it used to be.
> 
> So rest assured that your complaints are not fallen on deaf ears!

That is indeed good to hear. Obviously I have not been using Expresso for long enough to have seen the improvements 
made.

> >   c) Tutorials. Yeah I know these don't exist. Name one major open source 
> > success story that doesn't have a tutorial.
> 
> Actually, Tino has written a tutorial that is available on site that leads 
> you through some basic steps and Expresso have you been able to find this?

No, unfortunately I have not seen this yet. I checked the site carefully (or so I thought) for a tutorial when 
starting out a few weeks ago and couldn't find one. My apologies to Tino, but this also highlights the problem of 
finding the right documentation amongst all of the other doc's.

> 
> >- 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.
> 
> For the developers guide how you propose having the set up?  Do you want to 
> see a subtitle in each section covering the version of Expresso that it was 
> originally written for?  In that case, how are we going to iterate over the 
> various releases to be able to verify that the instructions are up to date?

Is this not a problem that has been experienced and solved by the open source commnuity yet???

I understand the logistical problem of keeping the documentation in line with the current version, however it would be 
useful to know which version the source code examples were written for as then you could tell that if your code 
doesn't work then perhaps something has been upgraded. For example on page 104-105 under the section "Jobs Expresso" 
none of the run method examples given call super.run(). My job refused to work until I put that line in. I found this 
by searching through the expresso code. I'm still not entirely sure if this is a documentation problem or some other 
factor.

> >- Scrap the online faq and forum - they're useless. All they serve to do 
> >is confuse and showcase eForum and eContent.
> 
> I believe that scrapping the forum would be extremely detrimental to the 
> community.  Approximately 80% of today's posts and assistance is 
> transmitted through the form.  And the online search engine for the form 
> helps us get to answers we have posted previously.

My experience was quite the opposite but that is probably circumstantial. I found 80% of my answers (that were 
answered that is) in the mailist and only 20% in the forum. I deduced that the forum was of less use.

Perhaps the answer is to scrap the maillist then? My point is really why have both - it requires two searches? Can't 
the mailists archives be loaded into the forum?

BTW, it's also difficult to search the maillist as the search urls generated for archived material do not point 
anywhere. I have been having to make a note of the date and subject and then so search through the archives.

> >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
> 
> Now I must say that you are one of the first people have posted a complaint 
> letter like this and immediately became part of the solution!  Bravo!  I 
> have contacted you about getting this included and you shall see it soon.

I apologize for being critical at times. I do however always make an effort to make some constructive input if I am 
going to critisize. Feel free to flame me if I don't.

In your note to me, or perhaps it was in Sandra's reply on this topic, you ask if I can make the changes directly in 
docbook. I don't mind doing this at all however I am an pre-web programmer and my eyes hurt the moment they lay eyes 
on html or xml code. I thought LISP was bad having earned the nickname of Lots of Irritating Single Parenthesis!

I found a free docbook word processor type editor called XMLmind. It can be downloaded at www.xmlmind.com. When 
loading the Expresso EDG it gave some warning saying that certain features would not be enabled, and loaded the 
document OK otherwise. Is it OK to use this, or is there another word processor that can be used to edit the EDG? I 
must admit that when I read the section on EDG contribution and XML and SGML popped up I dropped the idea immediately. 
Perhaps others also have the same aversion to learning docbook and hence write separate documents/articles?

Thanks again for the help,
Max