Re: [boost] Re: Divergent Paths in Boost?

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 
think of. 

-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net