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 <u...@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-unsubscr...@tapestry.apache.org > For additional commands, e-mail: users-h...@tapestry.apache.org > > -- Howard M. Lewis Ship Creator Apache Tapestry and Apache HiveMind --------------------------------------------------------------------- To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
