[C++-sig] Re: Example of use of indexing_suite NOT using the STL

[Niall Douglas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 10 Oct 2003 at 20:10, Raoul Gough wrote:

> > I read your docs but like most of the boost.python stuff I don't get
> > most of it. This is probably mostly my fault, however I understand
> > loki's documentation fine so I think it's a strong case of writing
> > style ie; yours is not how I think or how I write my documentation.
> 
> I haven't seen the loki documentation, but maybe I should have a look
> at it. I have to agree with you about the documentation being hard to
> follow - mostly, it makes sense only once you've already figured it
> out some other way. The trouble is probably that it is written mostly
> as a reference instead of being a tutorial or user guide. Both types
> are important to have, IMHO.

You don't need to go as far as a tutorial as they take ages to write 
and usually you have too much detail in some places and too little in 
others (hard to think like a newbie). They're also very boring to 
write when you have dozens of better uses for your time.

I personally always write reference only documentation. The big 
difference between mine and what seems to be considered normal for 
Boost is that I logically tie together how all the bits relate to 
each other in order to provide the overall solution. It's like the 
difference between Bertrand Russell's "History of Western Philosophy" 
and most other compendium of philosophy books - he said how he 
thought all the myriad of philosophies had fed into each other and in 
& out of the prevailing cultural context of the time. Thus Russell's 
book is eminently more readable and understandable than other books 
of its ilk, though of course one gets strongly flavoured by Russell's 
subjective view of things.

If you can master this ability, it only adds 20% more to the length 
of the documentation but it means more able programmers can teach 
themselves the whole system very quickly indeed without bothering 
other people. In Boost.Python's docs, the only knowledge I could 
glean about how the whole thing works was from Dave's status update 
posts and even then, those preassumed an excellent working 
understanding of how Boost.Python v1 worked.

It's very old (year 2000) but this page 
(http://www.nedprod.com/NedHAL/Docs/Core/ARM/Excepts.html) from my 
degree project gives a good idea. Reference docs about something few 
know about normally but there's enough added sugar to quickly twig 
both what's going on, but also how it works. Note I don't explain 
acronyms or do any hand holding whatsoever, but I clearly am much 
more "chatty" than you get in most technical documentation - thus 
readers get lots of hints subconsciously. And from the user feedback 
I have received, this technique is very well received (and thus I 
spend more time coding and not answering email which already sucks an 
hour of productivity from me per day).

> > Can I use your suite and not have begin() or end() methods? Indeed,
> > a C array doesn't even have length!
> 
> Well, that's actually not too hard. I haven't yet documented the
> iterator_pair template, but you can probably figure it out from the
> the getArray function in libs/python/test/testlinear.cpp

I'm still fetching Boost from CVS. It'll take another 30 mins yet, 
then I can fetch your new indexing suite. After that, I'll play and 
let you know my experiences.

Cheers,
Niall





-----BEGIN PGP SIGNATURE-----
Version: idw's PGP-Frontend 4.9.6.1 / 9-2003 + PGP 8.0.2

iQA/AwUBP4cRwMEcvDLFGKbPEQLlfQCg+k4p0iPiyu29q0YQ1Nysk6wONAUAn0VE
qhu5wedEplL1Ssoy5zWo/+69
=UMvR
-----END PGP SIGNATURE-----