[boost] Re: library overview page (was Re: Boost to the rescue)

From: David Abrahams (dave_at_[hidden])
Date: 2005-04-28 09:29:34

Rob Stewart <stewart_at_[hidden]> writes:

> From: David Abrahams <dave_at_[hidden]>
>> "Jeff Garland" <jeff_at_[hidden]> writes:
>> > On Wed, 27 Apr 2005 17:09:56 -0400, David Abrahams wrote
>> >  
>> >> Someone at ACCU suggested that we have a "libraries overview page"
>> >> that contains a short introduction and a mini-tutorial example for
>> >> each of the libraries.  I think it's a great idea and would vastly
>> >> increase accessibility of the libraries.
>> >
>> > Good idea, but what does it mean in practical fact?  It would be a
>> > hugely long page to have a tutorial of all the libraries.
>> 
>> Make that a micro-tutorial then.  It's supposed to be just enough to
>> get an idea.
>> 
>> > Just putting the library list no longer fits on a single page.  We
>> > already have libraries by category.
>> 
>> Yep.  It would be long.
>
> It will only get longer and that makes it harder to find what's
> really interesting on each occasion you visit that page.

The particular page being proposed isn't about "finding what's really
interesting."  It's more like a magazine about Boost and its
capabilities that you can browse through to get familiar with what's
there.

>> > Yet another idea would be to have a single page library teaser,
>> > including code example, linked available from the library list.  So
>> > a few sentences of intro text and some code examples as a really
>> > fast intro that people could scan to get the gist of the library in
>> > action.
>> 
>> That is in the same ballpark as what I suggested.  However, having to
>> click through to the material will make it harder for a user to get an
>> overall picture of what's in Boost.
>
> I don't think many users would read through one big page of such
> teasers, though.  

No they wouldn't; they'd skip over the ones that were clearly of no
interest.  The page down key works nicely.

> Maybe an all-encompassing example that uses
> most of the libraries would work.  

NooooooooooO.  Please, no!  That would introduce all kinds of
interactions and complexity.  The idea is to give people an easy way
to find out "what each library does."

> IOW, the example could build from a simple idea to a full program
> that uses most libraries with a brief mention of why each exists and
> how it would apply to the example.

To understand that you have to read through the whole thing.  That
defeats the purpose.

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