RFC: Wiki Turbine 2 User's Guide Outline

[Chris K Chew <ch...@fenetics.com>]

Hello.

http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaTurbine2UsersGuide

I created an ultra-rough-draft outline for the Wiki Turbine User's Guide
that we have wanted for some time now.  I would greatly appreciate it if
everybody takes a look at the outline to judge it for:

*Completeness
*Logical Organization

If you think of something that is missing or feel that a topic belongs in a
different category, then make a note of it by doing one of the following:

*Make the change on the wiki directly
*Send a note to the list and somebody will implement the change
*Send an email to me directly and I will implement the change

Once we are generally happy with the outline, I will set us all to work on
filling it in.

A quick note about editing the wiki:  please be sure to place your name near
the change AND supply a comment when saving the page.  This helps to
elaborate the conversation that Wiki's facilitate.

Thank you,

Chris


---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org

RE: RFC: Wiki Turbine 2 User's Guide Outline

[Chris K Chew <ch...@fenetics.com>]

> I have an idea. I think some of the documentation that already exists
> gets overlooked by newcomers because it's organized poorly. As an
> example, the TDK how-to has some important basics about developing an
> app with Turbine, yet people don't read it because it's under TDK on the
> site. I'm waiting for a response from Michael C. Starkie regarding the
> thread "newbie create new table" to verify this.
>
> I suggest we reorganize the docs, although I don't have a specific
> recommendation.
>
> What do you think?

Definitely!

Humberto Hernandez was also speaking earlier this week about improving how
we position Turbine, which is certainly something we must do.

I pretty much envision the user's guide as eventually replacing the majority
of the Turbine documentation.  MySQL is a good example, in my opinion.  A
single reference manual will increase the likelihood that it remains
up-to-date by keeping all the information in one place.

A manual won't really cater directly to people perusing the site looking for
a new framework (although having one will help position Turbine as having
good support and a strong community).  Consequently, we would still need
additional information geared towards positioning Turbine for potential new
users.

With these in mind, the areas of documentation might be something like:

*Introductory "Why Use Turbine" Information
*Quick Start Tutorial (Build a sample app)
*Maven-generated Information (Changes, javadoc, etc.)
*Complete Manual (Concepts, Migration, Troubleshooting, Known Issues, etc.
SEARCHABLE)

Any thoughts?


Thanks,
Chris


---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org

Re: RFC: Wiki Turbine 2 User's Guide Outline

[Eric Emminger <er...@ericemminger.com>]

Chris

> I had previously considered your suggestion about the Torque and Velocity
> documentation.  My conclusion was to include the basics of each so as to get
> new user's started without having to scour several websites and user-lists.
> This is particularly true with Torque, which has quite poor documentation.
> In retrospect, without the TDK I never would have been able to learn the
> Torque concepts.

Right.

> I also supposed it would be helpful if the information came heavily from the
> Turbine perspective, which is something that would be missing with links to
> the official Torque and Velocity documentation.  "Okay, so I can do a
> #foreach now, but how does that relate to my Screen class and the List that
> I need to display?".

That's a really good point. I agree. :)

> 
> Still, as developers we decouple code, and we should likewise decouple
> documentation.
> 
> What about a combination of the two...contribute lacking documentation to
> the other projects, link to it, then write an concept-adaptor to bring the
> concept back into Turbine?

Sounds great.

I have an idea. I think some of the documentation that already exists 
gets overlooked by newcomers because it's organized poorly. As an 
example, the TDK how-to has some important basics about developing an 
app with Turbine, yet people don't read it because it's under TDK on the 
site. I'm waiting for a response from Michael C. Starkie regarding the 
thread "newbie create new table" to verify this.

I suggest we reorganize the docs, although I don't have a specific 
recommendation.

What do you think?

Eric


---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org

RE: RFC: Wiki Turbine 2 User's Guide Outline

[Chris K Chew <ch...@fenetics.com>]

Eric,

Thanks for looking at the outline!

