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

From: Rob Stewart (stewart_at_[hidden])
Date: 2005-04-28 12:00:10

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.

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.  If you meant there would be a TOC with links to each
library and especially if you meant there would be some sort of
grouping, then it will probably work reasonably.

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

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

> > 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 rather than the one-liner now present.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;