Georg Rehfeld wrote: > Hi, > > note, I'm not complaining about bad JBoss docs, I find them brief > and enhancable but covering most important things yet, but And I'm not saying that documentation shouldn't be improved, but I think that much of your argument here is actually for requirements specification, not user documentation. > > Scott M Stark said: > >>3. Read the ultimate docs(the source) ... >> > > I don't agree with this, the ultimate doc is the doc! The > importance of documentation was addressed by SUN with the > JavaDoc tool for low level docs, but the rule applies to high > level docs too. OK, how about: "the authoritative resource describing the behavior of a software system is the source code." Yes, source != documentation, but if you want to know how something works, the source is far better than documentation. Documentation lies. Just read some documentation from proprietary tools! I just went through this argument with the support staff of another (commercial, proprietary) application server: we were getting a NullPointerException from their code, and it took a week to persuade them that maybe they should look at the source to determine what might be null. This is the strength of open source software: if it's behaving in a manner you don't understand, you can read the code! If you want free lunch, get a sales guy to take you out. If you want working software and self-determination, use open source software. > > The 'ultimate docs are the docs' rule especially is true for > Interfaces, The 'ultimate doc' in that case is the ejb 1.1 specification. > > One heavy pitfall of the 'ultimate doc is the source' rule is code > containing a bug. You never should assume that the existing code > is to be interpreted as the doc, which would declare the bug to > be the intended behaviour. again, deviation from specification is a bug. But now you're also bringing requirements documentation into the discussion. This is a completely separate thing from user documentation. I'd hate to refer to requirements docs to find out how to do something - especially for an infrastructure tool like JBoss. How often to you refer to POSIX doco when you want to get something done on *nix? > But without docs, how could the bug > ever discovered (except for really obvious ones)? By a human, > often the author himself, knowing or guessing the INTENTION of > the code and comparing the intention <=> documentation deviation from _requirements_ is a bug: deviation from documentation could be a documentation bug _or_ an implementation/design bug. > > Another example: I once had a *.properties file with duplicate > keys (by intention, don't tell you the whole story here) and > wanted to know how java.util.Properties would deal with that. > The docs for Properties.load() are lengthy about the expected > format, but say nothing about dups. So I looked up the impl and > found, that the last duplicate key/value pair in the file was the final > result. Should I now use this knowledge and rely on that behaviour? > Never! Because the impl at any time can change without notice, > the behaviour is undefined, so don't use it. Else you would > introduce very subtle and difficult to find bugs whit the next > JDK or with some subclass of Properties, that does other things > and so on. > > Having said that back to work. > > And please know, Scott has given sooo much source AND documentation > to JBoss and advice to users on this list that nobody of us avarage > readers here ever can keep up with him. > > Very respectful > Georg > ___ ___ > | + | |__ Georg Rehfeld Woltmanstr. 12 20097 Hamburg > |_|_\ |___ [EMAIL PROTECTED] +49 (40) 23 53 27 10 > > > > _______________________________________________ > JBoss-user mailing list > [EMAIL PROTECTED] > http://lists.sourceforge.net/lists/listinfo/jboss-user >
Confidential e-mail for addressee only. Access to this e-mail by anyone else is unauthorized. If you have received this message in error, please notify the sender immediately by reply e-mail and destroy the original communication.
