Docbook for Click documentation ?
|
|
Malcolm Edgar-2
|
What do people think about using DocBook to generate Click's
documentation as HTML pages and as a PDF document. This has been a common request from people, can I get a PDF of the documentation or when is the Click book comming out. I have shided away from DocBook after being involved in using it for Tapestry 2.3 (it was hard, and won't work offline) however after having a trial run with http://velocity.apache.org/docbook/ I think it has come along way. I think both the Spring and Hibernate projects use some form a DocBook to generate their documentation, and I think their very good documentation has been a significant factor in their adoption. One problem with the current documention is that it is held under very large chapters, so the TOC menu will display in smallish screens 1024x768. I dont think this will scale well as the documentation grows and we need smaller topic based chapters. Issues I have seen with DocBook is the formatting of HTML, but I presume this can be addressed with custom CSS styles. regards Malcolm Edgar ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
Ted Husted
|
I've used DocBook for a hundred+ page book, and I would do it again.
It's a bit of a struggle at first, but well worth it in the end. * http://code.google.com/p/sq1-struts2/ Something that helped me was to just write the XML straight-up in a text editor, rather than fuss with the XML editors. And, of course, for group editing and review, nothing beats a text-based format under Subversion :) -Ted. On Mon, Jul 28, 2008 at 8:22 PM, Malcolm Edgar <malcolm.edgar@...> wrote: > What do people think about using DocBook to generate Click's > documentation as HTML pages and as a PDF document. > > This has been a common request from people, can I get a PDF of the > documentation or when is the Click book comming out. > > I have shided away from DocBook after being involved in using it for > Tapestry 2.3 (it was hard, and won't work offline) however after > having a trial run with > > http://velocity.apache.org/docbook/ > > I think it has come along way. I think both the Spring and Hibernate > projects use some form a DocBook to generate their documentation, and > I think their very good documentation has been a significant factor in > their adoption. > > One problem with the current documention is that it is held under very > large chapters, so the TOC menu will display in smallish screens > 1024x768. I dont think this will scale well as the documentation grows > and we need smaller topic based chapters. > > Issues I have seen with DocBook is the formatting of HTML, but I > presume this can be addressed with custom CSS styles. > > regards Malcolm Edgar > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Click-development mailing list > Click-development@... > https://lists.sourceforge.net/lists/listinfo/click-development > -- HTH, Ted http://husted.com/ted/blog/ ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
Ted Husted-4
|
In reply to this post by Malcolm Edgar-2
I've used DocBook for a hundred+ page book, and I would do it again.
It's a bit of a struggle at first, but well worth it in the end. * http://code.google.com/p/sq1-struts2/ Something that helped me was to just write the XML straight-up in a text editor, rather than fuss with the XML editors. And, of course, for group editing and review, nothing beats a text-based format under Subversion :) HTH, Ted http://husted.com/ted/blog/ On Mon, Jul 28, 2008 at 8:22 PM, Malcolm Edgar <malcolm.edgar@...> wrote: > What do people think about using DocBook to generate Click's > documentation as HTML pages and as a PDF document. > > This has been a common request from people, can I get a PDF of the > documentation or when is the Click book comming out. > > I have shided away from DocBook after being involved in using it for > Tapestry 2.3 (it was hard, and won't work offline) however after > having a trial run with > > http://velocity.apache.org/docbook/ > > I think it has come along way. I think both the Spring and Hibernate > projects use some form a DocBook to generate their documentation, and > I think their very good documentation has been a significant factor in > their adoption. > > One problem with the current documention is that it is held under very > large chapters, so the TOC menu will display in smallish screens > 1024x768. I dont think this will scale well as the documentation grows > and we need smaller topic based chapters. > > Issues I have seen with DocBook is the formatting of HTML, but I > presume this can be addressed with custom CSS styles. > > regards Malcolm Edgar > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Click-development mailing list > Click-development@... > https://lists.sourceforge.net/lists/listinfo/click-development ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
|
Malcolm Edgar-2
|
Thanks Ted,
that feedback sounds promising. How is it for generating static web site content? regards Malcolm Edgar On Tue, Jul 29, 2008 at 11:59 AM, Ted Husted <thusted@...> wrote: > I've used DocBook for a hundred+ page book, and I would do it again. > It's a bit of a struggle at first, but well worth it in the end. > > * http://code.google.com/p/sq1-struts2/ > > Something that helped me was to just write the XML straight-up in a > text editor, rather than fuss with the XML editors. > > And, of course, for group editing and review, nothing beats a > text-based format under Subversion :) > > HTH, Ted > http://husted.com/ted/blog/ > > > On Mon, Jul 28, 2008 at 8:22 PM, Malcolm Edgar <malcolm.edgar@...> wrote: >> What do people think about using DocBook to generate Click's >> documentation as HTML pages and as a PDF document. >> >> This has been a common request from people, can I get a PDF of the >> documentation or when is the Click book comming out. >> >> I have shided away from DocBook after being involved in using it for >> Tapestry 2.3 (it was hard, and won't work offline) however after >> having a trial run with >> >> http://velocity.apache.org/docbook/ >> >> I think it has come along way. I think both the Spring and Hibernate >> projects use some form a DocBook to generate their documentation, and >> I think their very good documentation has been a significant factor in >> their adoption. >> >> One problem with the current documention is that it is held under very >> large chapters, so the TOC menu will display in smallish screens >> 1024x768. I dont think this will scale well as the documentation grows >> and we need smaller topic based chapters. >> >> Issues I have seen with DocBook is the formatting of HTML, but I >> presume this can be addressed with custom CSS styles. >> >> regards Malcolm Edgar >> >> ------------------------------------------------------------------------- >> This SF.Net email is sponsored by the Moblin Your Move Developer's challenge >> Build the coolest Linux based applications with Moblin SDK & win great prizes >> Grand prize is a trip for two to an Open Source event anywhere in the world >> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >> _______________________________________________ >> Click-development mailing list >> Click-development@... >> https://lists.sourceforge.net/lists/listinfo/click-development > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Click-development mailing list > Click-development@... > https://lists.sourceforge.net/lists/listinfo/click-development > ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
sabob
|
In reply to this post by Malcolm Edgar-2
Hi Malcolm,
Don't know much about Docbook but will use whichever format that makes sense. I assume the code highlighting won't fit with Docbook? > One problem with the current documention is that it is held under very > large chapters, so the TOC menu will display in smallish screens > 1024x768. I dont think this will scale well as the documentation grows > and we need smaller topic based chapters. Yes we will probably have to link to the top level doc only e.g. multi page HTML, single HTML and PDF. > > Issues I have seen with DocBook is the formatting of HTML, but I > presume this can be addressed with custom CSS styles. I think we should write an example, see how it works and decide on that? kind regards bob ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
Demetrios Kyriakis
|
In reply to this post by Malcolm Edgar-2
I think it is a very nice idea, but I also think (now) that it should be done with care (Click already has much documentation, and it looks very nice for me, so a DocBook migration should not bring worse results than the today state :) ). For the existing documentation base (not for cases starting from zero), there might be quite a few troubles. I tried to convince the author from the pretty known Swing framework OpenSwing: http://oswing.sourceforge.net/ to adopt DocBook for site and docs, and he really tried, but than abandoned the idea. See here the closed issue (and the problems he encountered, in the long comments): http://tinyurl.com/6xd98m So I think before doing such an important step, you should consider solutions to the problems discovered by others on the way. I think, if the HTML files are XHTML compatible (this can be constantly checked with tools similar to checkstyle), than there are many tools that can convert it to PDF very good (using a different style, e.g. instead of "style.css", by replacing it's usage first with a "pdf.css") So if PDF output is the only "new requirement", this can be achieved with less work than a DocBook migration. DocBook itself hasn't changed much, but the tools arround it got better. If a "manual" approach is used however, than I think DocBook is still that difficult as it was at Tapestry 2.3 time. (I listed in the comments of that OpenSwing issue many tools that help). I think the actual chapters are very nice. They just need subchapters (with numbers), and a search index to find quickly things in it. Well it's not that simple. The main issue comes from the fact that people consider the same thing a "HTML documentation" and the "HTML site", but it not what they get from DocBook. DocBook generates a very nice HTML documentation (like the one from Hibernate, or MeshCMS - the equivalent to the PDF), but that looks too simplistic for a website: it's more suited for an offline use or for print. In Click the site and the documentation is the same thing, and this is why the Click documentation is much easier to read (for me), but to obtain such thing from DocBook is not simple at all: a simple css file won't do it, so I used XSite for it. That approach I used, was for this pretty downloaded open source project: http://freemat.sourceforge.net/ by using Markdown and XSite. See a document describing how it works: http://docs.google.com/Doc?id=dfg7fx8s_0f3r89shd (it was much much simpler than forcing DocBook to generate a nice HTML Site) This because Markdown is very very like pure text, not like WIKI syntaxes (but it also has it's limits too :( ). If decide you use this Markdown approach, I could adapt my(unpublished yet) build.xml for Click too. Whatever strategy you choose, please please, don't convert the documentation to a full WIKI (e.g. Confluence), because that is a real pain in t.a. (in the last years I did much work with documentations, and mostly something that looks nice or hyped first, it's a nightmare to maintain later). Thank you, Demetrios. P.S. I think Markdown (and the generated HTML) is used in ClickClick too: http://code.google.com/p/clickclick/source/browse/trunk/clickclick/README.txt is in Markdown sytle, and: http://code.google.com/p/clickclick/source/browse/trunk/clickclick/README.html is the generated HTML (but looks simple because it's not decorated with XSite with a nicer website template). |
||||||||||||||||||
|
Malcolm Edgar-2
|
In reply to this post by sabob
On Tue, Jul 29, 2008 at 6:34 PM, Bob Schellink <sabob1@...> wrote:
> Hi Malcolm, > > Don't know much about Docbook but will use whichever format that makes > sense. > > I assume the code highlighting won't fit with Docbook? I presume in PDF it won't work, but was hoping we could use/retrofit the JS prittyprint in the HTML content. >> One problem with the current documention is that it is held under very >> large chapters, so the TOC menu will display in smallish screens >> 1024x768. I dont think this will scale well as the documentation grows >> and we need smaller topic based chapters. > > > Yes we will probably have to link to the top level doc only e.g. multi > page HTML, single HTML and PDF. > >> >> Issues I have seen with DocBook is the formatting of HTML, but I >> presume this can be addressed with custom CSS styles. > > I think we should write an example, see how it works and decide on that? OK, I will give it a try and we can see what the results look like. > kind regards > > bob > > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Click-development mailing list > Click-development@... > https://lists.sourceforge.net/lists/listinfo/click-development > regards Malcolm Edgar ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
|
Malcolm Edgar-2
|
In reply to this post by Demetrios Kyriakis
Thanks Demetrios for the feedback. Sounds like you have had a bit of
experience in this area. On Tue, Jul 29, 2008 at 8:33 PM, Demetrios Kyriakis <demetrios.kyriakis@...> wrote: > > > Malcolm Edgar-2 wrote: >> >> What do people think about using DocBook to generate Click's >> documentation as HTML pages and as a PDF document. >> > I think it is a very nice idea, but I also think (now) that it should be > done with care > (Click already has much documentation, and it looks very nice for me, so > a DocBook migration should not bring worse results than the today state :) > ). Yes. I think the Click site/documentation works pretty well but it needs to grow. How the navigation should work is a good question, and how DocBook could help with this. > For the existing documentation base (not for cases starting from zero), > there might be > quite a few troubles. I tried to convince the author from the pretty known > Swing framework > OpenSwing: > http://oswing.sourceforge.net/ > to adopt DocBook for site and docs, and he really tried, but than abandoned > the idea. > See here the closed issue (and the problems he encountered, in the long > comments): > http://tinyurl.com/6xd98m > > So I think before doing such an important step, you should consider > solutions to > the problems discovered by others on the way. > > > Malcolm Edgar-2 wrote: >> >> This has been a common request from people, can I get a PDF of the >> documentation or when is the Click book comming out. >> > I think, if the HTML files are XHTML compatible (this can be constantly > checked with tools > similar to checkstyle), than there are many tools that can convert it to PDF > very good (using > a different style, e.g. instead of "style.css", by replacing it's usage > first with a "pdf.css") > So if PDF output is the only "new requirement", this can be achieved with > less work than a DocBook migration. > > > Malcolm Edgar-2 wrote: >> >> I have shided away from DocBook after being involved in using it for >> Tapestry 2.3 (it was hard, and won't work offline) however after >> having a trial run with >> >> http://velocity.apache.org/docbook/ >> I think it has come along way. >> > DocBook itself hasn't changed much, but the tools arround it got better. > If a "manual" approach is used however, than I think DocBook is still > that difficult as it was at Tapestry 2.3 time. > (I listed in the comments of that OpenSwing issue many tools that help). > > > Malcolm Edgar-2 wrote: >> >> One problem with the current documention is that it is held under very >> large chapters, so the TOC menu will display in smallish screens >> 1024x768. I dont think this will scale well as the documentation grows >> and we need smaller topic based chapters. >> > I think the actual chapters are very nice. They just need subchapters (with > numbers), > and a search index to find quickly things in it. > > > Malcolm Edgar-2 wrote: >> >> Issues I have seen with DocBook is the formatting of HTML, but I >> presume this can be addressed with custom CSS styles. >> > Well it's not that simple. The main issue comes from the fact that people > consider the same thing a "HTML documentation" and the "HTML site", but it > not what they get from DocBook. > > DocBook generates a very nice HTML documentation (like the one from > Hibernate, or MeshCMS - the equivalent to the PDF), but that looks too > simplistic for a website: > it's more suited for an offline use or for print. > > In Click the site and the documentation is the same thing, and this is why > the Click documentation is much easier to read (for me), but to obtain such > thing from > DocBook is not simple at all: a simple css file won't do it, so I used XSite > for it. > > That approach I used, was for this pretty downloaded open source project: > http://freemat.sourceforge.net/ > by using Markdown and XSite. See a document describing how it works: > http://docs.google.com/Doc?id=dfg7fx8s_0f3r89shd > (it was much much simpler than forcing DocBook to generate a nice HTML Site) > > This because Markdown is very very like pure text, not like WIKI syntaxes > (but it also has it's limits > too :( ). Markdown looks a bit basic in its formatting capabilities, is this something you would recommend? > If decide you use this Markdown approach, I could adapt my(unpublished yet) > build.xml for Click too. > > Whatever strategy you choose, please please, don't convert the documentation > to a full WIKI (e.g. Confluence), because that is a real pain in t.a. (in > the last years I did much work with documentations, and mostly something > that looks nice or hyped first, it's a nightmare to maintain later). Ok that its interesting. I have been tempted by the WIKI approach, but I always wanted documentation to be available in the distribution or in an offline mode which didn't seem to be readily accomodated by WIKI's. > Thank you, > > Demetrios. > P.S. I think Markdown (and the generated HTML) is used in ClickClick too: > http://code.google.com/p/clickclick/source/browse/trunk/clickclick/README.txt > is in Markdown sytle, and: > http://code.google.com/p/clickclick/source/browse/trunk/clickclick/README.html > is the generated HTML (but looks simple because it's not decorated with > XSite with a nicer website template). > -- > View this message in context: http://www.nabble.com/Docbook-for-Click-documentation---tp18702596p18709305.html > Sent from the click-development mailing list archive at Nabble.com. > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Click-development mailing list > Click-development@... > https://lists.sourceforge.net/lists/listinfo/click-development > ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
|
Demetrios Kyriakis
|
Many jobs required documentation too :). Unfortunately there's no one solution that fits all :(. What and how to use depends greatly on the many factors like: - the number of users that really contriubute to the docs (not those that would just like to :) ). - the size of the text required to write - the number of consecutive changes - if it's started from zero, or a big number of pages need to be converted - how much does the existing style differ from the default values of various tools (for some tools the tunig is very hard - e.g. Apache Forest). - what type of output is desired. None of the solutions really help with the navigation, because a different navigation is required for: - online site (I think it is it's good what it is now) - offline docs/site (what docbook generates is better) - pdf (what docbook generates is better). so I think the navigation should be separated from the content, and generated at best for each output. There are many commercial tools that are free for open source projects, but most of them do not simply suply an ANT task. Something that just works with ANT is this old article: http://www.javaworld.com/javaworld/jw-04-2006/jw-0410-html.html (I think is the solution adopted by most open source projects - e.g. by Velocity DocBook too: DocBook is simply XML so it's a little simpler, but XHTML is almost the same as source, besides, for the PDF another style file can be used). Yes, Markdown is very simple. The rule is that what's not covered in Markdown, it should be done with HTML. I use Markdown: - where I have much to write, especially in a short period of time, so I can concentrate on text not style. - where people contribute that have less IT background, but I want to use their work directly (not converting all the time from something else like Word first). - where allot of diffs are required: since markdown is very close to text, the diffs are much more relevant than HTML diff. TextMate (or InType, but there's some Eclipse plug-in too), help very much to be even more productive - no web based tool can compete with it. However this is just "rough input" only to get a simple HTML, that needs to be further processed: decorated, e.g. with XSite, or a custom solution, or converted to something else like PDF (see the javaworld article). If this is all automated, than it is extremly efficient. If not, than using DocBook is simpler, so DocBook is not the "best" but pretty good for all sort of scenarios. Arround WIKIs there's allot of hype, and even if they can solve your problem (e.g. with a Maven plug-in), they're a pain on the long run, and I think this is what matters. Demetrios. |
||||||||||||||||||
Thomas Bernhard
|
In reply to this post by Malcolm Edgar-2
Please don't let the hype win again. At Apache.org this seems to happen (e.g. the Cayenne docs). I also saw other projects doing this: I believe the atlassian marketing is very happy about this :) . I worked with WIKI too (in commerials projects - driven by hype too) and I can tell you what a pain it is. It looks to me that in open source projects, people are even more prone to hype (I believe because there's no budget, or deadline), but they forget that their time is what will be lost (e.g. with the Maven move of many projects too). Even more, I converted the Click documentation to WIKI (wikibooks more precisely) here: http://en.wikibooks.org/wiki/Java_Webapplication_Development_With_Click_Framework and it was an incredible pain :(. Tom. |
||||||||||||||||||
|
Malcolm Edgar-2
|
OK thanks for that feedback.
regards Malcolm Edgar On Sun, Aug 3, 2008 at 10:16 PM, Thomas Bernhard <tbernhard@...> wrote: > > > Malcolm Edgar-2 wrote: >> >>> Whatever strategy you choose, please please, don't convert the >>> documentation >>> to a full WIKI (e.g. Confluence), because that is a real pain in t.a. (in >>> the last years I did much work with documentations, and mostly something >>> that looks nice or hyped first, it's a nightmare to maintain later). >> >> Ok that its interesting. I have been tempted by the WIKI approach, but >> I always wanted documentation to be available in the distribution or >> in an offline mode which didn't seem to be readily accomodated by >> WIKI's. >> > Please don't let the hype win again. At Apache.org this seems to happen > (e.g. the Cayenne docs). > I also saw other projects doing this: I believe the atlassian marketing is > very happy about this :) . > > I worked with WIKI too (in commerials projects - driven by hype too) and I > can tell you what a pain it is. > It looks to me that in open source projects, people are even more prone to > hype (I believe because there's no budget, or deadline), but they forget > that their time is what will be lost (e.g. with the Maven move > of many projects too). > > Even more, I converted the Click documentation to WIKI (wikibooks more > precisely) here: > http://en.wikibooks.org/wiki/Java_Webapplication_Development_With_Click_Framework > and it was an incredible pain :(. > > Tom. > -- > View this message in context: http://www.nabble.com/Docbook-for-Click-documentation---tp18702596p18798121.html > Sent from the click-development mailing list archive at Nabble.com. > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Click-development mailing list > Click-development@... > https://lists.sourceforge.net/lists/listinfo/click-development > ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
|
Ted Husted
|
One of the biggest pains of using Confluence for the documentation (as
we do for Struts) is that making sweeping changes is difficult. We are able to use the auto-export plugin to reduce the wiki site to HTML, which lets the site scale, and lets us bundle the documentation in the release download. But, it's still a clumsy solution. For an open source project, a significant benefit of wikis is that it's easier to get more people involved with the documentation. Regardless of whether it's more work for "us" or not, in the end, there can be more of "us" doing the work when the docs are on a wiki. Having used both approaches for a number of years on a number of projects, I have to admit that I am more likely to make a quick change to the wiki, because it's easy to do. OTOH, I'm less likely to attempt a reorganization of a wiki, because it's not easy to do. The converse is true for XML formats. The bottom line is that neither solution is optimal, and there are trade-offs either way. For my own work, I've been considering starting a side project on Google Code that would use Click with Velocity/Docbook and JackRabbit <http://jackrabbit.apache.org/> to create a DocBook-centric content repository platform for publishing books, articles, and project portals in online and PDF format. -Ted. On Sun, Aug 3, 2008 at 9:32 AM, Malcolm Edgar <malcolm.edgar@...> wrote: > OK thanks for that feedback. > > regards Malcolm Edgar > > On Sun, Aug 3, 2008 at 10:16 PM, Thomas Bernhard <tbernhard@...> wrote: >> >> >> Malcolm Edgar-2 wrote: >>> >>>> Whatever strategy you choose, please please, don't convert the >>>> documentation >>>> to a full WIKI (e.g. Confluence), because that is a real pain in t.a. (in >>>> the last years I did much work with documentations, and mostly something >>>> that looks nice or hyped first, it's a nightmare to maintain later). >>> >>> Ok that its interesting. I have been tempted by the WIKI approach, but >>> I always wanted documentation to be available in the distribution or >>> in an offline mode which didn't seem to be readily accomodated by >>> WIKI's. >>> >> Please don't let the hype win again. At Apache.org this seems to happen >> (e.g. the Cayenne docs). >> I also saw other projects doing this: I believe the atlassian marketing is >> very happy about this :) . >> >> I worked with WIKI too (in commerials projects - driven by hype too) and I >> can tell you what a pain it is. >> It looks to me that in open source projects, people are even more prone to >> hype (I believe because there's no budget, or deadline), but they forget >> that their time is what will be lost (e.g. with the Maven move >> of many projects too). >> >> Even more, I converted the Click documentation to WIKI (wikibooks more >> precisely) here: >> http://en.wikibooks.org/wiki/Java_Webapplication_Development_With_Click_Framework >> and it was an incredible pain :(. >> >> Tom. >> -- >> View this message in context: http://www.nabble.com/Docbook-for-Click-documentation---tp18702596p18798121.html >> Sent from the click-development mailing list archive at Nabble.com. >> >> >> ------------------------------------------------------------------------- >> This SF.Net email is sponsored by the Moblin Your Move Developer's challenge >> Build the coolest Linux based applications with Moblin SDK & win great prizes >> Grand prize is a trip for two to an Open Source event anywhere in the world >> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >> _______________________________________________ >> Click-development mailing list >> Click-development@... >> https://lists.sourceforge.net/lists/listinfo/click-development >> > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Click-development mailing list > Click-development@... > https://lists.sourceforge.net/lists/listinfo/click-development > -- HTH, Ted http://husted.com/ted/blog/ ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Click-development mailing list Click-development@... https://lists.sourceforge.net/lists/listinfo/click-development |
||||||||||||||||||
|
Ted Husted-4
|
|