RE: Barracuda docs....

Hi Christian,

See comments inline below...

At 08:19 AM 2/24/2003 -0500, you wrote:
>Hi Jake,
>
> > At some point we need to figure out what we want to do with Barracuda's
> > docs.  The way things are is not overly manageable.
>
>Can you clarity exactly what you mean by "not overly manageable"? I _think_
>you're referring to the complex HTML introduced by the nested tables, but
>perhaps you have something else in mind too? I want to make sure I
>understand exactly what you perceive the issues to be...
>
>My general thought is that the complexity of the current markup could be
>greatly simplified simply by using stylesheets.

This would definitely be an improvement.

>The advantage of keeping the docs in standard HTML is that it allows us to
>use HTML editing tools to edit/modify the docs (FrontPage, Mozilla's HTML
>editor, etc.) So, a basic requirement for me is that whatever docs solution
>we come up is GUI editable in something other than just textpad. Obviously,
>not everyone wants (or should have) to use a gui markup editor, but those of
>us that do want to take this approach should be able to...because it is a
>very fast way to generate docs.

It may be fast, but FrontPage produces some of the messiest possible 
HTML.  It is very difficult to read in a text editor.  Tools are fine if 
they work.  I know you feel that FrontPage works for you, but it makes it 
so things don't work for anyone else.  When this was brought up before, 
Diez agreed with me that it should be simple to write the docs in a plain 
text editor.  The way FrontPage mangles the markup makes that very 
difficult and deters outside contributions to documentation.

>So what I'd propose reworking the current format using style sheets to
>greatly simplify the markup format - that way those of us who have editors
>can continue to use them, and those who don't can edit by hand.

Yes, this would be good, but HTML will always impose a particular 
structure.  I have provided examples what is possible with stylesheets ( 
http://www.visi.com/~hoju/barracuda/barracuda.html ).  However, there is 
always still some structure imposed when you use static HTML.  Using XML, 
the entire markup structure can be modified for the whole site in an 
instant without using a GUI tool.

>Are there other benefits or advantages of a system like Forrest? (I just do
>not see much point in storing them as xml...but maybe you see something that
>I don't).

Like I said above, you can modify the structure of the markup dramatically 
without using a GUI tool.  Instead, it can be done using our Ant build.

That said, if Forest (or the like) isn't agreeable, I guess we won't use 
it.  It was just a suggestion about using an existing site management tool 
that is being used by a number of projects.  But if we do just use static 
HTML + stylesheets, we need to make sure that we aren't also using spacer 
images, <font> tags, tables for layout,  and the like.  It needs to be 
valid (XHTML) and *clean* markup.  If the GUI tools can't provide for that 
requirement, then out with the GUI tools.  If they can meet the 
requirements, more power to them.


>Final comment...as much as the docs need to get updated, there are other
>things that really need to get done first.

I agree, but if there are some who would volunteer to do this in parallel, 
then I don't see why this can't be done at the same time.  Obviously, for 
those of use who have access to make changes to the server, what you have 
below is priority.

>a) we need to revamp the contrib structure (I think we talked about this,
>but I don't think we every actually implemented it yet)

I'm really going to miss the way the contrib apps currently work.  Try 
this, for example...

ant contrib -Dsubproject=all -Dsubtarget=catalina-install

That will build Barracuda, build the main contrib stuff, and then build and 
install both Diez' and Stefan's projects into Tomcat.  All that with one 
little command.

I'm not saying we should keep this.  I know it has already been discussed 
at length.  I'm just proud of how slick it works and am going to miss the 
functionality :-(

>b) we really need to get our daily builds and downloads system up and
>running

definitely!

>c) we need to get the barracuda.enhydra.org site redirecting to
>barracudamvc.org.

most definitely!

>d) we need to get another major release out (with the newest version of
>xmlc?)

I wouldn't hold your breath on this one....at least not for too long.  As I 
understand it, the current approach for the 2.2 release is to wrap Xerces 
into XMLC.  As far as I could tell, 2.2 was nearly ready to be released 
until this decision was made.  I'm not sure how much, if any, progress has 
been made in this effort?  When it is released, it should make it that much 
simpler to build apps with XMLC because there *shouldn't* be any more 
collision with existing Xerces packages which means that we *should* be 
able to just put XMLC into WEB-INF/lib and not worry about putting an 
XMLC-specific version of Xerces in a shared classloader.  W'd just use 
whatever is there already.  This will simplify things greatly but, again, 
it may be a bit before it is out.  I would ping Richard or David to  see if 
we can get an approximate estimate for time-of-release.

>e) we need to make a concerted effort to get the word about Barracuda out,
>by doing press releases, announcing on various lists, etc.

I have been doing it on the Tomcat-user list when people are looking for 
frameworks or solutions to certain problems but I know that doesn't 
advertise Barracuda as far and wide as we'd like.  BTW, I did submit the 
Barracuda list for archiving on http://marc.theaimsgroup.com/ , however, I 
never got a response.  I'll have to try again.

>I think the docs need to be updated somewhere around d or e, but I'm really
>more interested in getting the other items listed above resolved first.

yep.

Jake

>Just my .02...
>
>Christian
>----------------------------------------------
>Christian Cryder [[email protected]]
>Internet Architect, ATMReports.com
>Barracuda - http://barracudamvc.org
>----------------------------------------------
>"Coffee? I could quit anytime, just not today"
>
> > -----Original Message-----
> > From: [email protected]
> > [mailto:[email protected]]On Behalf Of Jacob Kjome
> > Sent: Sunday, February 23, 2003 2:03 PM
> > To: [email protected]
> > Subject: [Barracuda] Barracuda docs....
> >
> >
> >
> > At some point we need to figure out what we want to do with Barracuda's
> > docs.  The way things are is not overly manageable.
> >
> > I think we should use something like Forest from the XML Apache project:
> > http://xml.apache.org/forrest/index.html
> >
> > This will make the doc source human readable and allow for lots of
> > flexibility in the presentation.  Human readability is important
> > for those
> > who might want to contribute to the docs.  They should be able to do so
> > using a simple text editor and not have to know much of anything
> > about the
> > resulting format of the docs.  This ease of use will, I believe, increase
> > contributions to our documentation   which, everyone will agree, requires
> > some enhancement.
> >
> > While it might seem like Forest forces a particular presentation format
> > based on most of the sites that use Forest looking almost exactly
> > the same
> > ( such as http://ant.apache.org/ looking like Forest's layout above ), I
> > believe this was a conscious choice of those sites to use what is
> > probably
> > the default layout.  Looking at some of the sites who claim to use Forest
> > bears this fact out....
> > http://xml.apache.org/forrest/live-sites.html
> >
> > There are a few in that list that don't look like standard Forest layout.
> >
> > I'm not saying we need to do this immediately.  However, we need to get
> > some people thinking about it and working on it at some point.  Any
> > thoughts?  Any volunteers?
> >
> > Jake
> >
> > _______________________________________________
> > Barracuda mailing list
> > [email protected]
> > http://barracudamvc.org/lists/listinfo/barracuda
>
>_______________________________________________
>Barracuda mailing list
>[email protected]
>http://barracudamvc.org/lists/listinfo/barracuda