On Wed, 11 Jul 2001, Craig R. McClanahan wrote:
>
>
> On Sun, 8 Jul 2001, Jonathan Asbell wrote:
>
> > What would you like to do Craig?
>
> I'm going to take this as an opportunity to comment broadly on my
> preferences for documentation :-).
>
> STRONG PREFERENCES:
>
> - Final output format readable on the web. In practical terms, that
> probably means HTML or PDF. I personally prefer the former, but ideal
> would be a way to generate HTML and PDF from the same input documents.
>
> - Final version of the docs delivered with Struts as one (or more) web
> apps, as we do now (struts-documentation.war).
>
> MILDER PREFERENCES:
>
> - XML-based "input" format for documents. This lends itself to transfor-
> mation based on multiple stylesheets for different purposes -- and since
> XML is a text-based format, it's much easier to understand incremental
> updates to the docs as they are checked in to CVS.
>
> - Using some standard DTDs for documentation (rather than our own).
>
> - Technologies to investigate include Docbook, Cocoon, FOP.
I've used FOP and my experience has been pretty positive. Other than some
issues / headaches with tables I had, it is pretty straightforward to use.
Some of the syntax can be a little cryptic but the reference documentation
is very (if not too) descriptive (bordering on esoteric!).
>
> STRONGLY OPPOSED:
>
> - Using MS Word or any other such proprietary format. That disenfranchies
> users who do not have the corresponding software. (No problems with
> providing raw docs in that format to people like Ted - I just don't want
> to use it as an official storage mechanism).
>
> - Storing the "output" version of documentation in CVS. Only the "input"
> version of the docs should be there.
>
> In terms of documentation organization, I would prefer to leave that in
> the hands of people (like you guys :-) that are better at it than I am.
>
> Craig
>
>
>
>
>
> >
> > ----- Original Message -----
> > From: "Craig R. McClanahan" <[EMAIL PROTECTED]>
> > To: <[EMAIL PROTECTED]>; "Jonathan" <[EMAIL PROTECTED]>
> > Sent: Saturday, July 07, 2001 4:50 PM
> > Subject: Re: *TED* - round 2 of documentation
> >
> >
> > >
> > >
> > > On Fri, 6 Jul 2001, Jonathan wrote:
> > >
> > > > Absolutely not. The user guide was really well written this time
> > around.
> > > > Kudos to Craig and others who wrote it. I think it should be one of the
> > > > first things you read about Struts because it gets you there quick. I
> > think
> > > > it belongs somewhere with the user guide =)
> > > >
> > >
> > > Perhaps this might be a "Welcome To Struts" or "What Is Struts" document
> > > that someone would read *before* reading the user guide? As someone else
> > > mentioned, maybe we could think of it as a "Product Data Sheet" type
> > > document.
> > >
> > > If so, I think it needs to include at least something like the "MVC
> > > Architecture" picture to visually clue people how the pieces fit together.
> > >
> > > Craig
> > >
> > >
> > > >
> > > > ----- Original Message -----
> > > > From: "Ted Husted" <[EMAIL PROTECTED]>
> > > > To: <[EMAIL PROTECTED]>
> > > > Sent: Friday, July 06, 2001 8:51 AM
> > > > Subject: Re: *TED* - round 2 of documentation
> > > >
> > > >
> > > > > I don't disagree Jonathan. I'm just asking for suggestions as to where
> > > > > we should place it in the context of the rest of the documentation.
> > > > > Should it be part of the User Guide or something else? If something
> > > > > else, what do we call it?
> > > > >
> > > > > Unless of course you're proposing that we drop the rest of the User
> > > > > Guide and just offer this ;-0
> > > > >
> > > > > Jonathan Asbell wrote:
> > > > > >
> > > > > > Hello Ted. I gave this documentation to the other developers in my
> > > > group
> > > > > > who do not know about Struts, and they said that they now understand
> > > > what
> > > > > > Struts is and how to approach using it. They got lost in the
> > "Struts
> > > > > > Components" section because they didnt have a picture to accompany
> > the
> > > > > > explanation, and because they were unfamiliar with Struts. They
> > said
> > > > that
> > > > > > the section "How it all works" clarified how Struts behaves.
> > > > > > The point being that the impedance from trying new tools lies in
> > the
> > > > > > time necessary to understand and configure it. Living in New York
> > is
> > > > great
> > > > > > because it is the ultimate test for when something is too
> > complicated:
> > > > > > People wont take the time to use it. This type of outline gets
> > would be
> > > > > > users/developers started quick. In a few pages they know what
> > Struts
> > > > is,
> > > > > > what it needs to run, and how it functions. Now they can go on,
> > > > install,
> > > > > > configure and develop with Struts with the user guide and this paper
> > in
> > > > hand
> > > > > > and feel fairly confident in developing with it.
> > > > >
> > > >
> > > >
> > >
> >
> >
>
