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
