Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal review request
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-08-06 04:31:51

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Roland Bock
> Sent: 05 August 2014 22:37
> To: boost_at_[hidden]
> Subject: Re: [boost] [Concepts] Definition. Was [GSoC] [Boost.Hana] Formal
review
> request
> 
> > It's somewhat off topic, but I'm going to take the opportunity to
> > point out https://www.sgi.com/tech/stl/doc_introduction.html .  I've
> > come to believe that C++ libraries - in particular parameterized
> > types, are best described by the documentation approach embodied in
> > this link.  It is sufficiently formal where it has to be - but not so formal
that one
> gets too bogged down.
> > I've made a big point of this
> > inhttp://rrsd.com/blincubator.com/requirements_documentation/ .   My
> > criticism of the HANA documentation is really that it fails to follow
> > this format and content.

> I haven't read enough documentation on Hana to comment on that, but I agree in
> principle that uniformity, consistency, use of concepts etc are extremely
useful to
> enhance documentation. I have my doubts though, that the STL documentation
> structure can be used as-is in a reasonable way for every library.
> 
> For instance I would not know how to do that for sqlpp11, but I would love to
> discuss it over a beer at CppCon.

I've already said the same for other libraries documentation.

IMO the STL docs structure doesn't work well for anything but trivially (but
invaluable) small libraries.

It's the lack of hyperlinks and indexing - the "how do I find what I want to
know when I'm not even sure yet what I want is called?" problem.

People get obsessed with the look rather than how documentation works.

We haven't cracked this yet.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]