[boost] Re: Some remarks on PP docs

From: David Abrahams (dave_at_[hidden])
Date: 2004-06-11 02:07:11

"Paul Mensonides" <pmenso57_at_[hidden]> writes:

>> Also, am I the only one who 
>> finds the sparse frame-based layout to be a little 
>> counter-intuitive?
>
> It is a reference tool intended to adequately support those
> developers that are already familiar with the library--that is the
> purpose of the layout.

Which begs the question of how anyone is supposed to get familiar in
the first place without personal help from you.

Speaking as one of those who followed that route and is now reasonably
familiar, the layout isn't even very good for us.  The big blank space
at the beginning and the lack of lines around the frames are
disconcerting, but more importantly, the reference pane lumps every
macro together at the same level instead of categorizing them and
progressively revealing detail.  It would be a big help, for example,
to have a view that simply hid all of the names with _Z _R or _D
suffixes.

>> Would it be possible to make the docs look a little more
>> Boost-like?
>
> Frankly, I find the Boost-like format to be suboptimal both in style and
> navigation--it achieves a lowest common denominator worthy of Netscape
> Gold--which is unnecessary.  

I tend to agree.

> I'm not saying that the pp-lib docs look good--because they don't
> without the fonts fixed--but navigation is much easier and much more
> direct.

It's pretty good, but the reference is much too "flat".  If you really
want to help the familiar programmer, you'll use all of the
hierarchical levels you have for a categorized reference.  The parts
that familiar programmers mostly don't need to look at are currently
sucking up all those convenient navigational abilities.

> Other documentation, such as Spirit's docs and Python's "Tutorial
> Introduction" are much more pleasing to the eye and much more
> professional.  

I'd say they're very accessible but not particularly professional.
They have a "chatty", almost dumbed-down (that's too pejorative a
word, but couldn't find another) feel about them.  They're also very
"flat".  Many people find the "original iMac case" background
disconcerting.

>> I didn't get that either.  It's a shame, because there's a 
>> lot of code that would benefit from the PP lib that almost 
>> certainly isn't because of the difficult learning curve.
>
> The difficult learning curve is never going to go away.  

Mostly because you believe it can't.

> It is an alien environment that is contrary to most forms of
> programming.  That takes time to become familiar with.

That's absolutely true, but most people don't need to get far enough
along on the curve to get to the part where it really *has* to be
difficult.  I didn't get started with C++ by studying the overload
resolution rules, did you?  I still don't know many of the subtleties,
and yet I get plenty of useful work done; I even write and call
overloaded functions on a daily basis.

>> Good documentation would go a long way towards making it more usable.
>
> More usable for what?  

Weren't you the one who was frustrated by people asking "what can the
PP lib be used for?" ;-)

> I ask this simply to determine perspective.  The documentation is
> never going to tell you what you can and cannot do with the
> preprocessor or what you should and should not do with the
> preprocessor--those are all unbounded sets.  

Paul, your ability to move from the specific to the general is
awesome; it's part of what makes you such a great programmer.  Your
unwillingness to go in the other direction is a liability, though, at
least for your users.

The PP lib is really only very well-suited to algorithmic and
pattern-based C/C++ code generation.  You probably could build a
program that analyzes english sentences in PP language, but other
languages are much better suited to AI research.

> The most that the documentation can do is tell you what the
> _library_ can do and give a few examples.  

It can describe the kinds of jobs the library is well-suited to.

> Take ENUM_PARAMS for example, an extremely common use of this
> primitive is to generate stuff like "class T0, class T1, class T2".
> However, the library doesn't have a single primitive that generates
> that string of preprocessing tokens--it only has the general form.
> It could just as easily generate "0.1, 0.2, 0.3".  

And you think that's hard to explain in a way that's simple, yet
captures the generality of ENUM_PARAMS?

> The point is that the output is a function of the combination of
> primitives, user-defined macros, and input.  The library takes the
> role of a programming language.  As such, it is never going to
> answer questions like "what things can I do with 'if'?"  and "what
> things can I do with 'while'?".  

I don't know why you obsess over questions like that.  I don't think
anyone expects anything other than a reasonable answer to them.  For
example, "BOOST_PP_IF selects between two sequences of preprocessing
tokens based on an integral-valued argument" (roughly speaking).

> The library really is that low-level.  ENUM_PARAMS is about the most
> underlying-language-oriented primitive in the entire library.  There
> is definitely room for improvement, but I suspect that no matter how
> much I improve the docs and no matter how many examples that I add,
> I'm always going to hear the same old argument--the learning curve
> is too steep.  

As long as you insist that it's impossible to (or people shouldn't)
use the library without an in-depth understanding of the fundamental
operation of the PP, that will be a self-fulfilling prophecy.

> That argument is based on the assumption that documentation (etc.)
> is enough to reduce every learning curve to a gentle slope--which is
> naive.  The library is hard to learn

It doesn't matter whether the library is hard to learn.  It matters
whether it's hard to learn _to use_.  Right now, that's the case.
Most people learn much more effectively incrementally, and in
layers.  The current docs, for all intents and purposes, dump the
whole library on you at once.

> because the library is different than anything that most programmers
> have been exposed to and because the many of the techniques and
> idioms used are different than those used in every other language
> and in computer science in general.  It isn't simple, and it can't
> be made to be simple.

Sure the whole picture can't be made simple, but enough of it can be
made simple that people could get a whole lot more useful work done
without handholding from you.  With some sense of mastery under their
belts on that basis, they would be much more inclined to delve
deeper, not least because it would seem easier.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com