RE: Barracuda docs....

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.

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.

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.

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

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

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)

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

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

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

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

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