> Which documentation are you talking about? The stuff that's included in > the distribution?
I am talking about the hand-written documentation that is included in the distribution. The problem is that it contains flaws, and requires a huge effort to maintain it (nobody seems to like writing documentation). Having the XDoclet community (and developers) maintain the WIKI (and we all know how easy it is to update something in a WIKI) will provide better and more profound documentation. The WIKI docs not "tagged", and are not for one specific release. > If so, would this then be maintained in the wiki > instead in future? How will the build scripts include the docs in the > dist zip if they're not in the source? We need to have an offline copy > of the docs in there, not everyone is online all the time they're coding > with xdoclet. IMO we should not distribute the hand-written documentation, only the generated reference documentation, javadocs and a quick-start guide. Remember, XDoclet 2 will not include container specific plug-ins. Also, working code is always the best documentation, and we will include working examples. > And what happens when the wiki docs are updated? How > will they be versioned? At present, people can fetch an old version of > the source from CVS based on its tag, build it themselves, and have a > complete set of documentation with it. How would they do that if the > docs are only on the wiki and are no longer relevant because they're > talking about a newer version of the code? I'm tired of hearing this over and over. "Maintain backward compability!" IMHO at a certain time we should "force" users to upgrade. We have limited resources, and should try to use these as best as possible, meaning that users are not able read the documentation of a release older than 6 months. Perhaps we should vote on this? Cheers, Mathias ----- Original Message ----- From: "Andrew Stevens" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Sunday, March 09, 2003 1:08 AM Subject: Re: [Xdoclet-devel] WIKI > On Sat, 2003-03-08 at 15:39, Mathias Bogaert wrote: > > To improve communication in the community and among developers, we are in > > need of a wiki. > > Debatable, I know many (myself for one) who've never needed to use one > yet. On the other hand, if it would be a better information outlet than > the SF forums and jGuru FAQ (and more frequently visited/maintained by > the developers), then why not. > > > The idea is to remove all documentation from CVS, and put it in the wiki > > (look at Hibernate website). > > Which documentation are you talking about? The stuff that's included in > the distribution? If so, would this then be maintained in the wiki > instead in future? How will the build scripts include the docs in the > dist zip if they're not in the source? We need to have an offline copy > of the docs in there, not everyone is online all the time they're coding > with xdoclet. And what happens when the wiki docs are updated? How > will they be versioned? At present, people can fetch an old version of > the source from CVS based on its tag, build it themselves, and have a > complete set of documentation with it. How would they do that if the > docs are only on the wiki and are no longer relevant because they're > talking about a newer version of the code? > > > We would appreciate your experience and input on: > > > > 1. which wiki to use ( http://c2.com/cgi/wiki?WikiEngines ), currently under > > consideration are moinmoin and coWiki > > 2. where to host this wiki > > I wouldn't have the faintest clue since, as I said, I've never needed to > use any of them. You've yet to convince me of the need, though. What's > wrong with where the docs are now? > > > Andrew. > > > > ------------------------------------------------------- > This SF.net email is sponsored by: Etnus, makers of TotalView, The debugger > for complex code. Debugging C/C++ programs can leave you feeling lost and > disoriented. TotalView can help you find your way. Available on major UNIX > and Linux platforms. Try it free. www.etnus.com > _______________________________________________ > xdoclet-devel mailing list > [EMAIL PROTECTED] > https://lists.sourceforge.net/lists/listinfo/xdoclet-devel > ------------------------------------------------------- This SF.net email is sponsored by: Etnus, makers of TotalView, The debugger for complex code. Debugging C/C++ programs can leave you feeling lost and disoriented. TotalView can help you find your way. Available on major UNIX and Linux platforms. Try it free. www.etnus.com _______________________________________________ xdoclet-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/xdoclet-devel
