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

From: Paul Baxter (pauljbaxter_at_[hidden])
Date: 2007-08-13 16:03:22

>> 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?'.

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.

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

I don't want to be overly critical of your work in progress, so what sort of 
comments are you looking for?

I started off going through page by page, but it became apparent early on 
that my comments might be getting counter-productive. I've left them below 
but don't take them to heart, please.

Paul

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

 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)?
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? 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?

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
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.

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

-------------------
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.
- Footnotes at the bottom of the page do not seem appropriate to this page

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?

  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>'

  Link to release notes?

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?

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, organisation 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).

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

3) FAQs - agree largely with Peter Foley's comments. At least in the FAQ, 
could you put 'Unit Test Framework (UTF)' at least once in this page so that 
people who are really new, instantly understand without a glossary at hand.

With a new library I usually visit - introduction/overview then 'guide for 
the impatient/getting started if available and FAQ before I wade in any 
further.

These should be free from too many three letter abbreviations (TLAs) if 
possible.

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.