[boost] Re: Divergent Paths in Boost?

From: David Abrahams (dave_at_[hidden])
Date: 2003-11-01 15:37:45

"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.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com