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

From: Paul A Bristow (pbristow_at_[hidden])
Date: 2007-08-14 04:24:18

>-----Original Message-----
>From: boost-bounces_at_[hidden] 
>[mailto:boost-bounces_at_[hidden]] On Behalf Of Gennadiy Rozental
>Sent: 14 August 2007 04:07
>To: boost_at_[hidden]
>Subject: Re: [boost] Boost.Test documentation update; alpha release
>
>
>"Paul A Bristow" <pbristow_at_[hidden]> wrote in message 
>news:003101c7ddc8$50ac1100$0400a8c0_at_hetp7...
>> 1  First line 1 space indent is a bit odd - not enough to be a real 
>> indent.
>> And anyway I don't think indents help!  so I'd go for now indents.
>
>Umm. Why?  Isn't it kinda standard?

Well no other Boost docs use first paragraph line indent.  And I single character width looks odd to me.  I think indents are a bit
last year ;-)
So I would follow the Boost style.

>> 3  You must explain what a UTF is before using the acronym.
>
>It is explained in first paragraphs of user's guide.

Ah - but I didn't read that first!  And most people will not be too much the wiser on learning it is an acronym for Unit Test
Framework either. Assumption is the mother of all misunderstandings.  Why Unit they will ask?  Why Framework?  Of course there are
good answers to these things, but they don't want to have to know that - at least yet.

>> 5  The minimal testing facility supplies it's own ... should 
>its ( it isn't it is, is it!)

>Sorry, I a bit lost in these "it" and "is". What did you mean?

Sorry my joke fell on it's head.  I was chiding you for using 'it's' (abbreviation for 'it is') when you should have used 'its'.  A
common mistake.
Rule of thumb - use its and you will more often be right.

>
>> 7  I would break up the code and 'inline' the comments.  It 
>makes it much 
>> more difficult to read having to go down to (1), and then
>> (2) ...  But I'm sure you're tired now ;-)  But for future 
>reference... 
>> (using the code blocks syntax for the code)  For example:
>>
>> // seven ways to detect and report the same error:
>>
>>  BOOST_CHECK( add( 2,2 ) == 4 ); // continues on error
>>
>> displays an error message (by default on std::cout) that 
>includes the 
>> expression that failed, the source file name, and the source
>> file line number. It also increments an error count. At program 
>> termination, the error count will be displayed automatically by the
>> Unit Test Framework.
>>
>>  BOOST_REQUIRE( add( 2,2 ) == 4 ); // throws on error
>>
>> similar to approach #1, except that after displaying the error, an 
>> exception is thrown, to be caught by the Unit Test Framework.
>> This approach is suitable when writing a explicit test 
>program, and the 
>> error would be so severe as to make further testing
>> impractical. BOOST_REQUIRE differs from the C++ Standard Library's 
>> assert() macro in that it is always generated, and channels error
>> detection into the uniform Unit Test Framework reporting procedure.
>>
>> ...
>>
>> Since this section is what most people want to start with, 
>it would be 
>> worth splitting it up?
>
>This is not how DocBook based documentation look like usually. 
>Callouts are located after the source code.

I know - I *HATE* it!  It's madness - why would you want to make people flick their focus back and forth?

>> 8  Mention pre-built libraries - bjam never works first time :-(

>Were? Can you provide exact wording?

" [@http://boost.org/more/getting_started/index.html Boost Getting started] also tells you how to get pre-built libraries for some
platforms."

If avilable, this is much the easiest option.

>> 9  Admonishment Important duplicates on Standalone library 
>compilation.
>
>Which page?  I do not see it.

All the admonishments display for me as [important]Important.  But porbably these will disappear when installed in the right place.
>
>> 10  It would help if you said in the Including the UTF 
>directly into your 
>> test module section that recompilation will *slow down*
>> your 'compile, run, crash' cycle ;-)
>
>I kinda saidit with last statement isn't it? The thing is it's 
>not that significant this days to emphasise it too much.

Well only kinda.  You could say "If you find the compile time becoming tiresome, try using linking to a library."

>> 11 It didn't quickly see the thing I need most, most often - 
>a list of the 
>> macros
>>
>> BOOST_CHECK ...
>>
>> Eventually I found 'The UTF testing tools reference' but 
>only by accident.

How about calling it 

"Test MACROS (BOOST_CHECK*...)"  ? 

or something that doesn't require you to know what UTF stands for.

>> 15 Test progress display is blank.  TODO?
>
>Yep. R u up to it?
>
>> 16 I don't like the output in white on black, but taste in 
>'color' is *very* subjective - and some people have no taste at all ;-)
>
>I wanted to mimic regular shell window output

Yours might look like that -

Mine has a lime-green background with fuschia characters ;-))

(Just kidding - it's black on white!)

A final comment - I think you should take most note of the 'novices' recent comments.  I think it is the *structure* that has caused
so much grief in the previous version - and that hasn't changed much.

You are disadvantaged by having too much knowledge.

Users *don't* want it in a logical layout - they *don't* want to know about things they won't use until they have used the basic
"add 2 + 2 and check it makes 4" unit test.

So make sure the first thing they hit is what they need to know.

*Examples* are the quickest way of doing this.  The testing the string class is excellent, so make sure that this is what jumps out
and hits them.

And when they get going, the bit they keep coming back to is the macros, so make sure that hits them too.

Good luck!

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]