Agree! Would be nice with something a bit more well-structured than the wiki, though. The wiki is great for finding examples, but it isn't a great guide by Geoff's definition.
On Wed, Mar 24, 2010 at 7:45 AM, Peter Stavrinides < p.stavrini...@albourne.com> wrote: > 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 > >
