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

From: David Abrahams (dave_at_[hidden])
Date: 2005-04-28 14:21:42

Rob Stewart <stewart_at_[hidden]> writes:

> From: David Abrahams <dave_at_[hidden]>
>> Rob Stewart <stewart_at_[hidden]> writes:
>> > From: David Abrahams <dave_at_[hidden]>
>> >> "Jeff Garland" <jeff_at_[hidden]> writes:
>> >> >  
>> >> 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.
>
> I think you mistook my meaning.  I meant that folks would revisit
> the page periodically to learn about libraries they didn't pay
> attention to previously.

You obviously need a different page for that; one that's sorted by
recent-ness.

> I may also have misunderstood the page you envision, but it
> sounds to me like a really long page with library after library
> of text and example code, with one mostly just running into the
> next.  

Yes one long page, but, I think we'd use dividers or major headings to
separate them.

> If you meant there would be a TOC with links to each library

Well of course a TOC would be helpful.

> and especially if you meant there would be some sort of grouping,
> then it will probably work reasonably.

Those are minor details.  The main idea is to have a brief overview of
what's available, but not so brief that you have to go look at
individual library docs just to have a sense of how it's used.

>> >> > 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.
>
> Tabbed browsing makes that palatable, even useful.

I don't see how that is related.

>> > 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.
>
> It works nicely until you get tired of paging past uninteresting
> parts.

If you're paging past most of what's there, then you wanted something
that the page wasn't designed to do in the first place.

>> > 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."
>
> OK.  OK.  It was just an idea to make it possible to show synergy
> among the libraries and to give a glimpse of what each can do.

KISS.

>> > 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.
>
> As I saw it, that example would make for interesting -- even
> compelling -- reading and would give incentive to keep reading to
> learn about all of the libraries.  Also as I saw it, yours was a
> longer read without cohesiveness.  Now I think you just mean to
> provide a small example with a little explanatory text with each
> listed library 

Yes.

> rather than the one-liner now present.

No, it's not meant to be a replacement for the existing library index.

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