David Abrahams wrote: > "Edward Diener" <[EMAIL PROTECTED]> writes: > >> David Abrahams wrote: >>> "Edward Diener" <[EMAIL PROTECTED]> writes: >>> >> I am always surprised when programmers, such as yourself in this >> instance, react so vehemently to those who suggest that >> documentation can be better in any respect. I don't think of writing >> documentation as easy, and I am sure my own is as flawed as much >> other documentation is, but the merest suggestion to improve >> documentation standards for programmers always meets with a similar >> response which you have given here. > > Not from me. I'm always one for better documentation, and you'll note > that I instituted just such a changelog for Boost.Python not long ago; > it's a good idea. What I was reacting to was the insulting suggestion > that library authors who don't publish the ChangeLog you want are > poorly educated.
I didn't say that at all and I do not think it is reasonable in any way to infer that from my remarks. > This is hardly first time we've been over this > ground: > > http://lists.boost.org/MailArchives/boost/msg38799.php > http://lists.boost.org/MailArchives/boost/msg38801.php > http://article.gmane.org/gmane.comp.lib.boost.devel/11576 These are irrelevant to the present post. > >>> It is difficult and time-consuming enough to write coherent >>> user-level documentation as required by Boost that IMO it's >>> unreasonable to demand implmentation documentation at the same >>> level. >> >> All I asked for is that when changes were made between releases to a >> library a small amount of documentation be given which elucidates >> what those changes were in a general way. It would help both users >> of a Boost library and 3rd party developers of a Boost library, as >> it would enable both parties to track general changes and adapt >> their understanding of the library from within their own code to >> those changes. > > That said, I thought you were asking for something else, and I > probably overreacted a bit: I'd been up all night and my nerves were a > bit frayed. OK, I am not out to create more work needlessly for developers and I am not targeting any individual here in my remarks. Encouraging programmers to document what they are doing better shouldn't be something which generates such antipathy simply because many programmers see it as unnecessary and needless effort. I do not know how to explain it better but I think that the ability of programmers to explain their ideas and thinking clearly is of great importance, not only for them but for the users of their software. My remark was just a suggestion, not an attempt to establish a rule. But if it leads to having library implementors documenting the major changes that occur in their library from release to release, I think it will do an important service to the many users of those Boost libraries in the C++ community. _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
