Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mario Mulansky (mario.mulansky_at_[hidden])
Date: 2013-10-10 16:52:31

On Thursday, October 10, 2013 10:29:20 PM Mathias Gaunard wrote:
> On 10/10/13 21:00, Andrew Hundt wrote:
> > http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_refer
> > ence.html#header.boost.container.static_vector_hpp
> > 
> > This second link is the typical header documentation throughout boost.
> > When
> > I first started using boost it was months before I realized that in these
> > header synopsis I could click on the words of the class to see the full
> > documentation of that class,  in this case "static_vector". Much of the
> > time I just felt confused and lost. I think this is indicative of a layout
> > and user interface that needs some improvement.
> 
> Documentation like this is generated by preprocessing Doxygen XML output
> to integrate it into Boostbook and have a good look for C++ references.
> It has most of what you can expect from Doxygen + the Boostbook stuff
> which gives better cross-referencing than simple Doxygen.
> 
> I personally don't understand how one cannot notice that the blue bits
> that become underlined when you hover them and change colors once
> visited are hyperlinks (especially since that's also true for any other
> hyperlink in Boost docs and most of the World Wide Web).

I have had the same experience as Andrew. I only figured out that those are 
links when I started working on my own library docs and I _knew_ there had to 
be more information. Now surely this is embarassing from my perspective now, 
but somehow the header file doc was just a bunch of source-code to me that was 
impossible to read and handle.

> What do you suggest would be better?

Maybe it would be more readable if we didnt use a header-file based 
organization for the reference, but rather compile lists of classes and 
functions for a library. The reference for individual classes/docs are quite 
good then - once you found them.

Best,
Mario