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

From: Rob Stewart (stewart_at_[hidden])
Date: 2005-04-28 08:48:09

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.

> > Several years ago I had the idea that a graphical view of the library
> > categories might be a nice way to navigate among the libraries.  My little
> > prototype is still on the wiki (each category is a hyperlink to the category
> > on the libs by category page).
> >
> > http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?BoostUserFAQ
> 
> Doesn't work for me.  IMO the graphics add nothing.  Why not just a
> table if you like grids?

What about organizing the main libraries page by group (<H1>)
with a TOC of those groups.  Then, in each group, create a
secondary TOC listing each library.  For each library, provide a
link to the overview, its main documentation, its code in CVS,
and its Wiki page, if any.  (If you get to the point of providing
a download for each library, that could be listed as well.)

With so many links, it can get confusing, but I'm thinking of the
following, which could be graphically represented using icons:

<H1>Template Metaprogramming</H1>
<B>mpl - Template metaprogramming framework of compile-time algorithms, sequences and metafunction classes</B>
[Overview] [Docs] [Code] [Wiki]
<B>static_assert  - Static assertions (compile time assertions)</B>
[Overview] [Docs] [Code] [Wiki]
<B>type_traits - Templates for fundamental properties of types</B>
[Overview] [Docs] [Code] [Wiki]

BTW, there can be a link near the top to an alphabetical list of
libraries, too, since that is often just what you need.  That
list can contain the same link structure shown above (which
suggests generating it from the same source).

> > Another idea is to make get the library documentation links
> > immediately available from the front page.  Make the front page 3
> > columns and have all the libraries or at least the categories listed
> > on the left column...
> 
> That sounds like a good idea, but of course it addresses a different
> need.

That would make the front page awfully busy.

> > 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.  Maybe an all-encompassing example that uses
most of the libraries would work.  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.

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