[C++-sig] Re: Example of use of indexing_suite NOT using the STL
s_sourceforge at nedprod.com
Fri Oct 10 22:08:31 CEST 2003
-----BEGIN PGP SIGNED MESSAGE-----
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.
-----BEGIN PGP SIGNATURE-----
Version: idw's PGP-Frontend 188.8.131.52 / 9-2003 + PGP 8.0.2
-----END PGP SIGNATURE-----
More information about the Cplusplus-sig