You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@tapestry.apache.org by Sebastian Hennebrueder <us...@laliluna.de> on 2009/08/06 00:04:26 UTC
Organisation of Tapestry documentation
Hello,
while working on my Tapestry evaluation article, I start to like
Tapestry but get annoyed at the same time by the distribution of the
documentation.
Sofar I used the following sources linked from the main site
Tapestry 5 Project
- JavaDocs
- Component Reference
- FAQ
Tapestry Tutorials
- Tutorial
User Guide
- many links here
Tapestry Cookbook
- some links
Resources
- WIKI
- WIKI howto
Junit Tests provided with the downloads (needed to read them as some
components are not documented)
This is pretty hard for a new user.
What do you think about the following structure?
Getting started
- Installation with Maven
- Installation without Maven
- Quick start tutorial
- Screen casts
Documentation
- User Guide
- Component Reference
- Java Doc
- FAQ
- Ref card
Documentation by the community
- WIKI
- WIKI Howtos
merge the content of the cookbook into the user guide or the wiki howto
--
Best Regards / Viele Grüße
Sebastian Hennebrueder
-----
Software Developer and Trainer for Hibernate / Java Persistence
http://www.laliluna.de
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: Organisation of Tapestry documentation
Posted by Howard Lewis Ship <hl...@gmail.com>.
It's the Wiki on tapestry.formos.com
On Sun, Aug 16, 2009 at 1:10 AM, Howard Lewis Ship<hl...@gmail.com> wrote:
> Trust me, documentation is a top priority for me ... I'm not even
> writing any code for 5.2 until I get the docs under control.
>
> The "user guide" needs to be renamed as a "reference guide".
>
> A new user guide needs to replace the current out of date tutorial;
> I've started writing that on a wiki. It may live on the wiki rather
> than on the web site, where it can be edited by the community.
>
> On Sat, Aug 15, 2009 at 5:30 AM, Sebastian
> Hennebrueder<us...@laliluna.de> wrote:
>> What is the opinion of the core commiter on this issue? I could take the
>> time to work out a more details or build a patch to the documentation.
>>
>> But this only make sense, if we have a common agreement.
>>
>>
>> --
>> Best Regards / Viele Grüße
>>
>> Sebastian Hennebrueder
>> -----
>> Software Developer and Trainer for Hibernate / Java Persistence
>> http://www.laliluna.de
>>
>>
>>
>> Paulo Marcelo schrieb:
>>>
>>> I agree.
>>>
>>> Paulo Marcelo
>>>
>>> He who asks is a fool for five minutes, but he who does not ask
>>> remains a fool forever.
>>>
>>> Chinese Proverb
>>>
>>>
>>> 2009/8/12 Szemere Szemere <sz...@googlemail.com>
>>>
>>>> +1
>>>>
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: users-help@tapestry.apache.org
>>
>>
>
>
>
> --
> Howard M. Lewis Ship
>
> Creator of Apache Tapestry
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
The source for Tapestry training, mentoring and support. Contact me to
learn how I can get you up and productive in Tapestry fast!
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: Organisation of Tapestry documentation
Posted by Scot Mcphee <sc...@gmail.com>.
2009/8/20 Otho <ta...@googlemail.com>:
> Yeah, it would be nice to be at least able to read it already and comment on
> it.
> Would save you probably a ton of work.
>
>
> 2009/8/20 Ulrich Stärk <ul...@spielviel.de>
>
>> Is the wiki freely accessible or are you doing this internally?
>>
>> On 16.08.2009 10:10 schrieb Howard Lewis Ship:
>>
>> Trust me, documentation is a top priority for me ... I'm not even
>>> writing any code for 5.2 until I get the docs under control.
I would not mind helping out with the documentation.
I've found a few things before where the answer was scattered among
various things - discussion about component classes, the javadoc,
component reference, example code.
For example, when I was starting out, I wrote my own component class,
which was just a little common menu structure that every page had.
There is a good general explanation of the idea of writing a component
*class* in the T5 documentation. But then, I struggled with the
template tag to use to include this new component in the TML files. I
searched and searched re-read the tutorial etc and but could not find
the 'convention' used until I hit on something that nearly worked -
and searching the stack trace led me to a discussion on the mailing
list in which a sample code was given. I spent probably a morning
struggling over something that infuriated me wasn't in the original
documentation of writing a component class - just two lines would have
been enough; "And here's how to include the component in a template:
(example)".
If I was just simply trying it out for a day, rather than using it in
anger, I might have tossed it aside angrily at that point and just
gone back to Spring MVC. I bet plenty of people confronted with a
similar situation have done that before.
The advantage of convention over configuration is obvious to all here.
But the disadvantage is, if you don't know the convention it is
completely opaque. Especially for people starting out - who are more
likely to dismiss the tool because of a struggle like the above, and
who aren't as likely to be able to find the precise terminology to use
in Google to lead them to an answer.
The example I would have to give is the Hibernate documentation. It
both serves as an excellent guide to beginners who need to know how
basic concepts on how to get started with the simple tasks AND a
fairly thorough reference doco for wizened old hands who just want to
model some strange relationship, trace a bug, use a weird database
feature or learn some fairly advanced technique to getting something
interesting done.
But if you had to choose, I would say the basic concepts are the most
important. It's no point discussing esoteric points about component
properties if the user cannot place their basic component into their
template file. I know the esoteric discussion is far more interesting
to Howard and other advanced users but it's only with beginners that
the framework will grow. The tutorial is a good start, but it's
incomplete, I think (although I prefer both task-orientated and
reference documentation to tutorials).
regs
scot
--
let x=x - http://crazymcphee.net/x/
xray dubs - http://autonomous.org/music/
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: Organisation of Tapestry documentation
Posted by Otho <ta...@googlemail.com>.
Yeah, it would be nice to be at least able to read it already and comment on
it.
Would save you probably a ton of work.
2009/8/20 Ulrich Stärk <ul...@spielviel.de>
> Is the wiki freely accessible or are you doing this internally?
>
> On 16.08.2009 10:10 schrieb Howard Lewis Ship:
>
> Trust me, documentation is a top priority for me ... I'm not even
>> writing any code for 5.2 until I get the docs under control.
>>
>> The "user guide" needs to be renamed as a "reference guide".
>>
>> A new user guide needs to replace the current out of date tutorial;
>> I've started writing that on a wiki. It may live on the wiki rather
>> than on the web site, where it can be edited by the community.
>>
>> On Sat, Aug 15, 2009 at 5:30 AM, Sebastian
>> Hennebrueder<us...@laliluna.de> wrote:
>>
>>> What is the opinion of the core commiter on this issue? I could take the
>>> time to work out a more details or build a patch to the documentation.
>>>
>>> But this only make sense, if we have a common agreement.
>>>
>>>
>>> --
>>> Best Regards / Viele Grüße
>>>
>>> Sebastian Hennebrueder
>>> -----
>>> Software Developer and Trainer for Hibernate / Java Persistence
>>> http://www.laliluna.de
>>>
>>>
>>>
>>> Paulo Marcelo schrieb:
>>>
>>>> I agree.
>>>>
>>>> Paulo Marcelo
>>>>
>>>> He who asks is a fool for five minutes, but he who does not ask
>>>> remains a fool forever.
>>>>
>>>> Chinese Proverb
>>>>
>>>>
>>>> 2009/8/12 Szemere Szemere <sz...@googlemail.com>
>>>>
>>>> +1
>>>>>
>>>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
>>> For additional commands, e-mail: users-help@tapestry.apache.org
>>>
>>>
>>>
>>
>>
>>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: users-help@tapestry.apache.org
>
>
Re: Organisation of Tapestry documentation
Posted by Ulrich Stärk <ul...@spielviel.de>.
Is the wiki freely accessible or are you doing this internally?
On 16.08.2009 10:10 schrieb Howard Lewis Ship:
> Trust me, documentation is a top priority for me ... I'm not even
> writing any code for 5.2 until I get the docs under control.
>
> The "user guide" needs to be renamed as a "reference guide".
>
> A new user guide needs to replace the current out of date tutorial;
> I've started writing that on a wiki. It may live on the wiki rather
> than on the web site, where it can be edited by the community.
>
> On Sat, Aug 15, 2009 at 5:30 AM, Sebastian
> Hennebrueder<us...@laliluna.de> wrote:
>> What is the opinion of the core commiter on this issue? I could take the
>> time to work out a more details or build a patch to the documentation.
>>
>> But this only make sense, if we have a common agreement.
>>
>>
>> --
>> Best Regards / Viele Grüße
>>
>> Sebastian Hennebrueder
>> -----
>> Software Developer and Trainer for Hibernate / Java Persistence
>> http://www.laliluna.de
>>
>>
>>
>> Paulo Marcelo schrieb:
>>> I agree.
>>>
>>> Paulo Marcelo
>>>
>>> He who asks is a fool for five minutes, but he who does not ask
>>> remains a fool forever.
>>>
>>> Chinese Proverb
>>>
>>>
>>> 2009/8/12 Szemere Szemere <sz...@googlemail.com>
>>>
>>>> +1
>>>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: users-help@tapestry.apache.org
>>
>>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: Organisation of Tapestry documentation
Posted by Howard Lewis Ship <hl...@gmail.com>.
Trust me, documentation is a top priority for me ... I'm not even
writing any code for 5.2 until I get the docs under control.
The "user guide" needs to be renamed as a "reference guide".
A new user guide needs to replace the current out of date tutorial;
I've started writing that on a wiki. It may live on the wiki rather
than on the web site, where it can be edited by the community.
On Sat, Aug 15, 2009 at 5:30 AM, Sebastian
Hennebrueder<us...@laliluna.de> wrote:
> What is the opinion of the core commiter on this issue? I could take the
> time to work out a more details or build a patch to the documentation.
>
> But this only make sense, if we have a common agreement.
>
>
> --
> Best Regards / Viele Grüße
>
> Sebastian Hennebrueder
> -----
> Software Developer and Trainer for Hibernate / Java Persistence
> http://www.laliluna.de
>
>
>
> Paulo Marcelo schrieb:
>>
>> I agree.
>>
>> Paulo Marcelo
>>
>> He who asks is a fool for five minutes, but he who does not ask
>> remains a fool forever.
>>
>> Chinese Proverb
>>
>>
>> 2009/8/12 Szemere Szemere <sz...@googlemail.com>
>>
>>> +1
>>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: users-help@tapestry.apache.org
>
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: Organisation of Tapestry documentation
Posted by Sebastian Hennebrueder <us...@laliluna.de>.
What is the opinion of the core commiter on this issue? I could take the
time to work out a more details or build a patch to the documentation.
But this only make sense, if we have a common agreement.
--
Best Regards / Viele Grüße
Sebastian Hennebrueder
-----
Software Developer and Trainer for Hibernate / Java Persistence
http://www.laliluna.de
Paulo Marcelo schrieb:
> I agree.
>
> Paulo Marcelo
>
> He who asks is a fool for five minutes, but he who does not ask
> remains a fool forever.
>
> Chinese Proverb
>
>
> 2009/8/12 Szemere Szemere <sz...@googlemail.com>
>
>> +1
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: Organisation of Tapestry documentation
Posted by Paulo Marcelo <pa...@gmail.com>.
I agree.
Paulo Marcelo
He who asks is a fool for five minutes, but he who does not ask
remains a fool forever.
Chinese Proverb
2009/8/12 Szemere Szemere <sz...@googlemail.com>
> +1
>
Re: Organisation of Tapestry documentation
Posted by Szemere Szemere <sz...@googlemail.com>.
+1
Re: Organisation of Tapestry documentation
Posted by Sergey Didenko <se...@gmail.com>.
I think it's a really good idea.
Currently the newcomer has to follow all the links to estimate what is more
important and what is less important. That takes a lot of time.
On Thu, Aug 6, 2009 at 1:04 AM, Sebastian Hennebrueder
<us...@laliluna.de>wrote:
> Hello,
>
> while working on my Tapestry evaluation article, I start to like Tapestry
> but get annoyed at the same time by the distribution of the documentation.
>
> Sofar I used the following sources linked from the main site
>
> Tapestry 5 Project
> - JavaDocs
> - Component Reference
> - FAQ
> Tapestry Tutorials
> - Tutorial
> User Guide
> - many links here
> Tapestry Cookbook
> - some links
> Resources
> - WIKI
> - WIKI howto
> Junit Tests provided with the downloads (needed to read them as some
> components are not documented)
>
> This is pretty hard for a new user.
>
> What do you think about the following structure?
> Getting started
> - Installation with Maven
> - Installation without Maven
> - Quick start tutorial
> - Screen casts
> Documentation
> - User Guide
> - Component Reference
> - Java Doc
> - FAQ
> - Ref card
> Documentation by the community
> - WIKI
> - WIKI Howtos
>
> merge the content of the cookbook into the user guide or the wiki howto
>
> --
> Best Regards / Viele Grüße
>
> Sebastian Hennebrueder
> -----
> Software Developer and Trainer for Hibernate / Java Persistence
> http://www.laliluna.de
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: users-help@tapestry.apache.org
>
>