[Opensource] Expresso documentation structure

[Michael Rimov]

At 05:00 AM 11/26/2003, you 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.

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!



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

Yes I understand what you're saying, I have successfully folded in several 
documents into the developers guide consideration and will continue to do 
so in future releases.  My ultimate goal is to have a fully indexed 
developers guide for easy searching as well.


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

The idea of a user's guide with all the miscellaneous usage information is 
pretty good idea what to the rest you guys think?  What you the rest of you 
think about combining the rest of the documentation into the developers guide?




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

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


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


>Not what beginners need. They also dipict such a low level of activity it 
>caused me to rethink my choice in Expresso.

I'm not sure what you mean here there are quite a few posts on form everyday.



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

Believe me, they have!  says that particular time the developers guide 
probably has doubled in size including more examples, comprehensive 
information, and diagrams (useful diagrams were essentially nonexistent in 
previous versions).



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


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

It will become part of the developers guide as soon as I am able to convert 
it to docbook format.

                                                 -Mike (R)