Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-07 09:43:46

On 07/10/11 02:51, Dave Abrahams wrote:
> on Thu Oct 06 2011, Mateusz Loskot<mateusz-AT-loskot.net>  wrote:
>> In my opinion, docs formatted/presented like this
>>
>> https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/html/boost/checks/luhn_algorithm.html
>>
>> will put most readers off. Looks terrible, if I may express my
>> opinion.
>>
>> Format and layout of class documentation in the standalone version
>> is way better.
>
> Which one is that?

This is what Paul and myself call standalone Doxygen documentation

https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/doxygen/html/index.html

IOW, it's native Doxygen HTML output.

>> I still vote for Boost.Asio docs as an examplar.
>
> +1
>
> Please view http://warpspire.com/talks/documentation/

Wow! If I have known this presentation, it would have saved
me a lot of typing. Awesome!

The very first question that came to my mind, what is wrong with C++?
Why documentations in scripting world can be clean, friendly,
usable and pretty?

Looking at slides 30-37, I'm wondering...why Boost documentation
looks and feels more like a scientific paper than a handbook.
The handbooks are for mortals. The scientific paper are not.
The Boost is developed by immortals, so let them use scientific paper.
The Boost is for use mostly by mortals who need handbook, but not 
scientific paper, about Boost.

If Boost documentation (and website) aims the slides 30-37, it will be a 
rockstar documentation.

Is it possible at all?

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org