RE: Solving the T5 Documentation Dilemma
-1 for a forum. I like the fact I can choose between users and users-digest, and I can use nabble or markmail to browse the archive. Unless the proposal is to stop the mailing list, I feel that a forum will simply act to fragment discussions which are an invaluable information source. Best regards, Alfie. -Original Message- From: liigo [mailto:com.li...@gmail.com] Sent: 13 May 2009 03:02 To: Tapestry users Subject: Re: Solving the T5 Documentation Dilemma +1 for Official docs and User docs, and +1 for tapestry forum
Re: Solving the T5 Documentation Dilemma
-1 on forum for the same reasons. On 13-May-09, at 07:36 , Alfie Kirkpatrick wrote: -1 for a forum. I like the fact I can choose between users and users- digest, and I can use nabble or markmail to browse the archive. Unless the proposal is to stop the mailing list, I feel that a forum will simply act to fragment discussions which are an invaluable information source. Best regards, Alfie. -Original Message- From: liigo [mailto:com.li...@gmail.com] Sent: 13 May 2009 03:02 To: Tapestry users Subject: Re: Solving the T5 Documentation Dilemma +1 for Official docs and User docs, and +1 for tapestry forum Christian Edward Gruber e-mail: christianedwardgru...@gmail.com weblog: http://www.geekinasuit.com/ - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
ditto. -1 forum -Original Message- From: Christian Edward Gruber christianedwardgru...@gmail.com Reply-To: Tapestry users users@tapestry.apache.org To: Tapestry users users@tapestry.apache.org Subject: Re: Solving the T5 Documentation Dilemma Date: Wed, 13 May 2009 09:29:10 -0400 -1 on forum for the same reasons. On 13-May-09, at 07:36 , Alfie Kirkpatrick wrote: -1 for a forum. I like the fact I can choose between users and users- digest, and I can use nabble or markmail to browse the archive. Unless the proposal is to stop the mailing list, I feel that a forum will simply act to fragment discussions which are an invaluable information source. Best regards, Alfie. -Original Message- From: liigo [mailto:com.li...@gmail.com] Sent: 13 May 2009 03:02 To: Tapestry users Subject: Re: Solving the T5 Documentation Dilemma +1 for Official docs and User docs, and +1 for tapestry forum Christian Edward Gruber e-mail: christianedwardgru...@gmail.com weblog: http://www.geekinasuit.com/ - 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: Solving the T5 Documentation Dilemma
I think the wiki is a great idea I was just thinking of adding some notes to it but I can't figure out where to add them at http://tapestry.formos.com/wiki/dashboard.action. It could do with a home page helping people find which space to use etc. Would it also be possible to update the Apache wiki home page with a note saying look at tapestry 360? Also I think the permissions are a bit broken as anonymous users can't see the 'Import from the Apache Wiki' space. Ben Gidley www.gidley.co.uk b...@gidley.co.uk On Fri, May 8, 2009 at 9:50 AM, Sergey Didenko sergey.dide...@gmail.comwrote: -1 for forums +1 for wiki Wiki is much better to create persistent knowledge, imho. We can try it open for guests thus it would be easier to start for occasional users. - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
I'll look into all that. On Tue, May 12, 2009 at 12:06 AM, Ben Gidley b...@gidley.co.uk wrote: I think the wiki is a great idea I was just thinking of adding some notes to it but I can't figure out where to add them at http://tapestry.formos.com/wiki/dashboard.action. It could do with a home page helping people find which space to use etc. Would it also be possible to update the Apache wiki home page with a note saying look at tapestry 360? Also I think the permissions are a bit broken as anonymous users can't see the 'Import from the Apache Wiki' space. Ben Gidley www.gidley.co.uk b...@gidley.co.uk On Fri, May 8, 2009 at 9:50 AM, Sergey Didenko sergey.dide...@gmail.comwrote: -1 for forums +1 for wiki Wiki is much better to create persistent knowledge, imho. We can try it open for guests thus it would be easier to start for occasional users. - 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 Director of Open Source Technology at Formos - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
+1 for Official docs and User docs, and +1 for tapestry forum 2009/5/1 Otho taa...@googlemail.com I would suggest splitting the documentation. There should be the reference documentation by the creators/commiters of the project, whis is organized like a book covering all the different aspects of tapestry 5 in a reference manner eg like spring or hibernate docs. These are tied to the release version, too. And then there should be the community docs with tutorials, howto's, recipes and so on on a wiki. There should be a pattern in the templates which requires or at least pushes you, to mention the version of Tapestry you are using. And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. 2009/4/30 Piero Sartini p...@sartini-its.com I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. Confluence is available with apache as well. There is already a space available at http://cwiki.apache.org/TAPESTRY/ ... maybe its just a matter of adding content to it? Anyway.. on Tapestry360 someone would not need to sign a CLA to contribute to the documentation. Piero - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
-1 for forums +1 for wiki Wiki is much better to create persistent knowledge, imho. We can try it open for guests thus it would be easier to start for occasional users. - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
On Freitag, 1. Mai 2009 19:04:53 Otho wrote: The perfect solution and topping cream would be a forum/community system written in Tapestry of course, as a showcase and demonstration of its capabilities as well as a solid starting point for Tapestry apps. But I am aware of the effort and time that takes. The main problem with a forum is the additional work for people who are signed into more than one or two mailing lists. Checking one forum for news may be ok. But navigating to 5-10 or even more forums to check if there is something new and to post answers does take a lot more time than going through your mailing folders and press the reply button. The only real possibility I see is a web-gateway for the mailing lists (NetBeans did it that way). But then... web-gateways like nabble are in place, why develop another one? Piero - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
Is someone still using own mail to receive these :) I've used nabble for a while, and it really rocks. Try it out http://www.nabble.com/Tapestry-f302.html - Ville Piero Sartini-4 wrote: On Freitag, 1. Mai 2009 19:04:53 Otho wrote: The perfect solution and topping cream would be a forum/community system written in Tapestry of course, as a showcase and demonstration of its capabilities as well as a solid starting point for Tapestry apps. But I am aware of the effort and time that takes. The main problem with a forum is the additional work for people who are signed into more than one or two mailing lists. Checking one forum for news may be ok. But navigating to 5-10 or even more forums to check if there is something new and to post answers does take a lot more time than going through your mailing folders and press the reply button. The only real possibility I see is a web-gateway for the mailing lists (NetBeans did it that way). But then... web-gateways like nabble are in place, why develop another one? Piero - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org -- View this message in context: http://www.nabble.com/Solving-the-T5-Documentation-Dilemma-tp23307256p23356147.html Sent from the Tapestry - User mailing list archive at Nabble.com. - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
Is someone still using own mail to receive these :) Yes... that means normally there should be a lists@ alias for sending mails to the lists - need to check whats wrong with my smtp setup. I've used nabble for a while, and it really rocks. Try it out http://www.nabble.com/Tapestry-f302.html Know it because when searching for solutions google takes me there quite often. But I really prefer my email inbox. Automatically filtered into imap directories of course. (Lists/Tapestry User for example). It's so much easier to follow the lists. There never was a good reason to switch to a webbased solution :-) Piero - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
On Freitag, 1. Mai 2009 20:09:07 Ulrich Stärk wrote: As I understand, CLAs only have to be signed by documentation contributors if the exported wiki documentation is bundled with the release. If its purely online, I don't think that this is necessary. Thanks for pointing this out. My assumption was based on how things are done at the struts2 project. Afaik they bundle their wiki with the release, so your explanation would make perfect sense. Piero - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
I would suggest splitting the documentation. There should be the reference documentation by the creators/commiters of the project, whis is organized like a book covering all the different aspects of tapestry 5 in a reference manner eg like spring or hibernate docs. These are tied to the release version, too. And then there should be the community docs with tutorials, howto's, recipes and so on on a wiki. There should be a pattern in the templates which requires or at least pushes you, to mention the version of Tapestry you are using. And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. 2009/4/30 Piero Sartini p...@sartini-its.com I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. Confluence is available with apache as well. There is already a space available at http://cwiki.apache.org/TAPESTRY/ ... maybe its just a matter of adding content to it? Anyway.. on Tapestry360 someone would not need to sign a CLA to contribute to the documentation. Piero - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
Otho schrieb: And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. +1 on this one. mailinglist is really nice, but forum often provides better search and layout advantages (especially for code snippets). Further more you have a better organization (categories, sticky notes etc.). -- manuel aldana ald...@gmx.de software-engineering blog: http://www.aldana-online.de - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
I must also say I prefer mailing lists - it is easier to follow it. If you want a forum why not use the nabble or markmail interfaces to the mailing lists? e.g. http://tapestry.markmail.org/ or http://www.nabble.com/Tapestry---User-f340.html Ben Gidley www.gidley.co.uk b...@gidley.co.uk On Fri, May 1, 2009 at 12:45 PM, Andy Pahne andy.pa...@googlemail.comwrote: except when they are down, just like the hibernate forums recently. I always preferred mailing lists... just my 2 cents manuel aldana schrieb: Otho schrieb: And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. +1 on this one. mailinglist is really nice, but forum often provides better search and layout advantages (especially for code snippets). Further more you have a better organization (categories, sticky notes etc.). - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
except when they are down, just like the hibernate forums recently. I always preferred mailing lists... just my 2 cents manuel aldana schrieb: Otho schrieb: And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. +1 on this one. mailinglist is really nice, but forum often provides better search and layout advantages (especially for code snippets). Further more you have a better organization (categories, sticky notes etc.). - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
On Wed, Apr 29, 2009 at 7:29 PM, Howard Lewis Ship hls...@gmail.com wrote: It might be possible for a wiki to operate in the same way ... we could have a Tapestry 5.1 space and, at the start of 5.2, we could copy it to form the Tapestry 5.2 space. In this way, the documentation for prior releases would be accurate (we could even freeze the space), but would still be open to a community effort to keep it up to date. That seems to be the way that Atlassian uses Confluence for their own documentation -- they copy the space for new versions. You might still not want a frozen space for released versions -- there's almost always room to improve documentation. Community docs can be of lower quality than official docs, but it certainly isn't always that way. I'm sure it's a tricky balance. - Geoffrey -- Geoffrey Wiseman http://www.geoffreywiseman.ca/
Re: Solving the T5 Documentation Dilemma
The primary concern, at the moment, seems to be encouraging people to contribute documentation, tutorials and examples. Making the adding, updating and extension of docs as open (so anyone can do it) and simple (so it is not an arduous task) is the key to this. Howard's suggestion of using the confluence Wiki - and taking snapshots of docs whenever a new release is done makes sense. I would encourage anyone to contribute, and I'm sure that the regular reviewers will compensate for occasional inaccuracies. Anything more cumbersome will put people off. I don't like the idea of tying it into Maven. I for one don't use Maven, and the perceived additional complexity may put others off experimenting using Tap. -Original Message- From: Otho taa...@googlemail.com Reply-To: Tapestry users users@tapestry.apache.org To: Tapestry users users@tapestry.apache.org Subject: Re: Solving the T5 Documentation Dilemma Date: Fri, 1 May 2009 08:43:30 +0200 I would suggest splitting the documentation. There should be the reference documentation by the creators/commiters of the project, whis is organized like a book covering all the different aspects of tapestry 5 in a reference manner eg like spring or hibernate docs. These are tied to the release version, too. And then there should be the community docs with tutorials, howto's, recipes and so on on a wiki. There should be a pattern in the templates which requires or at least pushes you, to mention the version of Tapestry you are using. And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. 2009/4/30 Piero Sartini p...@sartini-its.com I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. Confluence is available with apache as well. There is already a space available at http://cwiki.apache.org/TAPESTRY/ ... maybe its just a matter of adding content to it? Anyway.. on Tapestry360 someone would not need to sign a CLA to contribute to the documentation. Piero - 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: Solving the T5 Documentation Dilemma
-1 on the forum. nabble, markmail and others do an excellent job at providing a forum interface to a mailing list. The community is small enough and there is no need to split the attention w/ a forum that wouldn't bring anything new to the table. - original message - Subject:Re: Solving the T5 Documentation Dilemma From: Andy Pahne andy.pa...@googlemail.com Date: 05/01/2009 11:45 except when they are down, just like the hibernate forums recently. I always preferred mailing lists... just my 2 cents manuel aldana schrieb: Otho schrieb: And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. +1 on this one. mailinglist is really nice, but forum often provides better search and layout advantages (especially for code snippets). Further more you have a better organization (categories, sticky notes etc.). - 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: Solving the T5 Documentation Dilemma
2009/5/1 Alex Kotchnev akoch...@gmail.com -1 on the forum. nabble, markmail and others do an excellent job at providing a forum interface to a mailing list. I would really contend the excellent. It is crude and not really useably imo. The main point for a forum would be exactly your second point: The community is small enough and there is no need to split the attention w/ a forum that wouldn't bring anything new to the table. The question is, if the community should grow or not. In my personal experience Tapestry is much more newbie-friendly than might seem from some of the remarks about the steep learning curve in other threads. I personally find it easier to grasp and more convenient than for example grails. The community here on the list is composed mainly of professional developers I think (which I am not one of) and for this circle of persons mailing lists, jira, confluence etc. are second nature and they are definitely good tools. BUT: What you do with requiring use of mighty but sometimes complicated professional tools from newcomers is piling new complexity on that of the framework and thus easily intimidating them. If you want to reach people new to web development - and thus potential future users of tapestry - the entry barriers should be as low as possible. And forums are the natural first stop for newcomers as soon as they run into problems nowadays. And for the sake of help they are much more convenient than a mailinglist. You can impose a much better structure, edit your posts, contact people and get contacted without disclosing your email-address, moderate easily and so on. The perfect solution and topping cream would be a forum/community system written in Tapestry of course, as a showcase and demonstration of its capabilities as well as a solid starting point for Tapestry apps. But I am aware of the effort and time that takes.
Re: Solving the T5 Documentation Dilemma
yes, I know nabble, and I think it is great. I also think usenet is generally great, but at some point of support it does not scale. At mailinglists you don't have topic categories + sticky notes which I think are quite important for navigation. Further more it lacks and a notification system by topic there. In my view a first class spring support (like in spring support forum) wouldn't be possible with a mailinglist only. Ben Gidley schrieb: I must also say I prefer mailing lists - it is easier to follow it. If you want a forum why not use the nabble or markmail interfaces to the mailing lists? e.g. http://tapestry.markmail.org/ or http://www.nabble.com/Tapestry---User-f340.html Ben Gidley www.gidley.co.uk b...@gidley.co.uk On Fri, May 1, 2009 at 12:45 PM, Andy Pahne andy.pa...@googlemail.comwrote: except when they are down, just like the hibernate forums recently. I always preferred mailing lists... just my 2 cents manuel aldana schrieb: Otho schrieb: And lastly I would suggest setting up a forum. Information is more easily organized there and searching is more convenient than wíth a mailing list alone. I would think that the barrier of contributing to a forum is lower than that of contributing to / asking on a mailinglist. Well, the latter can also be seen as a feature in a way, but publicity and visibility never really hurt IMO. +1 on this one. mailinglist is really nice, but forum often provides better search and layout advantages (especially for code snippets). Further more you have a better organization (categories, sticky notes etc.). - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org -- manuel aldana ald...@gmx.de software-engineering blog: http://www.aldana-online.de - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
As I understand, CLAs only have to be signed by documentation contributors if the exported wiki documentation is bundled with the release. If its purely online, I don't think that this is necessary. On the other hand, CLAs also give the users an assurance that the generated content will be freely available in the future. Concerning hosting the wiki at Formos: As much as I value Formos' support for the Tapestry project, I also fear hosting official parts of Tapestry somewhere else than Apache even if it's more convenient. Apache is a name in the open source business and I believe that having parts of Tapestry's core hosted outside Apache might not be so smart what the marketing concerns. Uli Piero Sartini schrieb: I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. Confluence is available with apache as well. There is already a space available at http://cwiki.apache.org/TAPESTRY/ ... maybe its just a matter of adding content to it? Anyway.. on Tapestry360 someone would not need to sign a CLA to contribute to the documentation. Piero - 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: Solving the T5 Documentation Dilemma
I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. Confluence is available with apache as well. There is already a space available at http://cwiki.apache.org/TAPESTRY/ ... maybe its just a matter of adding content to it? Anyway.. on Tapestry360 someone would not need to sign a CLA to contribute to the documentation. Piero - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Solving the T5 Documentation Dilemma
One of the issues with T5 documentation is that it is written in Maven APT format. This is better than HTML or even various XML docbook-lite kind of things, but it ties documentation down to the Tapestry release cycle. Perhaps it would be better if all documentation was moved onto a live wiki. This has the advantage that more people can work on it, beyond just the T5 committers. I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. I've set up Confluence at Tapestry360: http://tapestry.formos.com/wiki/dashboard.action This is a more industrial strength wiki, better organized, good WYSIWYG editor, good support for images and attachments, and tons of features I don't know or understand yet. The downside of this is that it will be harder to correlate documentation against releases. We've seen this before, when I might publish on the list of the nightly docs some new features, and then a raft of errors about it not working come in. Also, I haven't had the bandwidth to validate the many notes and how-tos on the current Wiki. I'm not sure I would personally be able to do better on Confluence. On Wed, Apr 29, 2009 at 3:31 PM, manuel aldana ald...@gmx.de wrote: Inge Solvoll schrieb: 1. What, politically, made it hard to introduce T5 in your organisation? Who resisted, and why? I am sure there a two things which could help at promotion for convincing decision makers: Real big live sites running under tapestry and a good up to date book. 2. What, technically, made it hard to introduce/teach T5 among your programmer colleagues? (some already mentioned documentation) As bigger sites hardly start from scratch, I see the legacy reason as a big technical point. Usually big codebases rely on action/command focused frameworks (e.g. struts, spring mvc) and it is extremely hard to refactor them to page and component based ones. Also I see that frontend people are being used to work with JSP, freemarker etc. and are a bit hesitating to look at yet another templating technology. I really like tapestry concepts and helps a lot to think in different directions even if you don't use it in daily job. About tap-ioc I really like to java-code style injection and configuration instead for XML. - manuel aldana ald...@gmx.de software-engineering blog: http://www.aldana-online.de - 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 Director of Open Source Technology at Formos - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
I think a wiki is a decent option, but another option would be to make a /trunk/tapestry-ioc/ ... /trunk/tapestry-site/ ... project which could be versioned (or at least released) on a different cycle. This could keep (for any branch such as 5.0, 5.1) the docs as fresh as you wanted to release them. A second, orthogonal pattern is to generate site-documentation on a nightly build and put it up at a standard location, so anyone can check the nightly site docs. This could be matched by a nightly snapshot so the code matches the docs, for things like javadocs and component reports. Christian. On 29-Apr-09, at 19:02 , Howard Lewis Ship wrote: One of the issues with T5 documentation is that it is written in Maven APT format. This is better than HTML or even various XML docbook-lite kind of things, but it ties documentation down to the Tapestry release cycle. Perhaps it would be better if all documentation was moved onto a live wiki. This has the advantage that more people can work on it, beyond just the T5 committers. I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. I've set up Confluence at Tapestry360: http://tapestry.formos.com/wiki/dashboard.action This is a more industrial strength wiki, better organized, good WYSIWYG editor, good support for images and attachments, and tons of features I don't know or understand yet. The downside of this is that it will be harder to correlate documentation against releases. We've seen this before, when I might publish on the list of the nightly docs some new features, and then a raft of errors about it not working come in. Also, I haven't had the bandwidth to validate the many notes and how-tos on the current Wiki. I'm not sure I would personally be able to do better on Confluence. On Wed, Apr 29, 2009 at 3:31 PM, manuel aldana ald...@gmx.de wrote: Inge Solvoll schrieb: 1. What, politically, made it hard to introduce T5 in your organisation? Who resisted, and why? I am sure there a two things which could help at promotion for convincing decision makers: Real big live sites running under tapestry and a good up to date book. 2. What, technically, made it hard to introduce/teach T5 among your programmer colleagues? (some already mentioned documentation) As bigger sites hardly start from scratch, I see the legacy reason as a big technical point. Usually big codebases rely on action/command focused frameworks (e.g. struts, spring mvc) and it is extremely hard to refactor them to page and component based ones. Also I see that frontend people are being used to work with JSP, freemarker etc. and are a bit hesitating to look at yet another templating technology. I really like tapestry concepts and helps a lot to think in different directions even if you don't use it in daily job. About tap-ioc I really like to java-code style injection and configuration instead for XML. - manuel aldana ald...@gmx.de software-engineering blog: http://www.aldana-online.de - 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 Director of Open Source Technology at Formos - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org Christian Edward Gruber e-mail: christianedwardgru...@gmail.com weblog: http://www.geekinasuit.com/ - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
I'd also like to suggest that we add small usage examples into the .xdocs for the components themselves. This was what made NeXTSTEP documentation so nice. You'd have some decent usage documents right in the component reference, so I can go to the loop component reference and see six ways to use it. It would also go a long way to help people get good patterns. My search path is usually: Crap, gotta use some component, go to the reference... no good answer, go to the tutorial... to advanced, go to the cookbook... nothing, go to the wiki... sort of related page, go to the mailing lists... Because T5 is so component-oriented, shoring up the amount of information and context you can get directly in the component reference documentation would really short-circuit a lot of people's searching. cheers, Christian. On 29-Apr-09, at 19:02 , Howard Lewis Ship wrote: One of the issues with T5 documentation is that it is written in Maven APT format. This is better than HTML or even various XML docbook-lite kind of things, but it ties documentation down to the Tapestry release cycle. Perhaps it would be better if all documentation was moved onto a live wiki. This has the advantage that more people can work on it, beyond just the T5 committers. I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. I've set up Confluence at Tapestry360: http://tapestry.formos.com/wiki/dashboard.action This is a more industrial strength wiki, better organized, good WYSIWYG editor, good support for images and attachments, and tons of features I don't know or understand yet. The downside of this is that it will be harder to correlate documentation against releases. We've seen this before, when I might publish on the list of the nightly docs some new features, and then a raft of errors about it not working come in. Also, I haven't had the bandwidth to validate the many notes and how-tos on the current Wiki. I'm not sure I would personally be able to do better on Confluence. On Wed, Apr 29, 2009 at 3:31 PM, manuel aldana ald...@gmx.de wrote: Inge Solvoll schrieb: 1. What, politically, made it hard to introduce T5 in your organisation? Who resisted, and why? I am sure there a two things which could help at promotion for convincing decision makers: Real big live sites running under tapestry and a good up to date book. 2. What, technically, made it hard to introduce/teach T5 among your programmer colleagues? (some already mentioned documentation) As bigger sites hardly start from scratch, I see the legacy reason as a big technical point. Usually big codebases rely on action/command focused frameworks (e.g. struts, spring mvc) and it is extremely hard to refactor them to page and component based ones. Also I see that frontend people are being used to work with JSP, freemarker etc. and are a bit hesitating to look at yet another templating technology. I really like tapestry concepts and helps a lot to think in different directions even if you don't use it in daily job. About tap-ioc I really like to java-code style injection and configuration instead for XML. - manuel aldana ald...@gmx.de software-engineering blog: http://www.aldana-online.de - 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 Director of Open Source Technology at Formos - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org Christian Edward Gruber e-mail: christianedwardgru...@gmail.com weblog: http://www.geekinasuit.com/ - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
On Wed, Apr 29, 2009 at 4:11 PM, Christian Edward Gruber christianedwardgru...@gmail.com wrote: I think a wiki is a decent option, but another option would be to make a /trunk/tapestry-ioc/ ... /trunk/tapestry-site/ ... project which could be versioned (or at least released) on a different cycle. This could keep (for any branch such as 5.0, 5.1) the docs as fresh as you wanted to release them. This is how documentation is done today; it has the advantage that docs are implicitly synchornized to the code (as long as developers are dilligent about updating docs at the same time as code changes). It has the downside of being limited to just access by Tapestry committers. It might be possible for a wiki to operate in the same way ... we could have a Tapestry 5.1 space and, at the start of 5.2, we could copy it to form the Tapestry 5.2 space. In this way, the documentation for prior releases would be accurate (we could even freeze the space), but would still be open to a community effort to keep it up to date. A second, orthogonal pattern is to generate site-documentation on a nightly build and put it up at a standard location, so anyone can check the nightly site docs. This could be matched by a nightly snapshot so the code matches the docs, for things like javadocs and component reports. You mean, like we've been doing for the last couple of years? http://tapestry.formos.com/nightly/tapestry5 Christian. On 29-Apr-09, at 19:02 , Howard Lewis Ship wrote: One of the issues with T5 documentation is that it is written in Maven APT format. This is better than HTML or even various XML docbook-lite kind of things, but it ties documentation down to the Tapestry release cycle. Perhaps it would be better if all documentation was moved onto a live wiki. This has the advantage that more people can work on it, beyond just the T5 committers. I don't think Tapestry's wiki, http://wiki.apache.org/tapestry, is up to the task. I've set up Confluence at Tapestry360: http://tapestry.formos.com/wiki/dashboard.action This is a more industrial strength wiki, better organized, good WYSIWYG editor, good support for images and attachments, and tons of features I don't know or understand yet. The downside of this is that it will be harder to correlate documentation against releases. We've seen this before, when I might publish on the list of the nightly docs some new features, and then a raft of errors about it not working come in. Also, I haven't had the bandwidth to validate the many notes and how-tos on the current Wiki. I'm not sure I would personally be able to do better on Confluence. On Wed, Apr 29, 2009 at 3:31 PM, manuel aldana ald...@gmx.de wrote: Inge Solvoll schrieb: 1. What, politically, made it hard to introduce T5 in your organisation? Who resisted, and why? I am sure there a two things which could help at promotion for convincing decision makers: Real big live sites running under tapestry and a good up to date book. 2. What, technically, made it hard to introduce/teach T5 among your programmer colleagues? (some already mentioned documentation) As bigger sites hardly start from scratch, I see the legacy reason as a big technical point. Usually big codebases rely on action/command focused frameworks (e.g. struts, spring mvc) and it is extremely hard to refactor them to page and component based ones. Also I see that frontend people are being used to work with JSP, freemarker etc. and are a bit hesitating to look at yet another templating technology. I really like tapestry concepts and helps a lot to think in different directions even if you don't use it in daily job. About tap-ioc I really like to java-code style injection and configuration instead for XML. - manuel aldana ald...@gmx.de software-engineering blog: http://www.aldana-online.de - 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 Director of Open Source Technology at Formos - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org Christian Edward Gruber e-mail: christianedwardgru...@gmail.com weblog: http://www.geekinasuit.com/ - 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 Director of Open Source Technology at Formos - To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org For additional commands, e-mail: users-h...@tapestry.apache.org
Re: Solving the T5 Documentation Dilemma
LOL. You got me, Howard. Sorry. I have even visited them, but in my caffeine starved brain I forgot entirely. Christian. On Apr 29, 2009, at 7:29 PM, Howard Lewis Ship wrote: A second, orthogonal pattern is to generate site-documentation on a nightly build and put it up at a standard location, so anyone can check the nightly site docs. This could be matched by a nightly snapshot so the code matches the docs, for things like javadocs and component reports. You mean, like we've been doing for the last couple of years? http://tapestry.formos.com/nightly/tapestry5 Christian Edward Gruber christianedwardgru...@gmail.com http://www.geekinasuit.com/
Re: Solving the T5 Documentation Dilemma
On Apr 29, 2009, at 7:29 PM, Howard Lewis Ship wrote: On Wed, Apr 29, 2009 at 4:11 PM, Christian Edward Gruber christianedwardgru...@gmail.com wrote: ... project which could be versioned (or at least released) on a different cycle. This could keep (for any branch such as 5.0, 5.1) the docs as fresh as you wanted to release them. This is how documentation is done today; it has the advantage that docs are implicitly synchornized to the code (as long as developers are dilligent about updating docs at the same time as code changes). It has the downside of being limited to just access by Tapestry committers. It might be possible for a wiki to operate in the same way ... we could have a Tapestry 5.1 space and, at the start of 5.2, we could copy it to form the Tapestry 5.2 space. In this way, the documentation for prior releases would be accurate (we could even freeze the space), but would still be open to a community effort to keep it up to date. I'm not sure that docs are any less important to have commit rights for than code. I think people should be submitting patches, or they should be committers. Or maybe someone wants to be a committer with focus on docs, to mediate the flow of community suggestions. I just think that the difference between published and contributed documentation is often quite high, and I think the information in contributed docs should end up in the published docs ultimately (if it's not redundant or irrelevant), I think having a little bit of a gate on the documentation would be good. Another option is to have an open repository where the docs live, and can be manipulated - a set of community-oriented docs in a different repo where more people can have commit rights. Then people can play with docs, and people can move them into the canonical docs as appropriate. I'm still caffeine starved, so I may be over-thinking this. Christian. Christian Edward Gruber christianedwardgru...@gmail.com http://www.geekinasuit.com/