I had previously considered your suggestion about the Torque and Velocity
documentation.  My conclusion was to include the basics of each so as to get
new user's started without having to scour several websites and user-lists.
This is particularly true with Torque, which has quite poor documentation.
In retrospect, without the TDK I never would have been able to learn the
Torque concepts.

I also supposed it would be helpful if the information came heavily from the
Turbine perspective, which is something that would be missing with links to
the official Torque and Velocity documentation.  "Okay, so I can do a
#foreach now, but how does that relate to my Screen class and the List that
I need to display?".

Still, as developers we decouple code, and we should likewise decouple
documentation.

What about a combination of the two...contribute lacking documentation to
the other projects, link to it, then write an concept-adaptor to bring the
concept back into Turbine?

Thanks,

Chris

> -----Original Message-----
> From: Eric Emminger [mailto:eric@ericemminger.com]
> Sent: Friday, March 14, 2003 8:58 AM
> To: Turbine Users List
> Subject: Re: RFC: Wiki Turbine 2 User's Guide Outline
>
>
> Thank you, Chris! The outline looks great.
>
> I would suggest replacing the Torque information with a link to the
> Torque docs, since Torque is now a separate project. If you'd like, you
> could contribute additional Torque docs to the Torque project. I'm sure
> they would appreciate that. :)
>
> Maybe the same for Velocity.
>
> The Turbine docs could *also* contain some deep links to the relevant
> docs in the other projects. That would make it easier for Turbine users,
> while keeping the docs where they should be.
>
> What do you think?
>
> Eric
>
> Chris K Chew wrote:
> > Hello.
> >
> > http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaTurbine2UsersGuide
> >
> > I created an ultra-rough-draft outline for the Wiki Turbine User's Guide
> > that we have wanted for some time now.  I would greatly appreciate it if
> > everybody takes a look at the outline to judge it for:
> >
> > *Completeness
> > *Logical Organization
> >
> > If you think of something that is missing or feel that a topic
> belongs in a
> > different category, then make a note of it by doing one of the
> following:
> >
> > *Make the change on the wiki directly
> > *Send a note to the list and somebody will implement the change
> > *Send an email to me directly and I will implement the change
> >
> > Once we are generally happy with the outline, I will set us all
> to work on
> > filling it in.
> >
> > A quick note about editing the wiki:  please be sure to place
> your name near
> > the change AND supply a comment when saving the page.  This helps to
> > elaborate the conversation that Wiki's facilitate.
> >
> > Thank you,
> >
> > Chris
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: turbine-user-help@jakarta.apache.org
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: turbine-user-help@jakarta.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org

Re: RFC: Wiki Turbine 2 User's Guide Outline

[Eric Emminger <er...@ericemminger.com>]

Thank you, Chris! The outline looks great.

I would suggest replacing the Torque information with a link to the 
Torque docs, since Torque is now a separate project. If you'd like, you 
could contribute additional Torque docs to the Torque project. I'm sure 
they would appreciate that. :)

Maybe the same for Velocity.

The Turbine docs could *also* contain some deep links to the relevant 
docs in the other projects. That would make it easier for Turbine users, 
while keeping the docs where they should be.

What do you think?

Eric

Chris K Chew wrote:
> Hello.
> 
> http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaTurbine2UsersGuide
> 
> I created an ultra-rough-draft outline for the Wiki Turbine User's Guide
> that we have wanted for some time now.  I would greatly appreciate it if
> everybody takes a look at the outline to judge it for:
> 
> *Completeness
> *Logical Organization
> 
> If you think of something that is missing or feel that a topic belongs in a
> different category, then make a note of it by doing one of the following:
> 
> *Make the change on the wiki directly
> *Send a note to the list and somebody will implement the change
> *Send an email to me directly and I will implement the change
> 
> Once we are generally happy with the outline, I will set us all to work on
> filling it in.
> 
> A quick note about editing the wiki:  please be sure to place your name near
> the change AND supply a comment when saving the page.  This helps to
> elaborate the conversation that Wiki's facilitate.
> 
> Thank you,
> 
> Chris
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: turbine-user-help@jakarta.apache.org
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org