[Samba] It would seem to be simple but it's got me scratching my head

[John H Terpstra]

On Thu, 18 Dec 2003, Craig White wrote:

> I am so honored that you took the time to help - now that I finally
> slurped it and got it all configured - even on self generated
> certificates - LDAPS - this has been the experience that I really feel
> as though each lesson was learned after hours of head banging.

No meed to feel too honored. Samba is a bit of a preoccupation of mine.
I started to update the documentation to help reduce to level of pain we
see on the mailing list.

I feel sorry for Jerry Carter and Jeremy Allison. I have bugged both of
them to death to get myself up to speed so that I can document this stuff.

What bugs me more than anything though, is the realization that it is
impossible to write crystal clear documentation that everyone can read and
understand. Even more so, it is impossible to clearly index what has been
written so that everyone can find what they are looking for.

The problem is human nature - dang, it gets right in the way of finding
answers! When we get all heated up by frustration the neuron transmitters
and receivers of the brain somehow don't work the same way as they do when
we are calm. :)

I love it whan someone says, "The Samba documentation is confusing!" It is
true - everything is confusing when your head is all clouded up. But how
can we avoid that? I am seriously searching for that magic manner of
expression that gets poor befuddled people out of the rut.

The writing of the new book "Samba-3 by Example" is a big challenge. I am
finding the going much slower than expected. The example cases are so
simple in concept, but good example solutions are difficult to prepare and
take an incredible amount of preparation.

One has to choose real examples, communicate real problems clearly, and
then deploy the solutions in such a way that the un-initiated can make it
work.

No sooner do you get it straight, and a vital piece of software is updated
and things no longer work. Writing examples of implementations that are
platform agnositic is a joke. It does not happen - the Encyclopedia
Britanica would be too small to contain all the permutations and
combinations of potential glitches.

There is a world of difference between being able to install software and
make it work, and writing clear instructions that someone else can follow.
For that, one has to crack the edges off many areas, realise where people
mis-read, mis-implement, etc. and then document all the tid-bits that
matter. I find it takes around 6 repeat installs of every example to find
the warts.

I can assure everyone, writing documentation is a thankless, exasperating,
and largely unrewarding exercise. And just for the record: I go through
exactly the same head-banging as everyone else (just ask Jerry! :)).

So from someone who has been humbled and who knows how it feels, noone is
alone in the pain they suffer through learning, finding bugs, and finding
rewarding solutions. Fight on! The victory is sweet! :)

Cheers,
John T.
-- 
John H Terpstra
Email: jht at samba.org