Re: Organisation of Tapestry documentation
It's the Wiki on tapestry.formos.com On Sun, Aug 16, 2009 at 1:10 AM, Howard Lewis Ship wrote: > Trust me, documentation is a top priority for me ... I'm not even > writing any code for 5.2 until I get the docs under control. > > The "user guide" needs to be renamed as a "reference guide". > > A new user guide needs to replace the current out of date tutorial; > I've started writing that on a wiki. It may live on the wiki rather > than on the web site, where it can be edited by the community. > > On Sat, Aug 15, 2009 at 5:30 AM, Sebastian > Hennebrueder wrote: >> What is the opinion of the core commiter on this issue? I could take the >> time to work out a more details or build a patch to the documentation. >> >> But this only make sense, if we have a common agreement. >> >> >> -- >> Best Regards / Viele Grüße >> >> Sebastian Hennebrueder >> - >> Software Developer and Trainer for Hibernate / Java Persistence >> http://www.laliluna.de >> >> >> >> Paulo Marcelo schrieb: >>> >>> I agree. >>> >>> Paulo Marcelo >>> >>> He who asks is a fool for five minutes, but he who does not ask >>> remains a fool forever. >>> >>> Chinese Proverb >>> >>> >>> 2009/8/12 Szemere Szemere >>> +1 >>> >> >> - >> To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org >> For additional commands, e-mail: users-h...@tapestry.apache.org >> >> > > > > -- > Howard M. Lewis Ship > > Creator of Apache Tapestry > -- Howard M. Lewis Ship Creator of Apache Tapestry The source for Tapestry training, mentoring and support. Contact me to learn how I can get you up and productive in Tapestry fast! - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Organisation of Tapestry documentation
2009/8/20 Otho : > Yeah, it would be nice to be at least able to read it already and comment on > it. > Would save you probably a ton of work. > > > 2009/8/20 Ulrich Stärk > >> Is the wiki freely accessible or are you doing this internally? >> >> On 16.08.2009 10:10 schrieb Howard Lewis Ship: >> >> Trust me, documentation is a top priority for me ... I'm not even >>> writing any code for 5.2 until I get the docs under control. I would not mind helping out with the documentation. I've found a few things before where the answer was scattered among various things - discussion about component classes, the javadoc, component reference, example code. For example, when I was starting out, I wrote my own component class, which was just a little common menu structure that every page had. There is a good general explanation of the idea of writing a component *class* in the T5 documentation. But then, I struggled with the template tag to use to include this new component in the TML files. I searched and searched re-read the tutorial etc and but could not find the 'convention' used until I hit on something that nearly worked - and searching the stack trace led me to a discussion on the mailing list in which a sample code was given. I spent probably a morning struggling over something that infuriated me wasn't in the original documentation of writing a component class - just two lines would have been enough; "And here's how to include the component in a template: (example)". If I was just simply trying it out for a day, rather than using it in anger, I might have tossed it aside angrily at that point and just gone back to Spring MVC. I bet plenty of people confronted with a similar situation have done that before. The advantage of convention over configuration is obvious to all here. But the disadvantage is, if you don't know the convention it is completely opaque. Especially for people starting out - who are more likely to dismiss the tool because of a struggle like the above, and who aren't as likely to be able to find the precise terminology to use in Google to lead them to an answer. The example I would have to give is the Hibernate documentation. It both serves as an excellent guide to beginners who need to know how basic concepts on how to get started with the simple tasks AND a fairly thorough reference doco for wizened old hands who just want to model some strange relationship, trace a bug, use a weird database feature or learn some fairly advanced technique to getting something interesting done. But if you had to choose, I would say the basic concepts are the most important. It's no point discussing esoteric points about component properties if the user cannot place their basic component into their template file. I know the esoteric discussion is far more interesting to Howard and other advanced users but it's only with beginners that the framework will grow. The tutorial is a good start, but it's incomplete, I think (although I prefer both task-orientated and reference documentation to tutorials). regs scot -- let x=x - http://crazymcphee.net/x/ xray dubs - http://autonomous.org/music/ - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Organisation of Tapestry documentation
Yeah, it would be nice to be at least able to read it already and comment on it. Would save you probably a ton of work. 2009/8/20 Ulrich Stärk > Is the wiki freely accessible or are you doing this internally? > > On 16.08.2009 10:10 schrieb Howard Lewis Ship: > > Trust me, documentation is a top priority for me ... I'm not even >> writing any code for 5.2 until I get the docs under control. >> >> The "user guide" needs to be renamed as a "reference guide". >> >> A new user guide needs to replace the current out of date tutorial; >> I've started writing that on a wiki. It may live on the wiki rather >> than on the web site, where it can be edited by the community. >> >> On Sat, Aug 15, 2009 at 5:30 AM, Sebastian >> Hennebrueder wrote: >> >>> What is the opinion of the core commiter on this issue? I could take the >>> time to work out a more details or build a patch to the documentation. >>> >>> But this only make sense, if we have a common agreement. >>> >>> >>> -- >>> Best Regards / Viele Grüße >>> >>> Sebastian Hennebrueder >>> - >>> Software Developer and Trainer for Hibernate / Java Persistence >>> http://www.laliluna.de >>> >>> >>> >>> Paulo Marcelo schrieb: >>> I agree. Paulo Marcelo He who asks is a fool for five minutes, but he who does not ask remains a fool forever. Chinese Proverb 2009/8/12 Szemere Szemere +1 > > - >>> 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 > >
Re: Organisation of Tapestry documentation
Is the wiki freely accessible or are you doing this internally? On 16.08.2009 10:10 schrieb Howard Lewis Ship: Trust me, documentation is a top priority for me ... I'm not even writing any code for 5.2 until I get the docs under control. The "user guide" needs to be renamed as a "reference guide". A new user guide needs to replace the current out of date tutorial; I've started writing that on a wiki. It may live on the wiki rather than on the web site, where it can be edited by the community. On Sat, Aug 15, 2009 at 5:30 AM, Sebastian Hennebrueder wrote: What is the opinion of the core commiter on this issue? I could take the time to work out a more details or build a patch to the documentation. But this only make sense, if we have a common agreement. -- Best Regards / Viele Grüße Sebastian Hennebrueder - Software Developer and Trainer for Hibernate / Java Persistence http://www.laliluna.de Paulo Marcelo schrieb: I agree. Paulo Marcelo He who asks is a fool for five minutes, but he who does not ask remains a fool forever. Chinese Proverb 2009/8/12 Szemere Szemere +1 - 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
Re: Organisation of Tapestry documentation
Trust me, documentation is a top priority for me ... I'm not even writing any code for 5.2 until I get the docs under control. The "user guide" needs to be renamed as a "reference guide". A new user guide needs to replace the current out of date tutorial; I've started writing that on a wiki. It may live on the wiki rather than on the web site, where it can be edited by the community. On Sat, Aug 15, 2009 at 5:30 AM, Sebastian Hennebrueder wrote: > What is the opinion of the core commiter on this issue? I could take the > time to work out a more details or build a patch to the documentation. > > But this only make sense, if we have a common agreement. > > > -- > Best Regards / Viele Grüße > > Sebastian Hennebrueder > - > Software Developer and Trainer for Hibernate / Java Persistence > http://www.laliluna.de > > > > Paulo Marcelo schrieb: >> >> I agree. >> >> Paulo Marcelo >> >> He who asks is a fool for five minutes, but he who does not ask >> remains a fool forever. >> >> Chinese Proverb >> >> >> 2009/8/12 Szemere Szemere >> >>> +1 >>> >> > > - > To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org > For additional commands, e-mail: users-h...@tapestry.apache.org > > -- Howard M. Lewis Ship Creator of Apache Tapestry - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Organisation of Tapestry documentation
What is the opinion of the core commiter on this issue? I could take the time to work out a more details or build a patch to the documentation. But this only make sense, if we have a common agreement. -- Best Regards / Viele Grüße Sebastian Hennebrueder - Software Developer and Trainer for Hibernate / Java Persistence http://www.laliluna.de Paulo Marcelo schrieb: I agree. Paulo Marcelo He who asks is a fool for five minutes, but he who does not ask remains a fool forever. Chinese Proverb 2009/8/12 Szemere Szemere +1 - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Organisation of Tapestry documentation
I agree. Paulo Marcelo He who asks is a fool for five minutes, but he who does not ask remains a fool forever. Chinese Proverb 2009/8/12 Szemere Szemere > +1 >
Re: Organisation of Tapestry documentation
+1
Re: Organisation of Tapestry documentation
I think it's a really good idea. Currently the newcomer has to follow all the links to estimate what is more important and what is less important. That takes a lot of time. On Thu, Aug 6, 2009 at 1:04 AM, Sebastian Hennebrueder wrote: > Hello, > > while working on my Tapestry evaluation article, I start to like Tapestry > but get annoyed at the same time by the distribution of the documentation. > > Sofar I used the following sources linked from the main site > > Tapestry 5 Project > - JavaDocs > - Component Reference > - FAQ > Tapestry Tutorials > - Tutorial > User Guide > - many links here > Tapestry Cookbook > - some links > Resources > - WIKI > - WIKI howto > Junit Tests provided with the downloads (needed to read them as some > components are not documented) > > This is pretty hard for a new user. > > What do you think about the following structure? > Getting started > - Installation with Maven > - Installation without Maven > - Quick start tutorial > - Screen casts > Documentation > - User Guide > - Component Reference > - Java Doc > - FAQ > - Ref card > Documentation by the community > - WIKI > - WIKI Howtos > > merge the content of the cookbook into the user guide or the wiki howto > > -- > Best Regards / Viele Grüße > > Sebastian Hennebrueder > - > Software Developer and Trainer for Hibernate / Java Persistence > http://www.laliluna.de > > > > > - > To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org > For additional commands, e-mail: users-h...@tapestry.apache.org > >
Organisation of Tapestry documentation
Hello, while working on my Tapestry evaluation article, I start to like Tapestry but get annoyed at the same time by the distribution of the documentation. Sofar I used the following sources linked from the main site Tapestry 5 Project - JavaDocs - Component Reference - FAQ Tapestry Tutorials - Tutorial User Guide - many links here Tapestry Cookbook - some links Resources - WIKI - WIKI howto Junit Tests provided with the downloads (needed to read them as some components are not documented) This is pretty hard for a new user. What do you think about the following structure? Getting started - Installation with Maven - Installation without Maven - Quick start tutorial - Screen casts Documentation - User Guide - Component Reference - Java Doc - FAQ - Ref card Documentation by the community - WIKI - WIKI Howtos merge the content of the cookbook into the user guide or the wiki howto -- Best Regards / Viele Grüße Sebastian Hennebrueder - Software Developer and Trainer for Hibernate / Java Persistence http://www.laliluna.de - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org