We understand that Tapestry commiters are giving up their time to make Tapestry what it is, and we are grateful, I think they too are aware of these issues and must have some plans in the pipeline to rectify the problems.
Nothing being suggested in this post is new, my question is where the bottleneck lies? and how can we help? community driven docs (with or without changing existing docs) sounds like the most sensible option to me as it would lift this burden from the commiters and get more people activly involved in growing Tapestry. Cheers, Peter -- If you are not an intended recipient of this e-mail, please notify the sender, delete it and do not read, act upon, print, disclose, copy, retain or redistribute it. Please visit http://www.albourne.com/email.html for important additional terms relating to this e-mail. ----- Original Message ----- From: "Geoff Callender" <geoff.callender.jumpst...@gmail.com> To: "Tapestry users" <users@tapestry.apache.org> Sent: Wednesday, 24 March, 2010 05:13:22 GMT +02:00 Athens, Beirut, Bucharest, Istanbul Subject: Re: Documentation Request/Suggestion I agree too. Users of anything usually need both a Guide and a Reference. To me, the Tapestry documentation is much more of a Reference than a Guide, and that makes it a source of immense frustration to newbies and the experienced alike. Here's what I mean: A User Reference is usually organised alphabetically for quick, well, reference. In contrast, a User Guide is usually organised by task, starting with the simplest task (Hello World?!?!) then working progressively through the tasks the author thinks you are most likely to want to accomplish. Whereas a User Reference includes every last arcane detail (because it really must), a User Guide leads you by the hand to what it thinks is important, helps you avoid known gotchas, and leaves out absolutely everything that doesn't directly contribute to doing the task. A Reference often is not focused on the practical. A User Guide must be focused on the practical. To learn from a Reference is very tough indeed. You pretty much have to read the entire thing at least twice before you can even judge what's actually important and get yourself started. As for injectables and annotations, I think there's a very practical need for something that brings all of them together in a way that all of us users can get a handle on them. A key part would be a description of why you might use each one, and it should put the stuff you're least likely to use down the bottom. Maybe they should even be organised by task? Cheers, Geoff On 24/03/2010, at 12:20 AM, Erick Erickson wrote: > I'll second Michael's statement, the documentation may exist but you > don't even know it's there unless you already know it's there. Tribal > knowledge and all that. Sometimes Google even gets me there. > > But the T5 website is NOT my first choice exactly because of its > organization, and it *should* be my first choice. > > Most of my complaints would be alleviated by a simple search > capability on the tapestry5 website, the lack thereof is my main > difficulty in using it. The organization may make perfect sense to > someone who really understands the thinking behind T5, but to new > folks, it's a mystery. > > Clearly lots and lots of work has been put into the Tapestry website > and documentation. I imagine it's tempting for people who *have* put > the effort into the docs to reply "Read The Field Manual" (Look, it's > a public board, "Field" will do). That work would be much more valuable > to many more of us if it were searchable. It would certainly reduce > my frustration level. > > Here's an example of trying to find something utterly trivial. Say I want > to learn about the @Persist annotation. I go to the top level and click > on "annotations", and you get a page that is utterly useless, to whit: > http://tapestry.apache.org/tapestry5.1/tapestry5-annotations/ > Aha, I look again at the top-level and I find a "Persistent State" > link. Nope. > http://tapestry.apache.org/tapestry5.1/guide/appstate.html > > Hmmm, maybe I clicked one link too low, there's the > "Persistent page data" link at: > http://tapestry.apache.org/tapestry5.1/guide/persist.html > Aha! cool, that page talks about @Persist. Except..... > it has no example of *how* to implement one of the > three strategies. > But look! There's a link to the javadoc for @Persist! I'm saved! > Nope, that page has no example either. > http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/annotations/Persist.html > > At this point I give up and search the project I'm working on for > @Persist and see how utterly simple it is to specify, say, flash > persistence because some intrepid soul has ferreted it out and > put it in the project already. > > And this is one of the most trivial things in T5. God help me if I'm looking > for something more complex, thank goodness for the jumpstart website.... > > All that said, I *am* grateful for the work that has gone into this project, > I > just find this maddening..... > > There, rant finished.. > > Erick > > On Tue, Mar 23, 2010 at 8:47 AM, Michael Gentry <mgen...@masslight.net>wrote: > >> Most new users don't know where in the JavaDoc to begin looking. I >> wasn't suggesting there was no JavaDoc, but I don't consider it to be >> the main starting point for a new user (needle in a haystack). It is >> something for more advanced users. >> >> As for: http://tapestry.apache.org/tapestry5.1/tapestry-ioc/injection.html >> ... Well, using ComponentResources as an example, that page says: >> Injects fields of type ComponentResources. That doesn't really give >> any information as to what it does or how it can be used. No link to >> examples or other documentation. Also, the injection page is buried >> down in the IOC section and is not at the top level. That reduces the >> prominence of it and that is mainly what I'm talking about (put the >> most prominent stuff one uses in T5 -- components, annotations, >> injectables -- in a nice reference at the top). >> >> Thanks, >> >> mrg >> >> >> On Tue, Mar 23, 2010 at 2:42 AM, Igor Drobiazko >> <igor.drobia...@gmail.com> wrote: >>> Why is the javadoc insufficient? All the services are located in few >>> packages depending on the module they were created. Some of them are: >>> >>> >> http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/ioc/services/package-frame.html >>> >> http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/services/package-frame.html >>> >> http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/hibernate/package-frame.html >>> >>> Furthermore there is a page describing all the resources that are >>> injectable: >>> >>> http://tapestry.apache.org/tapestry5.1/tapestry-ioc/injection.html >>> >>> You can also open the page ServiceStatus and read its javadoc, if you >> want >>> to find an appropriate service: >>> >>> http://tapestry.apache.org/tapestry5.1/guide/servicestatus.html >>> >>> In summary I would say this issue should be closed as invalid. Tapestry >> has >>> over 100 services which are good documented in javadoc. Maybe a wiki >> article >>> which is maintained by the community is a better choice. page. We could >> also >>> provide a new annotation @Injectable which is used to mark the interfaces >>> that are meant for injection. >>> >>> On Tue, Mar 23, 2010 at 12:54 AM, Michael Gentry <mgen...@masslight.net >>> wrote: >>> >>>> Created: https://issues.apache.org/jira/browse/TAP5-1070 >>>> >>>> I'm not sure if what I meant by Injectables makes sense, but basically >>>> I meant all things supplied by T5 that you can @Inject (such as >>>> ComponentResources). I had been using T5 for 2-3 months and had no >>>> idea ComponentResources even existed and then I saw an e-mail to this >>>> list by Jun Tsai showing it being used to do something that was >>>> precisely what I needed to solve a particular problem. Great timing, >>>> but it was also quite lucky. If there was a reference of all things I >>>> could inject, I might've been able to read through them and have a >>>> much better idea of things that are available. >>>> >>>> Thanks again! >>>> >>>> mrg >>>> >>>> >>>> On Mon, Mar 22, 2010 at 3:11 PM, Thiago H. de Paula Figueiredo >>>> <thiag...@gmail.com> wrote: >>>>> On Mon, 22 Mar 2010 16:48:31 -0300, Michael Gentry < >>>> mgen...@masslight.net> >>>>> wrote: >>>>> >>>>>> Hello everyone, >>>>> >>>>> Hi! >>>>> >>>>> For annotations, >>>>> >>>>>> All I'm imagining here is a table for each that lists all of the >>>>>> annotations and injectables that ship with Tapestry, a short >>>>>> description as to what they do, and perhaps links to >> examples/detailed >>>>>> explanations of how to use them. Another useful column would be what >>>>>> version of Tapestry it was introduced. >>>>> >>>>> Please post a JIRA about it. Seems a very good suggestion to me. >>>>> >>>>> -- >>>>> Thiago H. de Paula Figueiredo >>>>> Independent Java, Apache Tapestry 5 and Hibernate consultant, >> developer, >>>> and >>>>> instructor >>>>> Owner, software architect and developer, Ars Machina Tecnologia da >>>>> Informação Ltda. >>>>> http://www.arsmachina.com.br >>>>> >>>>> --------------------------------------------------------------------- >>>>> To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org >>>>> For additional commands, e-mail: users-h...@tapestry.apache.org >>>>> >>>>> >>>> >>>> --------------------------------------------------------------------- >>>> To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org >>>> For additional commands, e-mail: users-h...@tapestry.apache.org >>>> >>>> >>> >>> >>> -- >>> Best regards, >>> >>> Igor Drobiazko >>> http://tapestry5.de/blog >>> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org >> For additional commands, e-mail: users-h...@tapestry.apache.org >> >> --------------------------------------------------------------------- To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
