Re: [boost] Boost.Test documentation update;alpha release

From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2007-08-14 00:20:59

"Paul Baxter" <pauljbaxter_at_[hidden]> wrote in message 
news:BAY144-DAV173B3621EBC31CAA3BEF9AB5DC0_at_phx.gbl...
>>> The release is available here:
>>>
>>> patmedia.net/~rogeeff/html/index.html
>>>
>>> in patmedia.net/~rogeeff/src you can find sources.
>
> Thanks for devoting effort to updating the docs of this important 
> library..
>
> My first impressions as a likely new user of Boost Test is, not very good,
> I'm afraid.
>
> I don't find a clear statement of intent or capabilities beyond a one 
> liner.
> It goes straight into the heart of things next without answering my basic
> question, 'what can it do for me?'.

Yes. For a long time I am looking for someone to write some introductory 
paragraphs for the library. I am not that good with these things. Any 
volunteers please speak up.

> When I get into the various sections, it is difficult for me to grade
> information as critically important, useful user background, an
> implementation quirk or gotcha, a limitation etc.

Can you give an example annotated with how would you prefer it to look like?

> Perhaps its more about the documentation needing some more consistent
> *organization* of the information rather than the content itself.

What wrong with current organization?

> ---------------------------------------
> As a reasonable focus for people without much time, perhaps they could 
> take
> a look at say 'execution monitor'.

execution monitor is not probably the best component to start with.

> Look at the compilation page for Execution monitor for instance.
> http://patmedia.net/~rogeeff/html/execution-monitor/compilation.html
>
> There are only a few sentences but I'm left reeling.
>
> That 'one source file', is it a .hpp or a .cpp or both (broken link refers
> to a .ipp, text refers to a .hpp and later a .cpp)?

Exact wording:

"The Execution Monitor is implemented in two modules: one header file and 
one source file."

difference between .ipp and .cpp is technical and I plan to explain it in 
"fine print"

> Your text: 'In some cases you may want to include the source file along 
> with
> header file into your sources. But be aware that ...this file will bring a
> lot of dependencies.'
>  - well should I use it or not?

Should or should you use it depends on you need. These section describe how 
you can use it (if you decided to)

> Is there a lightweight alternative if I
> just want to catch some types of errors? If its good enough to be used as
> the basis for core components in boost.Test, why should I be concerned 
> about
> all the dependencies it brings in?

I am not sure what you are trying to say, but the statement is just trying 
to explain the consequences of including the execution_monitor.ipp into your 
source file.

> Next page: Execution monitor user guide
> http://patmedia.net/~rogeeff/html/execution-monitor/user-guide.html
>
> Lots of really good information but its style makes it hard work to wade
> through.
>
> Perhaps make it more explicit:
>
> What does the function do
> What are its parameters

This is in reference section

> What are its quirks and limitations
> Tips on how to use it
> Advanced features
>
> All questions are answered there somewhere, but its quite difficult for me
> to take it all in because of the form in which its presented.

I am not sure how to fix above, but accidentally I found that 
execution_monitor::execute usage description is completely outdated and 
incorrect. This one is fixed ;))

> Having read the much better introduction to the next section 'Program
> execution monitor' I ask myself why I just spent time with 'execution
> monitor'

Ummm. These are two different beasts.

> -------------------
> Here are a few other ad-hoc comments
>
> 1) Front page:
>
> - Email address at top of page has an unfortunate mis-spell of the word
> 'account'
> also since your account is boost-test@  etc  you might want to remove the
> confusing use of hypen to also delimit other words e.g. -at- -dot- etc.

Fixed

> - Footnotes at the bottom of the page do not seem appropriate to this page

Yeah this is bug in BoostBook

> 2) Introduction:
>
>  First paragraph:
> 'The Program Execution Monitor is also useful in some production 
> (non-test)
> environments' doesn't really help. What is it; is it different from the
> 'matched set of components ...controlling their runtime execution' you 
> refer
> to in the previous sentence?
>
> Perhaps a sentence or two to distinguish the capabilities for the four 
> parts
> referred to on the contents page as I to IV?

Yeah. Intro is desperately needs couple paragraph update.

>  Portability para:
> 'Boost.Test internal tests have been run (and work) under numerous
> compilers....'
> Perhaps reword. e.g.
> 'Boost.Test supports all main Boost compilers and platforms. Confirmation 
> of
> its status on core and additional platforms/compilers can be seen by 
> viewing
> Boost.Test's own internal regression test results <here> and <here>'

Ok. Updated.

>  Link to release notes?

Where?

> General comment. This page is perhaps an ideal one to briefly describe a
> little more about the capabilities first and an outline of components 
> within
> Boost Test. Perhaps a picture capturing the essence?

Which page?

> At present as a new reader I still know very little about the scope of 
> this
> library. (I know you have the material later but an overview here wouldn't
> hurt).
>
> I think in terms of my unit tests, organization of those tests into 
> suites,
> how info is reported/displayed, what helper functions/capabilities would 
> be
> good (compile time asserts, error trapping/reporting). I want to know that
> this library addresses my problems (and I know it does and gives me so 
> much
> more).

Can you provide specific paragraphs and where you want them?

>
> Not sure I'd put FAQ and open issues as sub-sections under introduction 
> ....

See below

[...]

> 4) Open Issues
>
> 5) Execution Monitor
>
> Not sure this is best placed as the first section after introduction. It
> appears from what I read up to this point that it is a core low-level
> building block and at this point I'm thinking, well is this an
> implementation detail or an advanced feature or something I should care
> about right now. It hides lots of mess, but should I, as a user, care 
> about
> it?
> Probably yes, but I'm not sure.

I guess I need big clear disclaimer somewhere at the very beginning, but the 
Boost.Test documentation is not intended to be read from top to bottom, like 
a book. I had a hard time ordering different parts of docs. Should execution 
Monitor goes first or last? On one hand it's implementation details for 
majority of the users, but on the other hand it referenced in UTF - so it 
should be explained before - and in general is standalone Boost.Test 
component. Where should "open issues", "portability", "release notes" 
sections go: at the beginning or at the end. At the end I decided to follow 
regular site order where these items are accessible from top level or in 
this case at the beginning. I am open to suggestions though.

Regards,

Gennadiy