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