Re: [boost] Call for Review: Boost.Test documentation rewrite

Subject: Re: [boost] Call for Review: Boost.Test documentation rewrite
From: Rob Stewart (robertstewart_at_[hidden])
Date: 2014-01-22 04:36:45

On Jan 20, 2014, at 2:48 PM, legalize+jeeves_at_[hidden] (Richard) wrote:

> boost_at_[hidden] spake the secret code
> <561059F5-FA00-4F37-87AD-22C04C4C8DAC_at_[hidden]> thusly:
> 
>> It sounds to me as if you both want useful documentation for Boost.Test, and have been willing to cooperate. Gennadiy has expressed ongoing
>> interest in collaborating on documentation for the new APIs. Richard, if you're still interested in helping, can you agree to help on the new
>> version? If not, Gennadiy's idea to link to your docs for the old, soon to be deprecated, interface seems appropriate.
> 
> I was told that the documentation can be updated at any time and isn't tied to a particular release, unlike features.

I don't know who told you that or why, but Boost documentation is release specific. How can it be otherwise? Each release can have different functionality.

If you meant that it's possible to replace the latest releases docs at any time, I think that's possible.

> I don't understand why we can't update the documentation *now*, make things better *now*, and get on with incremental improvements after
> that.

I didn't mean to suggest that yours couldn't be pushed as the latest, but that it would become the old, deprecated features documentation once the new API was documented, reviewed, and accepted.

> The documentation for this library has a long history of not being updated promptly and new features lagging for a long time.

I would certainly require a very long time to create and update docs in French, though I know a little of that language, so I can understand Gennadiy's slowness. I don't recall how proactive he was in seeking help.

> Why can't we simply make things better immediately and then look at anything that is new?

It's fair to say that many are inclined in your favor. Gennadiy has said your docs don't document the new state of the library, so yours will be short lived if the new state is adopted fairly soon. OTOH, if the new APIs are rejected, releasing the new version will be delayed or never occur making your version long(er) lived. Given the idea of linking to your version as documentation of the deprecated APIs when (if) the new version is released, your docs will be useful for some time either way, and that bolsters your case. Still, the question remains whether you're willing to document the new APIs, too.

___
Rob

(Sent from my portable computation engine)