2009/8/20 Otho <taa...@googlemail.com>: > 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 <u...@spielviel.de> > >> 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
