Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-14 15:43:04

On 8/14/17 8:19 AM, Vinnie Falco via Boost wrote:
> On Mon, Aug 14, 2017 at 8:15 AM, Edward Diener via Boost
> <boost_at_[hidden]> wrote:
>> ...others think having the same look-and-feel of all
>> Boost docs is an advantage.
> 
> I'm one of those people. Some of the folks working on Boost I have
> interacted with seem to think that the success of a library or project
> will/should depend solely on its technical merits. I don't share that
> view, I think that the presentation matters. In other words the way
> that the "product" (Boost, or a particular library in this case) is
> "marketed" to users.
> 
> Engineers might find it distasteful or not "pure" that such factors
> play a role in the success of a library but that is the reality.
> 
> For this reason I think that the uniformity of "look and feel" of the
> Boost documentation is one of its strengths. It is a signal of
> attention to quality. 

Actually, I'm in agreement here.  But it also means that we have to come 
to some consensus about what that "look and feel" should be.  These 
debates are actually tiresome to me and I believe are mostly 
unproductive. What I would like to see is that the tools for creating 
documentation be sufficiently appealing that that it's worth using even 
by those who would say - "I'm not all that crazy about the look and 
feel, but it's not worth investing effort to change"

Personally I think the documentation tool chain has a lot of stuff 
that's right.  But I would like to see it developed so that it would be 
better.  But reaching consensus on doing this is also a big obstacle.

I know the toolchain can be difficult. I feel
> that the results are worth it.

Right - I would like to see the tool chain much easier to use.
> 
> Thanks
> 
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
>