Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2017-08-14 15:29:42

2017-08-14 16:37 GMT+02:00 Robert Ramey via Boost <boost_at_[hidden]>:

> On 8/14/17 12:40 AM, Andrzej Krzemienski via Boost wrote:
>
> I do not know anything about the project, so I am not really addressing
>> your question,but I wonder how it is possible to get a unified look and
>> feel across all the libraries when library authors are given freedom to
>> use
>> whatever format for their documentation, whatever tool, and whatever
>> approach to documentation.
>>
>
> I don't think it is possible.
>
> This leaves us with a couple of options:
>
> a) Enforce the usage of boost book for documentation as condition of
> acceptance and inclusion of a library in boost. This would guarantee
> consistent look and feel across libraries.
>
> b) Encourage everyone to "do their own thing".  Which would almost
> certainly result in a wide variation of look and field.
>
> c) Improve the boostbook documentation and related tooling to make it so
> compelling that only an idiot or egomaniac would decide not to use it. This
> would be the best of course.  But it's a lot of work and we're not there
> yet.  And of course in any large organization, there's always a couple of
> idiots/ecomaniacs or people who act that way on an occasional basis.
>
> Actually, this was the motivation for my post.  I think when this
> initiative was announced we were on the right track.  But I think we lost
> our way on this one.  I don't know if it's possible to all get back on the
> same page, but it would be a good thing if we could.

I do not even know if there is a consensus about what "look and feel" is.
Is it only the fonts and colors, or is it also the same structure of
documentaion in all libraries: short intro first, then tutorial, then
reference section. If the latter, according to my knowledge, boostbook does
not offer the ability to generate reference from source code annotations,
so it might just put off people. You need to set up a collection of
additional tools.

This apart, some libraries have only plain HTML documentation, and some do
not have it at all, so they would benefit immediately from being converted
to boostbook.

Regards,
&rzej;