From: Joel de Guzman (joel_at_[hidden])
Date: 2003-11-02 21:57:57
David Abrahams <dave_at_[hidden]> wrote:
> "Peter Dimov" <pdimov_at_[hidden]> writes:
>>> Besides, doesn't "LWG ready" imply formal language that is not
>>> desirable for "normal" documentation?
>> In my opinion, a reasonably tight definition doesn't necessarily
>> imply formal language, although formal language makes the task
>> considerably easier for non-native speakers, at least. In other
>> words, informal descriptions are acceptable as long as the
>> informality isn't used to avoid doing the work.
> The hard part about formal documentation is that (painting with a
> broad brush here), people don't read it. Tutorials are of course very
> helpful, but if you supply one, many people will stop there. I'm
> beginning to think it would be best to try adopting an "annotated"
> style of formal documentation, much like the original C++ ARM did, to
> help people navigate it... but that's just speculation.
I agree 100%!!! The ARM taught me C++ more than any book I can
-- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk