Fwd: [Python-Dev] Primer on distributed revision control?

John Yates jyates at netezza.com
Tue Mar 25 19:44:21 GMT 2008


Ian Clatworthy write:

> Any reason why you prefer the Hg book to the Bazaar User Guide?
> While I got a lot out of the Hg book when I first read it 12-18
> months ago, my feeling at the time was that the material could be
> much better organised, and that it focussed too much on internal
> data management and not enough on good processes and supporting
> procedures. I wrote most of the opening chapters of the Bazaar
> UG reflecting these biases, so I'd like to know what we could do
> to make it better and more useful to the kind souls who actually
> read documentation. :-)

First let me say that I have seen the bzr documentation progress
tremendously since Ian has seized ownership of it.  Still I concur
with Paul that I find reading the hg manual a more satisfying
experience.  Let me see if I can explain why.  Please bear with me
as I come at the explanation somewhat circuitiously.

Years ago as a budding compiler writer, sometimes language designer
I had a painful but ultimately instructive interaction with my tech
writer.  We were building Vax Pascal V2.  V1 had been a simple port
of Niklaus Wirth's compiler and supplied printed copies of documents
already floating around the Pascal community.  V2 was a clean slate
effort.  Along with a state of the art backend we included many
language features to support systems programming.  You may  get some
sense of the scope of our language extension when I tell you that we
added an attribute framework akin to gcc/g++.  Attributes on types,
variables, formal parameters, fields, aggregates, etc. included
size, alignmnet, and volatile.  It took some significant effort to
pin down our attribute propagation and compatibility rules.

With the end of a multi-year development project in sight attention
turned to documentation.  My writer, one of the brightest, most fun
I ever worked with, presented me with an attribute write-up that made
me cringe.  As a progammer, language designer, and frontend-writer I
viewed the documentation task as expository: present the concepts,
define the new syntax, define the well-formedness rules and semantics;
maybe provide some carefully chosen examples to illustrate obscure
corner cases.  What I got was a cookbook of recipes.  Fundamentally
a collection of "If you want to achieve X Vax Pascal V2 allows you
to write Y."  Interspersed here and there were statements of the
form "You cannot write Z."

I explained my profound dislike of this documentation.  My writer
understood completely.  Being bright and analytical she even agreed
that she herself preferred the form of documentation I desired.  The
problem was that DEC had invested significant money and time into
studies that purported to show that users prefered what the company
called "task oriented" documentation and hence that is what the
members of the documentation group were required to produce.

My insight was that there are folk who just want to master process
with minimal time spent on model development or internalization.
Such folk differ profoundly from those who, without a model, feel
lost and adrift.  I, and I think many programmers, fall into the
latter category.

To bring the discussion back to hg vs bzr documentation I would say
that hg definitely invests effort in attempting to get across a model
of how the system works while bzr documentation tends to be much more
prescriptive in nature.  I agree that the hg documentation could be
criticized for being too concrete about how the system operates.
OTOH, if one has to err, I prefer hg's concrete details to bzr's
vagueness.

In one of the many threads occasioned by RMS's expressed preference
for bzr there was a good example of the importance of getting across
a model.  Although I do not have the post to quote at the moment the
author wrote of how much more had appreciated git once he grokked the
model of a single DAG and heads as references to points therein.

I think that part of the slant in the bzr documentation is the notion
that the system should be so imbued with DWIM-ness that the need for
crisp documentation is minimal.  That that mindset also seems to lead
to tolerance of sloppy use of terminology: terms are used as casually
in documentation as they are in conversation.

I remain deeply biased towards a set of "Rules of naming" taught to
me by one of me earlist mentors.  He asserted that "Ninety percent of
the documentation in any system is in the choice of names."  His five
rules were:

1) Every concept has a name.
2) No concept has more than one name.
3) Distinct concepts have distinct names.
4) A compound concept is named by a predictable composition of the
   names of it component concepts.
5) No application of a name violates connotation nor the audience's
   preconceptions.

I find that bzr's general terminology, its help texts and its written
documentation violate these rules often enough to leave me forever
slightly frustrated.  And that in spite of following the project pretty
much since day one.

/john



More information about the bazaar mailing list