You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@tapestry.apache.org by Ulrich Stärk <ul...@spielviel.de> on 2009/01/13 15:28:18 UTC
[T5] improve documentation
Hi all,
Tapestry's current documentation is very complete, covering almost
everything a developer needs to know to be productive with Tapestry.
Unfortunately this documentation is clustered across several locations
thus making it hard to find information and very hard for beginners to
get going. Sometimes even I am annoyed because I don't find the
information I'm looking for at the expected place. There is the official
user guide, which is no guide in the actual sense of the word but merely
a collection of topics using Tapestry-specific vocabulary as the topics,
making it hard for a beginner to get started. Then there is the tutorial
that gets you started with Tapestry but doesn't go deep enough to know
the name of the topic to look for in the user guide when a problem
arises or more information on a subject is needed. Thirdly, there is the
wiki that contains numerous examples on how to solve common use cases
with Tapestry. And lastly there is the component reference that not only
contains documentation for a specific component but also contains
examples on how to use them to solve common use cases. Today for
example, someone on the users mailing list asked for how to have some
kind of a "dynamic component". He wanted to display a certain component
based on the outcome of a function he wrote in his page class. This
question has come up before on the list and because of the "Static
Structure, Dynamic Behavior" paradigm - which is a key principle and is
not mentioned in the documentation but at the bottom of the start page -
the solution is to use the Delegate component with blocks. In the
Delegate component reference documentation there is an example covering
exactly that use case. But it seems that the user wasn't able to find it
- either he didn't look at all or more probably, he looked in the wrong
place. How could he possibly know, that the solution to his use case is
documented in a component named Delegate?
Because I think that the current arrangement of the documentation makes
it hard to grasp the concepts of Tapestry, especially for beginners, and
to quickly find the information one seeks, I propose the following steps
to be taken to improve the documentation:
1. Re-arrange the current documentation to not just be an alphabetically
ordered list of topics but instead to be some kind of guide to Tapestry.
Group topics that belong together, start with basic topics and end with
advanced ones.
2. Print a short description of the purpose of a component next to its
link in the component reference.
3. Integrate the various documents into a coherent documentation that
follows a red line, beginning at the basics and ending with advanced
topics like manipulation of internal services. The tutorial could be
used as a starting point.
4. Extend the Tapestry Cookbook. Move solutions to common use cases from
the wiki (if they meet certain quality criteria) and the component
reference there.
Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
What do you think? What are your experiences with Tapestrys
documentation? Do you think the proposed steps would lead to an
improvement? What other aspects of the documentation do you think need
improvement and how could they be improved?
Cheers,
Uli
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: [T5] improve documentation
Posted by Ulrich Stärk <ul...@spielviel.de>.
I don't think that someone has to be appointed to do it. Everyone can
contribute by writing an improvement, opening an issue in JIRA and
attaching the improvement to it.
As to the book you mentioned, I think the initiative came to a halt
again, shortly after it was started.
Uli
Newham, Cameron schrieb:
> I think we are all in agreement that the documentation needs a radical overhaul (and lots to be written).
>
> The next question is, who is going to do it?
>
> A while ago someone proposed a book on T5. A small group from here organised a separate discussion group and went off to work on it (I have no idea how it is going. Does anyone know?)
>
> Maybe a similar thing should be done w.r.t this current issue?
>
> c.
>
>
> -----Original Message-----
> From: Borut Bolčina [mailto:borut.bolcina@gmail.com]
> Sent: 21 January 2009 08:58
> To: Tapestry users
> Subject: Re: [T5] improve documentation
>
> Hi,
>
> also a guide/recipes/good practices/tips/chapter for converting JSP
> applications to Tapestry 5 would be very welcome. At least a paragraph
> clarifying questions like: "Can I have JSPs in my Tapestry 5 application or
> do I have to have two web applications talking somehow to each other?", "How
> to post a form from JSP to a Tapestry page or vice versa?", ...
>
> A guide on clustering. I know this info can be found in many locations on
> the net, but writing it in Tapestry documentation would imho greatly improve
> the credibility of the framework for "serious" web applications. I feel
> tapestry is missing the scope in the market. It is not advertised in any
> way, nor as a framework which one can use to quickly make a simple news
> site, as other frameworks (non java) are better at that (so I hear), nor as
> a framework which is best for large teams and large applications. Just look
> at the web page for Zend PHP framework (http://www.zend.com). Which page do
> you think management like more, zend's or tapestry's? Unfortunately
> sometimes (too often) the arguments of power outweight the power of
> arguments and the consequence is, well, "We will use the framework which has
> more flashy homepage!".
>
> The community, us, must prove that a simple web application (some forms,
> administration pages, publishing news, social "crap", etc) can be done
> without having a PhD in Computer Science. Tapestry relies much on convention
> over configuration paradigm, that is why the documentation must be excelent.
> Say, for example
> http://tapestry.apache.org/tapestry5/tapestry-core/ref/org/apache/tapestry5/corelib/components/Form.html.
> This page is clearly frightening - look at the first paragraph. So many
> events and none/few of them has a decent explanation/usage scenario/example.
> IMO all of them should be properly documented or not mentioned at all.
>
> The authorization should have a chapter! Tapestry is a very powerful
> framework and as such the same thing can be done differently, BUT...why
> should one have to spend days/weeks to implement a decent
> authentication/authorization system? There should be a guide for common
> scenarios like form based authentication. Of course one can hunt for example
> projects and study the guts of them, which in the end is very rewarding, but
> time consuming. Newcomers should have clear goals on how to implement such
> things, without jumping to the wiki and other places and fighting the
> dependency incompatibilities.
>
>
> -Borut
>
> 2009/1/13 Ulrich Stärk <ul...@spielviel.de>
>
>> Hi all,
>>
>> Tapestry's current documentation is very complete, covering almost
>> everything a developer needs to know to be productive with Tapestry.
>> Unfortunately this documentation is clustered across several locations thus
>> making it hard to find information and very hard for beginners to get going.
>> Sometimes even I am annoyed because I don't find the information I'm looking
>> for at the expected place. There is the official user guide, which is no
>> guide in the actual sense of the word but merely a collection of topics
>> using Tapestry-specific vocabulary as the topics, making it hard for a
>> beginner to get started. Then there is the tutorial that gets you started
>> with Tapestry but doesn't go deep enough to know the name of the topic to
>> look for in the user guide when a problem arises or more information on a
>> subject is needed. Thirdly, there is the wiki that contains numerous
>> examples on how to solve common use cases with Tapestry. And lastly there is
>> the component reference that not only contains documentation for a specific
>> component but also contains examples on how to use them to solve common use
>> cases. Today for example, someone on the users mailing list asked for how to
>> have some kind of a "dynamic component". He wanted to display a certain
>> component based on the outcome of a function he wrote in his page class.
>> This question has come up before on the list and because of the "Static
>> Structure, Dynamic Behavior" paradigm - which is a key principle and is not
>> mentioned in the documentation but at the bottom of the start page - the
>> solution is to use the Delegate component with blocks. In the Delegate
>> component reference documentation there is an example covering exactly that
>> use case. But it seems that the user wasn't able to find it - either he
>> didn't look at all or more probably, he looked in the wrong place. How could
>> he possibly know, that the solution to his use case is documented in a
>> component named Delegate?
>> Because I think that the current arrangement of the documentation makes it
>> hard to grasp the concepts of Tapestry, especially for beginners, and to
>> quickly find the information one seeks, I propose the following steps to be
>> taken to improve the documentation:
>>
>> 1. Re-arrange the current documentation to not just be an alphabetically
>> ordered list of topics but instead to be some kind of guide to Tapestry.
>> Group topics that belong together, start with basic topics and end with
>> advanced ones.
>> 2. Print a short description of the purpose of a component next to its link
>> in the component reference.
>> 3. Integrate the various documents into a coherent documentation that
>> follows a red line, beginning at the basics and ending with advanced topics
>> like manipulation of internal services. The tutorial could be used as a
>> starting point.
>> 4. Extend the Tapestry Cookbook. Move solutions to common use cases from
>> the wiki (if they meet certain quality criteria) and the component reference
>> there.
>>
>> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
>>
>> What do you think? What are your experiences with Tapestrys documentation?
>> Do you think the proposed steps would lead to an improvement? What other
>> aspects of the documentation do you think need improvement and how could
>> they be improved?
>>
>> Cheers,
>>
>> Uli
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: users-help@tapestry.apache.org
>>
>>
>
> **************************************************************************
>
> Experience the British Library online at www.bl.uk
>
> The British Library's new interactive Annual Report and Accounts 2007/08 : www.bl.uk/knowledge
>
> Help the British Library conserve the world's knowledge. Adopt a Book. www.bl.uk/adoptabook
>
> The Library's St Pancras site is WiFi - enabled
>
> *************************************************************************
>
> The information contained in this e-mail is confidential and may be legally privileged. It is intended for the addressee(s) only. If you are not the intended recipient, please delete this e-mail and notify the postmaster@bl.uk : The contents of this e-mail must not be disclosed or copied without the sender's consent.
>
> The statements and opinions expressed in this message are those of the author and do not necessarily reflect those of the British Library. The British Library does not take any responsibility for the views of the author.
>
> *************************************************************************
>
> ---------------------------------------------------------------------
> 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: [T5] improve documentation
Posted by "Newham, Cameron" <ca...@bl.uk>.
I think we are all in agreement that the documentation needs a radical overhaul (and lots to be written).
The next question is, who is going to do it?
A while ago someone proposed a book on T5. A small group from here organised a separate discussion group and went off to work on it (I have no idea how it is going. Does anyone know?)
Maybe a similar thing should be done w.r.t this current issue?
c.
-----Original Message-----
From: Borut Bolčina [mailto:borut.bolcina@gmail.com]
Sent: 21 January 2009 08:58
To: Tapestry users
Subject: Re: [T5] improve documentation
Hi,
also a guide/recipes/good practices/tips/chapter for converting JSP
applications to Tapestry 5 would be very welcome. At least a paragraph
clarifying questions like: "Can I have JSPs in my Tapestry 5 application or
do I have to have two web applications talking somehow to each other?", "How
to post a form from JSP to a Tapestry page or vice versa?", ...
A guide on clustering. I know this info can be found in many locations on
the net, but writing it in Tapestry documentation would imho greatly improve
the credibility of the framework for "serious" web applications. I feel
tapestry is missing the scope in the market. It is not advertised in any
way, nor as a framework which one can use to quickly make a simple news
site, as other frameworks (non java) are better at that (so I hear), nor as
a framework which is best for large teams and large applications. Just look
at the web page for Zend PHP framework (http://www.zend.com). Which page do
you think management like more, zend's or tapestry's? Unfortunately
sometimes (too often) the arguments of power outweight the power of
arguments and the consequence is, well, "We will use the framework which has
more flashy homepage!".
The community, us, must prove that a simple web application (some forms,
administration pages, publishing news, social "crap", etc) can be done
without having a PhD in Computer Science. Tapestry relies much on convention
over configuration paradigm, that is why the documentation must be excelent.
Say, for example
http://tapestry.apache.org/tapestry5/tapestry-core/ref/org/apache/tapestry5/corelib/components/Form.html.
This page is clearly frightening - look at the first paragraph. So many
events and none/few of them has a decent explanation/usage scenario/example.
IMO all of them should be properly documented or not mentioned at all.
The authorization should have a chapter! Tapestry is a very powerful
framework and as such the same thing can be done differently, BUT...why
should one have to spend days/weeks to implement a decent
authentication/authorization system? There should be a guide for common
scenarios like form based authentication. Of course one can hunt for example
projects and study the guts of them, which in the end is very rewarding, but
time consuming. Newcomers should have clear goals on how to implement such
things, without jumping to the wiki and other places and fighting the
dependency incompatibilities.
-Borut
2009/1/13 Ulrich Stärk <ul...@spielviel.de>
> Hi all,
>
> Tapestry's current documentation is very complete, covering almost
> everything a developer needs to know to be productive with Tapestry.
> Unfortunately this documentation is clustered across several locations thus
> making it hard to find information and very hard for beginners to get going.
> Sometimes even I am annoyed because I don't find the information I'm looking
> for at the expected place. There is the official user guide, which is no
> guide in the actual sense of the word but merely a collection of topics
> using Tapestry-specific vocabulary as the topics, making it hard for a
> beginner to get started. Then there is the tutorial that gets you started
> with Tapestry but doesn't go deep enough to know the name of the topic to
> look for in the user guide when a problem arises or more information on a
> subject is needed. Thirdly, there is the wiki that contains numerous
> examples on how to solve common use cases with Tapestry. And lastly there is
> the component reference that not only contains documentation for a specific
> component but also contains examples on how to use them to solve common use
> cases. Today for example, someone on the users mailing list asked for how to
> have some kind of a "dynamic component". He wanted to display a certain
> component based on the outcome of a function he wrote in his page class.
> This question has come up before on the list and because of the "Static
> Structure, Dynamic Behavior" paradigm - which is a key principle and is not
> mentioned in the documentation but at the bottom of the start page - the
> solution is to use the Delegate component with blocks. In the Delegate
> component reference documentation there is an example covering exactly that
> use case. But it seems that the user wasn't able to find it - either he
> didn't look at all or more probably, he looked in the wrong place. How could
> he possibly know, that the solution to his use case is documented in a
> component named Delegate?
> Because I think that the current arrangement of the documentation makes it
> hard to grasp the concepts of Tapestry, especially for beginners, and to
> quickly find the information one seeks, I propose the following steps to be
> taken to improve the documentation:
>
> 1. Re-arrange the current documentation to not just be an alphabetically
> ordered list of topics but instead to be some kind of guide to Tapestry.
> Group topics that belong together, start with basic topics and end with
> advanced ones.
> 2. Print a short description of the purpose of a component next to its link
> in the component reference.
> 3. Integrate the various documents into a coherent documentation that
> follows a red line, beginning at the basics and ending with advanced topics
> like manipulation of internal services. The tutorial could be used as a
> starting point.
> 4. Extend the Tapestry Cookbook. Move solutions to common use cases from
> the wiki (if they meet certain quality criteria) and the component reference
> there.
>
> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
>
> What do you think? What are your experiences with Tapestrys documentation?
> Do you think the proposed steps would lead to an improvement? What other
> aspects of the documentation do you think need improvement and how could
> they be improved?
>
> Cheers,
>
> Uli
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: users-help@tapestry.apache.org
>
>
**************************************************************************
Experience the British Library online at www.bl.uk
The British Library's new interactive Annual Report and Accounts 2007/08 : www.bl.uk/knowledge
Help the British Library conserve the world's knowledge. Adopt a Book. www.bl.uk/adoptabook
The Library's St Pancras site is WiFi - enabled
*************************************************************************
The information contained in this e-mail is confidential and may be legally privileged. It is intended for the addressee(s) only. If you are not the intended recipient, please delete this e-mail and notify the postmaster@bl.uk : The contents of this e-mail must not be disclosed or copied without the sender's consent.
The statements and opinions expressed in this message are those of the author and do not necessarily reflect those of the British Library. The British Library does not take any responsibility for the views of the author.
*************************************************************************
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: [T5] improve documentation
Posted by Borut Bolčina <bo...@gmail.com>.
Hi,
also a guide/recipes/good practices/tips/chapter for converting JSP
applications to Tapestry 5 would be very welcome. At least a paragraph
clarifying questions like: "Can I have JSPs in my Tapestry 5 application or
do I have to have two web applications talking somehow to each other?", "How
to post a form from JSP to a Tapestry page or vice versa?", ...
A guide on clustering. I know this info can be found in many locations on
the net, but writing it in Tapestry documentation would imho greatly improve
the credibility of the framework for "serious" web applications. I feel
tapestry is missing the scope in the market. It is not advertised in any
way, nor as a framework which one can use to quickly make a simple news
site, as other frameworks (non java) are better at that (so I hear), nor as
a framework which is best for large teams and large applications. Just look
at the web page for Zend PHP framework (http://www.zend.com). Which page do
you think management like more, zend's or tapestry's? Unfortunately
sometimes (too often) the arguments of power outweight the power of
arguments and the consequence is, well, "We will use the framework which has
more flashy homepage!".
The community, us, must prove that a simple web application (some forms,
administration pages, publishing news, social "crap", etc) can be done
without having a PhD in Computer Science. Tapestry relies much on convention
over configuration paradigm, that is why the documentation must be excelent.
Say, for example
http://tapestry.apache.org/tapestry5/tapestry-core/ref/org/apache/tapestry5/corelib/components/Form.html.
This page is clearly frightening - look at the first paragraph. So many
events and none/few of them has a decent explanation/usage scenario/example.
IMO all of them should be properly documented or not mentioned at all.
The authorization should have a chapter! Tapestry is a very powerful
framework and as such the same thing can be done differently, BUT...why
should one have to spend days/weeks to implement a decent
authentication/authorization system? There should be a guide for common
scenarios like form based authentication. Of course one can hunt for example
projects and study the guts of them, which in the end is very rewarding, but
time consuming. Newcomers should have clear goals on how to implement such
things, without jumping to the wiki and other places and fighting the
dependency incompatibilities.
-Borut
2009/1/13 Ulrich Stärk <ul...@spielviel.de>
> Hi all,
>
> Tapestry's current documentation is very complete, covering almost
> everything a developer needs to know to be productive with Tapestry.
> Unfortunately this documentation is clustered across several locations thus
> making it hard to find information and very hard for beginners to get going.
> Sometimes even I am annoyed because I don't find the information I'm looking
> for at the expected place. There is the official user guide, which is no
> guide in the actual sense of the word but merely a collection of topics
> using Tapestry-specific vocabulary as the topics, making it hard for a
> beginner to get started. Then there is the tutorial that gets you started
> with Tapestry but doesn't go deep enough to know the name of the topic to
> look for in the user guide when a problem arises or more information on a
> subject is needed. Thirdly, there is the wiki that contains numerous
> examples on how to solve common use cases with Tapestry. And lastly there is
> the component reference that not only contains documentation for a specific
> component but also contains examples on how to use them to solve common use
> cases. Today for example, someone on the users mailing list asked for how to
> have some kind of a "dynamic component". He wanted to display a certain
> component based on the outcome of a function he wrote in his page class.
> This question has come up before on the list and because of the "Static
> Structure, Dynamic Behavior" paradigm - which is a key principle and is not
> mentioned in the documentation but at the bottom of the start page - the
> solution is to use the Delegate component with blocks. In the Delegate
> component reference documentation there is an example covering exactly that
> use case. But it seems that the user wasn't able to find it - either he
> didn't look at all or more probably, he looked in the wrong place. How could
> he possibly know, that the solution to his use case is documented in a
> component named Delegate?
> Because I think that the current arrangement of the documentation makes it
> hard to grasp the concepts of Tapestry, especially for beginners, and to
> quickly find the information one seeks, I propose the following steps to be
> taken to improve the documentation:
>
> 1. Re-arrange the current documentation to not just be an alphabetically
> ordered list of topics but instead to be some kind of guide to Tapestry.
> Group topics that belong together, start with basic topics and end with
> advanced ones.
> 2. Print a short description of the purpose of a component next to its link
> in the component reference.
> 3. Integrate the various documents into a coherent documentation that
> follows a red line, beginning at the basics and ending with advanced topics
> like manipulation of internal services. The tutorial could be used as a
> starting point.
> 4. Extend the Tapestry Cookbook. Move solutions to common use cases from
> the wiki (if they meet certain quality criteria) and the component reference
> there.
>
> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
>
> What do you think? What are your experiences with Tapestrys documentation?
> Do you think the proposed steps would lead to an improvement? What other
> aspects of the documentation do you think need improvement and how could
> they be improved?
>
> Cheers,
>
> Uli
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: users-help@tapestry.apache.org
>
>
Re: [T5] improve documentation
Posted by Ulrich Stärk <ul...@spielviel.de>.
I'd be happy to help and contribute.
Uli
Howard Lewis Ship schrieb:
> I've been coming to the same conclusion.
>
> I'm clearing time with my boss to pursue this, along with several
> online articles.
>
> I have an idea for an application that can demonstrate every bit of
> Tapestry and be useful to boot.
>
> So the "guide" is the reference, what I have planned is the "tour".
> It would replace the tutorial.
>
> On Tue, Jan 13, 2009 at 6:28 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
>> Hi all,
>>
>> Tapestry's current documentation is very complete, covering almost
>> everything a developer needs to know to be productive with Tapestry.
>> Unfortunately this documentation is clustered across several locations thus
>> making it hard to find information and very hard for beginners to get going.
>> Sometimes even I am annoyed because I don't find the information I'm looking
>> for at the expected place. There is the official user guide, which is no
>> guide in the actual sense of the word but merely a collection of topics
>> using Tapestry-specific vocabulary as the topics, making it hard for a
>> beginner to get started. Then there is the tutorial that gets you started
>> with Tapestry but doesn't go deep enough to know the name of the topic to
>> look for in the user guide when a problem arises or more information on a
>> subject is needed. Thirdly, there is the wiki that contains numerous
>> examples on how to solve common use cases with Tapestry. And lastly there is
>> the component reference that not only contains documentation for a specific
>> component but also contains examples on how to use them to solve common use
>> cases. Today for example, someone on the users mailing list asked for how to
>> have some kind of a "dynamic component". He wanted to display a certain
>> component based on the outcome of a function he wrote in his page class.
>> This question has come up before on the list and because of the "Static
>> Structure, Dynamic Behavior" paradigm - which is a key principle and is not
>> mentioned in the documentation but at the bottom of the start page - the
>> solution is to use the Delegate component with blocks. In the Delegate
>> component reference documentation there is an example covering exactly that
>> use case. But it seems that the user wasn't able to find it - either he
>> didn't look at all or more probably, he looked in the wrong place. How could
>> he possibly know, that the solution to his use case is documented in a
>> component named Delegate?
>> Because I think that the current arrangement of the documentation makes it
>> hard to grasp the concepts of Tapestry, especially for beginners, and to
>> quickly find the information one seeks, I propose the following steps to be
>> taken to improve the documentation:
>>
>> 1. Re-arrange the current documentation to not just be an alphabetically
>> ordered list of topics but instead to be some kind of guide to Tapestry.
>> Group topics that belong together, start with basic topics and end with
>> advanced ones.
>> 2. Print a short description of the purpose of a component next to its link
>> in the component reference.
>> 3. Integrate the various documents into a coherent documentation that
>> follows a red line, beginning at the basics and ending with advanced topics
>> like manipulation of internal services. The tutorial could be used as a
>> starting point.
>> 4. Extend the Tapestry Cookbook. Move solutions to common use cases from the
>> wiki (if they meet certain quality criteria) and the component reference
>> there.
>>
>> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
>>
>> What do you think? What are your experiences with Tapestrys documentation?
>> Do you think the proposed steps would lead to an improvement? What other
>> aspects of the documentation do you think need improvement and how could
>> they be improved?
>>
>> Cheers,
>>
>> Uli
>>
>> ---------------------------------------------------------------------
>> 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: [T5] improve documentation
Posted by Kevin Monceaux <Ke...@RawFedDogs.net>.
On Tue, 13 Jan 2009, Howard Lewis Ship wrote:
> I have an idea for an application that can demonstrate every bit of
> Tapestry and be useful to boot.
This is great news!!! As a struggling newbie this is exactly what I've
been looking for. I will be eagerly awaiting it's development.
Here are a few thoughts from this newbie's perspective, in case they might
help. If you have an idea for an application that will demonstrate every
bit of Tapestry, I'm sure it will cover everything I'm looking for. My
apologies ahead of time if any of the following is stating the obvious.
First, I'd personally prefer tutorials that don't assume I'm using an IDE.
I've had trouble following some tutorials because of that. When I see
IDE, I think of hard drives. My editor of choice is vim.
If the tutorial builds the example application incrementally, please
include the includes when code is added. I know they may be obvious to
experienced users. With the current tutorial when it had me add a bit of
code to an existing class, it sometimes took me quite a while, and a bit
of Googling, to find the includes I needed to add to make the code work.
As I said, I'm sure the example app will cover everything I'm looking for.
At the moment I'm looking for examples of handling relational data. I
will also be needing examples of handling security at some point. I've
only looked briefly at some acegi examples. I know it handles role based
security. Does it also handle "object owner" based security? Using a
photo gallery app as an example, I might want to give "admin" users the
ability to add/edit photos to/in all photo albums, and give less powerful
users the ability to only add/edit photos in albums they created.
Kevin
http://www.RawFedDogs.net
http://www.WacoAgilityGroup.org
Bruceville, TX
Si hoc legere scis nimium eruditionis habes.
Longum iter est per praecepta, breve et efficax per exempla!!!
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: [T5] improve documentation
Posted by Otho <ta...@googlemail.com>.
I would prefer a prototypical community application to start the usual
webapp.
So user management, registration with email validation and capchas,
profiles, user groups, fine grained security, optionally simplistic blogs,
forums, pm's and a bit of content management etc. I tend to copy that stuff
over from older applications everytime, since it is standard in almost all
webapps. Having an archetype for that would definitely also give Tap5 a
boost in the hobby programmers section.
Sure, this overlaps a bit with appfuse, but appfuse tends to be a bit
bloated for smaller projects by virtue of the generalizations made.
With the community/user base in place it would be possible to go for full
featured community apps and portals or for example to an online shop, stock
monitors or whatever. If it would be possible to make it easily skinnable I
would think it wouldn't take long before "the community" provides with
interesting designs and eyecandy.
But maybe this is all a bit far fetched ;)
Regards,
Otho
2009/1/17 James Hillyerd <yi...@gmail.com>
> I quite like the existing tutorial, I was just disappointed it ended so
> abruptly. :)
>
> I think whatever docs come around in the future, they need to cover more on
> Encoders/Translators/Coercers - as that was one of the most difficult
> things
> for me to learn. Honestly, I still barely understand when to use which.
>
> -james
>
> On Tue, Jan 13, 2009 at 10:15 AM, Howard Lewis Ship <hlship@gmail.com
> >wrote:
>
> > I've been coming to the same conclusion.
> >
> > I'm clearing time with my boss to pursue this, along with several
> > online articles.
> >
> > I have an idea for an application that can demonstrate every bit of
> > Tapestry and be useful to boot.
> >
> > So the "guide" is the reference, what I have planned is the "tour".
> > It would replace the tutorial.
> >
> >
> >
>
> --
> James A. Hillyerd <ja...@hillyerd.com>
>
Re: [T5] improve documentation
Posted by James Hillyerd <yi...@gmail.com>.
I quite like the existing tutorial, I was just disappointed it ended so
abruptly. :)
I think whatever docs come around in the future, they need to cover more on
Encoders/Translators/Coercers - as that was one of the most difficult things
for me to learn. Honestly, I still barely understand when to use which.
-james
On Tue, Jan 13, 2009 at 10:15 AM, Howard Lewis Ship <hl...@gmail.com>wrote:
> I've been coming to the same conclusion.
>
> I'm clearing time with my boss to pursue this, along with several
> online articles.
>
> I have an idea for an application that can demonstrate every bit of
> Tapestry and be useful to boot.
>
> So the "guide" is the reference, what I have planned is the "tour".
> It would replace the tutorial.
>
>
>
--
James A. Hillyerd <ja...@hillyerd.com>
Re: RE: [T5] improve documentation
Posted by su...@gmx.de.
Jumpstart would also be a good idea....
-------- Original-Nachricht --------
> Datum: Wed, 14 Jan 2009 10:22:13 -0000
> Von: "Newham, Cameron" <ca...@bl.uk>
> An: "Tapestry users" <us...@tapestry.apache.org>
> Betreff: RE: [T5] improve documentation
> I second this.
>
> I much prefer the "cookbook" approach as opposed to having to wade through
> a complete application to find how to do something.
>
> Jumpstart is excellent and has helped me many times. All it needs is
> perhaps a bit more explanation of what's going on, more cases covering solutions
> to common problems, and a bit more filling out.
>
>
>
> -----Original Message-----
> From: Andy Pahne [mailto:andy.pahne@googlemail.com]
> Sent: 13 January 2009 21:15
> To: Tapestry users
> Subject: Re: [T5] improve documentation
>
>
> I'd prefer if it were more like jumpstart than petstore.
>
> Any chance jumpstart becoming part of the framework?
>
> Andy
>
>
>
> superoverdrive@gmx.de schrieb:
> > An good old pet-shop application...with lots of Ajax would be nice...or
> something similiar.
> >
> > It could coves common questions on the Tapestry mailing list from the
> past
> > by providing an example implementation.
> >
> > Would be good if it also contained one or the other things of the
> following list:
> >
> > - Caching HTML fragments (e.g. expensive database queries) that only
> need to be generated
> > every 5 minutes or 5 hours.
> >
> > - Dynamic rendering of form elements (when the configuration is read
> from a database, for dynamic
> > form field definitions, e.g. in the backend "3 textfields with 50 chars
> max, 10 checkboxes with 3 minimum selections.)
> >
> > - some "common" Ajax/DHTML stuff you see nowadays on most websites..e.g.
> > "animations", e.g. imagine you delete a row from a table that dissolves
> with a small animation, or combining an Ajax List with autocomplete or
> something like this here:
> >
> >
> http://www.interiders.com/2008/02/11/prototextboxlist-meets-autocompletion/
> >
> > ....and stuff like progress bars (e.g. during a search)
> >
> > Just a few suggestions!
> >
> > Toby
> >
> > -------- Original-Nachricht --------
> >
> >> Datum: Tue, 13 Jan 2009 10:15:44 -0800
> >> Von: Howard Lewis Ship <hl...@gmail.com>
> >> An: Tapestry users <us...@tapestry.apache.org>
> >> Betreff: Re: [T5] improve documentation
> >>
> >
> >
> >> I've been coming to the same conclusion.
> >>
> >> I'm clearing time with my boss to pursue this, along with several
> >> online articles.
> >>
> >> I have an idea for an application that can demonstrate every bit of
> >> Tapestry and be useful to boot.
> >>
> >> So the "guide" is the reference, what I have planned is the "tour".
> >> It would replace the tutorial.
> >>
> >> On Tue, Jan 13, 2009 at 6:28 AM, Ulrich Stärk <ul...@spielviel.de>
> wrote:
> >>
> >>> Hi all,
> >>>
> >>> Tapestry's current documentation is very complete, covering almost
> >>> everything a developer needs to know to be productive with Tapestry.
> >>> Unfortunately this documentation is clustered across several locations
> >>>
> >> thus
> >>
> >>> making it hard to find information and very hard for beginners to get
> >>>
> >> going.
> >>
> >>> Sometimes even I am annoyed because I don't find the information I'm
> >>>
> >> looking
> >>
> >>> for at the expected place. There is the official user guide, which is
> no
> >>> guide in the actual sense of the word but merely a collection of
> topics
> >>> using Tapestry-specific vocabulary as the topics, making it hard for a
> >>> beginner to get started. Then there is the tutorial that gets you
> >>>
> >> started
> >>
> >>> with Tapestry but doesn't go deep enough to know the name of the topic
> >>>
> >> to
> >>
> >>> look for in the user guide when a problem arises or more information
> on
> >>>
> >> a
> >>
> >>> subject is needed. Thirdly, there is the wiki that contains numerous
> >>> examples on how to solve common use cases with Tapestry. And lastly
> >>>
> >> there is
> >>
> >>> the component reference that not only contains documentation for a
> >>>
> >> specific
> >>
> >>> component but also contains examples on how to use them to solve
> common
> >>>
> >> use
> >>
> >>> cases. Today for example, someone on the users mailing list asked for
> >>>
> >> how to
> >>
> >>> have some kind of a "dynamic component". He wanted to display a
> certain
> >>> component based on the outcome of a function he wrote in his page
> class.
> >>> This question has come up before on the list and because of the
> "Static
> >>> Structure, Dynamic Behavior" paradigm - which is a key principle and
> is
> >>>
> >> not
> >>
> >>> mentioned in the documentation but at the bottom of the start page -
> the
> >>> solution is to use the Delegate component with blocks. In the Delegate
> >>> component reference documentation there is an example covering exactly
> >>>
> >> that
> >>
> >>> use case. But it seems that the user wasn't able to find it - either
> he
> >>> didn't look at all or more probably, he looked in the wrong place. How
> >>>
> >> could
> >>
> >>> he possibly know, that the solution to his use case is documented in a
> >>> component named Delegate?
> >>> Because I think that the current arrangement of the documentation
> makes
> >>>
> >> it
> >>
> >>> hard to grasp the concepts of Tapestry, especially for beginners, and
> to
> >>> quickly find the information one seeks, I propose the following steps
> to
> >>>
> >> be
> >>
> >>> taken to improve the documentation:
> >>>
> >>> 1. Re-arrange the current documentation to not just be an
> alphabetically
> >>> ordered list of topics but instead to be some kind of guide to
> Tapestry.
> >>> Group topics that belong together, start with basic topics and end
> with
> >>> advanced ones.
> >>> 2. Print a short description of the purpose of a component next to its
> >>>
> >> link
> >>
> >>> in the component reference.
> >>> 3. Integrate the various documents into a coherent documentation that
> >>> follows a red line, beginning at the basics and ending with advanced
> >>>
> >> topics
> >>
> >>> like manipulation of internal services. The tutorial could be used as
> a
> >>> starting point.
> >>> 4. Extend the Tapestry Cookbook. Move solutions to common use cases
> from
> >>>
> >> the
> >>
> >>> wiki (if they meet certain quality criteria) and the component
> reference
> >>> there.
> >>>
> >>> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
> >>>
> >>> What do you think? What are your experiences with Tapestrys
> >>>
> >> documentation?
> >>
> >>> Do you think the proposed steps would lead to an improvement? What
> other
> >>> aspects of the documentation do you think need improvement and how
> could
> >>> they be improved?
> >>>
> >>> Cheers,
> >>>
> >>> Uli
> >>>
> >>> ---------------------------------------------------------------------
> >>> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> >>> For additional commands, e-mail: users-help@tapestry.apache.org
> >>>
> >>>
> >>>
> >>
> >> --
> >> Howard M. Lewis Ship
> >>
> >> Creator Apache Tapestry and Apache HiveMind
> >>
> >> ---------------------------------------------------------------------
> >> 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
> >
> >
>
>
> ---------------------------------------------------------------------
> 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
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
RE: [T5] improve documentation
Posted by "Newham, Cameron" <ca...@bl.uk>.
I second this.
I much prefer the "cookbook" approach as opposed to having to wade through a complete application to find how to do something.
Jumpstart is excellent and has helped me many times. All it needs is perhaps a bit more explanation of what's going on, more cases covering solutions to common problems, and a bit more filling out.
-----Original Message-----
From: Andy Pahne [mailto:andy.pahne@googlemail.com]
Sent: 13 January 2009 21:15
To: Tapestry users
Subject: Re: [T5] improve documentation
I'd prefer if it were more like jumpstart than petstore.
Any chance jumpstart becoming part of the framework?
Andy
superoverdrive@gmx.de schrieb:
> An good old pet-shop application...with lots of Ajax would be nice...or something similiar.
>
> It could coves common questions on the Tapestry mailing list from the past
> by providing an example implementation.
>
> Would be good if it also contained one or the other things of the following list:
>
> - Caching HTML fragments (e.g. expensive database queries) that only need to be generated
> every 5 minutes or 5 hours.
>
> - Dynamic rendering of form elements (when the configuration is read from a database, for dynamic
> form field definitions, e.g. in the backend "3 textfields with 50 chars max, 10 checkboxes with 3 minimum selections.)
>
> - some "common" Ajax/DHTML stuff you see nowadays on most websites..e.g.
> "animations", e.g. imagine you delete a row from a table that dissolves with a small animation, or combining an Ajax List with autocomplete or something like this here:
>
> http://www.interiders.com/2008/02/11/prototextboxlist-meets-autocompletion/
>
> ....and stuff like progress bars (e.g. during a search)
>
> Just a few suggestions!
>
> Toby
>
> -------- Original-Nachricht --------
>
>> Datum: Tue, 13 Jan 2009 10:15:44 -0800
>> Von: Howard Lewis Ship <hl...@gmail.com>
>> An: Tapestry users <us...@tapestry.apache.org>
>> Betreff: Re: [T5] improve documentation
>>
>
>
>> I've been coming to the same conclusion.
>>
>> I'm clearing time with my boss to pursue this, along with several
>> online articles.
>>
>> I have an idea for an application that can demonstrate every bit of
>> Tapestry and be useful to boot.
>>
>> So the "guide" is the reference, what I have planned is the "tour".
>> It would replace the tutorial.
>>
>> On Tue, Jan 13, 2009 at 6:28 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
>>
>>> Hi all,
>>>
>>> Tapestry's current documentation is very complete, covering almost
>>> everything a developer needs to know to be productive with Tapestry.
>>> Unfortunately this documentation is clustered across several locations
>>>
>> thus
>>
>>> making it hard to find information and very hard for beginners to get
>>>
>> going.
>>
>>> Sometimes even I am annoyed because I don't find the information I'm
>>>
>> looking
>>
>>> for at the expected place. There is the official user guide, which is no
>>> guide in the actual sense of the word but merely a collection of topics
>>> using Tapestry-specific vocabulary as the topics, making it hard for a
>>> beginner to get started. Then there is the tutorial that gets you
>>>
>> started
>>
>>> with Tapestry but doesn't go deep enough to know the name of the topic
>>>
>> to
>>
>>> look for in the user guide when a problem arises or more information on
>>>
>> a
>>
>>> subject is needed. Thirdly, there is the wiki that contains numerous
>>> examples on how to solve common use cases with Tapestry. And lastly
>>>
>> there is
>>
>>> the component reference that not only contains documentation for a
>>>
>> specific
>>
>>> component but also contains examples on how to use them to solve common
>>>
>> use
>>
>>> cases. Today for example, someone on the users mailing list asked for
>>>
>> how to
>>
>>> have some kind of a "dynamic component". He wanted to display a certain
>>> component based on the outcome of a function he wrote in his page class.
>>> This question has come up before on the list and because of the "Static
>>> Structure, Dynamic Behavior" paradigm - which is a key principle and is
>>>
>> not
>>
>>> mentioned in the documentation but at the bottom of the start page - the
>>> solution is to use the Delegate component with blocks. In the Delegate
>>> component reference documentation there is an example covering exactly
>>>
>> that
>>
>>> use case. But it seems that the user wasn't able to find it - either he
>>> didn't look at all or more probably, he looked in the wrong place. How
>>>
>> could
>>
>>> he possibly know, that the solution to his use case is documented in a
>>> component named Delegate?
>>> Because I think that the current arrangement of the documentation makes
>>>
>> it
>>
>>> hard to grasp the concepts of Tapestry, especially for beginners, and to
>>> quickly find the information one seeks, I propose the following steps to
>>>
>> be
>>
>>> taken to improve the documentation:
>>>
>>> 1. Re-arrange the current documentation to not just be an alphabetically
>>> ordered list of topics but instead to be some kind of guide to Tapestry.
>>> Group topics that belong together, start with basic topics and end with
>>> advanced ones.
>>> 2. Print a short description of the purpose of a component next to its
>>>
>> link
>>
>>> in the component reference.
>>> 3. Integrate the various documents into a coherent documentation that
>>> follows a red line, beginning at the basics and ending with advanced
>>>
>> topics
>>
>>> like manipulation of internal services. The tutorial could be used as a
>>> starting point.
>>> 4. Extend the Tapestry Cookbook. Move solutions to common use cases from
>>>
>> the
>>
>>> wiki (if they meet certain quality criteria) and the component reference
>>> there.
>>>
>>> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
>>>
>>> What do you think? What are your experiences with Tapestrys
>>>
>> documentation?
>>
>>> Do you think the proposed steps would lead to an improvement? What other
>>> aspects of the documentation do you think need improvement and how could
>>> they be improved?
>>>
>>> Cheers,
>>>
>>> Uli
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
>>> For additional commands, e-mail: users-help@tapestry.apache.org
>>>
>>>
>>>
>>
>> --
>> Howard M. Lewis Ship
>>
>> Creator Apache Tapestry and Apache HiveMind
>>
>> ---------------------------------------------------------------------
>> 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
>
>
---------------------------------------------------------------------
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: [T5] improve documentation
Posted by Andy Pahne <an...@googlemail.com>.
I'd prefer if it were more like jumpstart than petstore.
Any chance jumpstart becoming part of the framework?
Andy
superoverdrive@gmx.de schrieb:
> An good old pet-shop application...with lots of Ajax would be nice...or something similiar.
>
> It could coves common questions on the Tapestry mailing list from the past
> by providing an example implementation.
>
> Would be good if it also contained one or the other things of the following list:
>
> - Caching HTML fragments (e.g. expensive database queries) that only need to be generated
> every 5 minutes or 5 hours.
>
> - Dynamic rendering of form elements (when the configuration is read from a database, for dynamic
> form field definitions, e.g. in the backend "3 textfields with 50 chars max, 10 checkboxes with 3 minimum selections.)
>
> - some "common" Ajax/DHTML stuff you see nowadays on most websites..e.g.
> "animations", e.g. imagine you delete a row from a table that dissolves with a small animation, or combining an Ajax List with autocomplete or something like this here:
>
> http://www.interiders.com/2008/02/11/prototextboxlist-meets-autocompletion/
>
> ....and stuff like progress bars (e.g. during a search)
>
> Just a few suggestions!
>
> Toby
>
> -------- Original-Nachricht --------
>
>> Datum: Tue, 13 Jan 2009 10:15:44 -0800
>> Von: Howard Lewis Ship <hl...@gmail.com>
>> An: Tapestry users <us...@tapestry.apache.org>
>> Betreff: Re: [T5] improve documentation
>>
>
>
>> I've been coming to the same conclusion.
>>
>> I'm clearing time with my boss to pursue this, along with several
>> online articles.
>>
>> I have an idea for an application that can demonstrate every bit of
>> Tapestry and be useful to boot.
>>
>> So the "guide" is the reference, what I have planned is the "tour".
>> It would replace the tutorial.
>>
>> On Tue, Jan 13, 2009 at 6:28 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
>>
>>> Hi all,
>>>
>>> Tapestry's current documentation is very complete, covering almost
>>> everything a developer needs to know to be productive with Tapestry.
>>> Unfortunately this documentation is clustered across several locations
>>>
>> thus
>>
>>> making it hard to find information and very hard for beginners to get
>>>
>> going.
>>
>>> Sometimes even I am annoyed because I don't find the information I'm
>>>
>> looking
>>
>>> for at the expected place. There is the official user guide, which is no
>>> guide in the actual sense of the word but merely a collection of topics
>>> using Tapestry-specific vocabulary as the topics, making it hard for a
>>> beginner to get started. Then there is the tutorial that gets you
>>>
>> started
>>
>>> with Tapestry but doesn't go deep enough to know the name of the topic
>>>
>> to
>>
>>> look for in the user guide when a problem arises or more information on
>>>
>> a
>>
>>> subject is needed. Thirdly, there is the wiki that contains numerous
>>> examples on how to solve common use cases with Tapestry. And lastly
>>>
>> there is
>>
>>> the component reference that not only contains documentation for a
>>>
>> specific
>>
>>> component but also contains examples on how to use them to solve common
>>>
>> use
>>
>>> cases. Today for example, someone on the users mailing list asked for
>>>
>> how to
>>
>>> have some kind of a "dynamic component". He wanted to display a certain
>>> component based on the outcome of a function he wrote in his page class.
>>> This question has come up before on the list and because of the "Static
>>> Structure, Dynamic Behavior" paradigm - which is a key principle and is
>>>
>> not
>>
>>> mentioned in the documentation but at the bottom of the start page - the
>>> solution is to use the Delegate component with blocks. In the Delegate
>>> component reference documentation there is an example covering exactly
>>>
>> that
>>
>>> use case. But it seems that the user wasn't able to find it - either he
>>> didn't look at all or more probably, he looked in the wrong place. How
>>>
>> could
>>
>>> he possibly know, that the solution to his use case is documented in a
>>> component named Delegate?
>>> Because I think that the current arrangement of the documentation makes
>>>
>> it
>>
>>> hard to grasp the concepts of Tapestry, especially for beginners, and to
>>> quickly find the information one seeks, I propose the following steps to
>>>
>> be
>>
>>> taken to improve the documentation:
>>>
>>> 1. Re-arrange the current documentation to not just be an alphabetically
>>> ordered list of topics but instead to be some kind of guide to Tapestry.
>>> Group topics that belong together, start with basic topics and end with
>>> advanced ones.
>>> 2. Print a short description of the purpose of a component next to its
>>>
>> link
>>
>>> in the component reference.
>>> 3. Integrate the various documents into a coherent documentation that
>>> follows a red line, beginning at the basics and ending with advanced
>>>
>> topics
>>
>>> like manipulation of internal services. The tutorial could be used as a
>>> starting point.
>>> 4. Extend the Tapestry Cookbook. Move solutions to common use cases from
>>>
>> the
>>
>>> wiki (if they meet certain quality criteria) and the component reference
>>> there.
>>>
>>> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
>>>
>>> What do you think? What are your experiences with Tapestrys
>>>
>> documentation?
>>
>>> Do you think the proposed steps would lead to an improvement? What other
>>> aspects of the documentation do you think need improvement and how could
>>> they be improved?
>>>
>>> Cheers,
>>>
>>> Uli
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
>>> For additional commands, e-mail: users-help@tapestry.apache.org
>>>
>>>
>>>
>>
>> --
>> Howard M. Lewis Ship
>>
>> Creator Apache Tapestry and Apache HiveMind
>>
>> ---------------------------------------------------------------------
>> 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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org
Re: [T5] improve documentation
Posted by su...@gmx.de.
An good old pet-shop application...with lots of Ajax would be nice...or something similiar.
It could coves common questions on the Tapestry mailing list from the past
by providing an example implementation.
Would be good if it also contained one or the other things of the following list:
- Caching HTML fragments (e.g. expensive database queries) that only need to be generated
every 5 minutes or 5 hours.
- Dynamic rendering of form elements (when the configuration is read from a database, for dynamic
form field definitions, e.g. in the backend "3 textfields with 50 chars max, 10 checkboxes with 3 minimum selections.)
- some "common" Ajax/DHTML stuff you see nowadays on most websites..e.g.
"animations", e.g. imagine you delete a row from a table that dissolves with a small animation, or combining an Ajax List with autocomplete or something like this here:
http://www.interiders.com/2008/02/11/prototextboxlist-meets-autocompletion/
....and stuff like progress bars (e.g. during a search)
Just a few suggestions!
Toby
-------- Original-Nachricht --------
> Datum: Tue, 13 Jan 2009 10:15:44 -0800
> Von: Howard Lewis Ship <hl...@gmail.com>
> An: Tapestry users <us...@tapestry.apache.org>
> Betreff: Re: [T5] improve documentation
> I've been coming to the same conclusion.
>
> I'm clearing time with my boss to pursue this, along with several
> online articles.
>
> I have an idea for an application that can demonstrate every bit of
> Tapestry and be useful to boot.
>
> So the "guide" is the reference, what I have planned is the "tour".
> It would replace the tutorial.
>
> On Tue, Jan 13, 2009 at 6:28 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
> > Hi all,
> >
> > Tapestry's current documentation is very complete, covering almost
> > everything a developer needs to know to be productive with Tapestry.
> > Unfortunately this documentation is clustered across several locations
> thus
> > making it hard to find information and very hard for beginners to get
> going.
> > Sometimes even I am annoyed because I don't find the information I'm
> looking
> > for at the expected place. There is the official user guide, which is no
> > guide in the actual sense of the word but merely a collection of topics
> > using Tapestry-specific vocabulary as the topics, making it hard for a
> > beginner to get started. Then there is the tutorial that gets you
> started
> > with Tapestry but doesn't go deep enough to know the name of the topic
> to
> > look for in the user guide when a problem arises or more information on
> a
> > subject is needed. Thirdly, there is the wiki that contains numerous
> > examples on how to solve common use cases with Tapestry. And lastly
> there is
> > the component reference that not only contains documentation for a
> specific
> > component but also contains examples on how to use them to solve common
> use
> > cases. Today for example, someone on the users mailing list asked for
> how to
> > have some kind of a "dynamic component". He wanted to display a certain
> > component based on the outcome of a function he wrote in his page class.
> > This question has come up before on the list and because of the "Static
> > Structure, Dynamic Behavior" paradigm - which is a key principle and is
> not
> > mentioned in the documentation but at the bottom of the start page - the
> > solution is to use the Delegate component with blocks. In the Delegate
> > component reference documentation there is an example covering exactly
> that
> > use case. But it seems that the user wasn't able to find it - either he
> > didn't look at all or more probably, he looked in the wrong place. How
> could
> > he possibly know, that the solution to his use case is documented in a
> > component named Delegate?
> > Because I think that the current arrangement of the documentation makes
> it
> > hard to grasp the concepts of Tapestry, especially for beginners, and to
> > quickly find the information one seeks, I propose the following steps to
> be
> > taken to improve the documentation:
> >
> > 1. Re-arrange the current documentation to not just be an alphabetically
> > ordered list of topics but instead to be some kind of guide to Tapestry.
> > Group topics that belong together, start with basic topics and end with
> > advanced ones.
> > 2. Print a short description of the purpose of a component next to its
> link
> > in the component reference.
> > 3. Integrate the various documents into a coherent documentation that
> > follows a red line, beginning at the basics and ending with advanced
> topics
> > like manipulation of internal services. The tutorial could be used as a
> > starting point.
> > 4. Extend the Tapestry Cookbook. Move solutions to common use cases from
> the
> > wiki (if they meet certain quality criteria) and the component reference
> > there.
> >
> > Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
> >
> > What do you think? What are your experiences with Tapestrys
> documentation?
> > Do you think the proposed steps would lead to an improvement? What other
> > aspects of the documentation do you think need improvement and how could
> > they be improved?
> >
> > Cheers,
> >
> > Uli
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> > For additional commands, e-mail: users-help@tapestry.apache.org
> >
> >
>
>
>
> --
> Howard M. Lewis Ship
>
> Creator Apache Tapestry and Apache HiveMind
>
> ---------------------------------------------------------------------
> 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: [T5] improve documentation
Posted by Howard Lewis Ship <hl...@gmail.com>.
I've been coming to the same conclusion.
I'm clearing time with my boss to pursue this, along with several
online articles.
I have an idea for an application that can demonstrate every bit of
Tapestry and be useful to boot.
So the "guide" is the reference, what I have planned is the "tour".
It would replace the tutorial.
On Tue, Jan 13, 2009 at 6:28 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
> Hi all,
>
> Tapestry's current documentation is very complete, covering almost
> everything a developer needs to know to be productive with Tapestry.
> Unfortunately this documentation is clustered across several locations thus
> making it hard to find information and very hard for beginners to get going.
> Sometimes even I am annoyed because I don't find the information I'm looking
> for at the expected place. There is the official user guide, which is no
> guide in the actual sense of the word but merely a collection of topics
> using Tapestry-specific vocabulary as the topics, making it hard for a
> beginner to get started. Then there is the tutorial that gets you started
> with Tapestry but doesn't go deep enough to know the name of the topic to
> look for in the user guide when a problem arises or more information on a
> subject is needed. Thirdly, there is the wiki that contains numerous
> examples on how to solve common use cases with Tapestry. And lastly there is
> the component reference that not only contains documentation for a specific
> component but also contains examples on how to use them to solve common use
> cases. Today for example, someone on the users mailing list asked for how to
> have some kind of a "dynamic component". He wanted to display a certain
> component based on the outcome of a function he wrote in his page class.
> This question has come up before on the list and because of the "Static
> Structure, Dynamic Behavior" paradigm - which is a key principle and is not
> mentioned in the documentation but at the bottom of the start page - the
> solution is to use the Delegate component with blocks. In the Delegate
> component reference documentation there is an example covering exactly that
> use case. But it seems that the user wasn't able to find it - either he
> didn't look at all or more probably, he looked in the wrong place. How could
> he possibly know, that the solution to his use case is documented in a
> component named Delegate?
> Because I think that the current arrangement of the documentation makes it
> hard to grasp the concepts of Tapestry, especially for beginners, and to
> quickly find the information one seeks, I propose the following steps to be
> taken to improve the documentation:
>
> 1. Re-arrange the current documentation to not just be an alphabetically
> ordered list of topics but instead to be some kind of guide to Tapestry.
> Group topics that belong together, start with basic topics and end with
> advanced ones.
> 2. Print a short description of the purpose of a component next to its link
> in the component reference.
> 3. Integrate the various documents into a coherent documentation that
> follows a red line, beginning at the basics and ending with advanced topics
> like manipulation of internal services. The tutorial could be used as a
> starting point.
> 4. Extend the Tapestry Cookbook. Move solutions to common use cases from the
> wiki (if they meet certain quality criteria) and the component reference
> there.
>
> Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
>
> What do you think? What are your experiences with Tapestrys documentation?
> Do you think the proposed steps would lead to an improvement? What other
> aspects of the documentation do you think need improvement and how could
> they be improved?
>
> Cheers,
>
> Uli
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: users-help@tapestry.apache.org
>
>
--
Howard M. Lewis Ship
Creator Apache Tapestry and Apache HiveMind
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tapestry.apache.org
For additional commands, e-mail: users-help@tapestry.apache.org