consider yourself upgraded in my book! ;-) Danny Angus wrote: >>or something as >>fundamental as the correct documentation for how to setup a database URL >>(which is correct in the CVS, and wrong in the current download). > > > If this is the case it because the docs have been fixed. > > And.. you should only consider the relevance of the stable "release" > versions' documentation, the "latest" and "nightly" builds are strictly > snapshots of work-in-progress, as such they should not be expected to > function, nor should documentation be expected to be correct in any aspect. > > Furthermore James has never released a Beta quality version yet, all the > releases so far have, for various reasons, been considered to be Alpha > quality code. > > I subscribe to Andy's opinion that James is hard for a new user to get > started with, because I have had to nursemaid many such users through their > first experience with James. > > In addition to documentation making life easier for users remember also that > a +1 vote for a release binds the voter to support that release by > participating on the developers and users lists. This is a great incentive > to commiters to produce clear and accurate user documentation, and clear and > accurate code documentation. > > IMHO while the XP case for not documenting code is based in part upon the > assumption that the code should be easy to follow and documentation ca be > used to avoid writing clear code, it does not follow that concise targeted > code documentation obfuscates the code. > > I rather believe that good javadoc documentation can encourage encapsulation > and re-use by removing the necessity for programmers to concern themselves > with the detail of code not directly relevant to the issues they are > addressing, revealing method signatures and documenting their intended use > cannot, surely, be counter productive, particularly in an OSS project. > > Take a look at the Tomcat javadocs, they reveal the architecture of Tomcat > in just enough detail for an outsider to extend and adapt the product, > without explaining away bad practices, or forcing you to read the code > itself. > > I strongly believe that code documentation should be a halfway house between > user documentation and the code itself, providing a convenient and easily > navigable journey through the architecture, un-encumbered by the > implementation details. > > d.
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
