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.