Ned Konz <ned at bike-nomad.com> wrote:
> I think some have been afraid to write such a book because of the rate 
> of change in Squeak. When Squeak was being banged on heavily by 
> Squeak Central, we would see changes added to the update stream that 
> would appear "out of the blue". The rate of change in the distributed 
> image has been pretty high in the past.
Your right the rate of change was and is a problem. I think, however,
it's more a percieved problem than a real one. Linux changes too, all
the time, at a much higher rate than Squeak, but it has lots of
documentation. How do they keep it up to date? well, they don't
strictly. It's a matter of expectations. If you're reading a HOWTO, you
know it'll focus on the ideas, and if the name of the option has changed
since, you'll use --help, too, and figure it out. Taking the attitude
that documentation doesn't have to be perfect, but merely point at the
scheme of things, and give you a good feel for what things look like
(alot of pointers to methods, even if the name might change on a few of
them), it's not nearly as hopeless as it may seem.

A big issue here is in putting things where they'll be found, in the
Swiki, and that people occaisonally take charge, update, edit and
refactor the Swiki to keep it alive. The recent efforts in this
direction are a great example.

Which leads us to ownership:
> I think part of the problem now is one of ownership. As we transition 
> to the new model -- a model in which more and more of the image we 
> know now gets separated into loadable packages -- I think it's going 
> to be extremely important to get people responsible for each package. 
> Once there's someone to point to, and an identifiable artifact, I 
> think it's easier to get documentation done.

I think ownership is critical for documentation, but it's even more
important for something else most of us are really complaining about,
thought we call it documentation - conceptual integrity. When things are
built piece meal, by a number of people, each with their own slant on
the ideas, names aren't consistent. The rules of the framework ARE
sidestepped. An owner is there to mediate such things - always
explaining why things are done in a certain way, adapting code to fit
before accepting it into his package, and so forth.

People, we need owners, soon (maybe stewards is a better name, since the
the code is actually free). I'd like to take a shot at a few
misconceptions there may be about stewardship, and maybe plant a few
ideas about how it should be -
* The steward is nobody's bitch. She's not someone you complain to,
she's someone you bring an offering of feedback or code, and look to for
wisdom. If you treat her any less nicely than you'd like to be treated
in her place, she might stop.
* Being a steward isn't about having one bright idea, it's about having
a stake in the thing. Submit patches for it. Answer questions (it's also
a good way of getting mastery over details you've overlooked). Learn why
it was written as it was, and document it. Never stop. Somewhere along
the way, you become it.
* Being a steward is usually neither solo, nor a group effort. There's
usually one person or tight group actively in charge of something.
Otherwise it's hard to make those in or out decisions. But single people
have limited perspective, and they eventually move on - that's why it's
important to cultivate the people that sit on the periphery of some
code. The people that mostly use, but occaisonally submit a patch. Even
if it isn't good enough to include in your package, help them maintain
it for themselves in parallel, and maybe include it when it is good
enough... you never know where your replacement will come from.

And even if the steward isn't someone that will automagically solve all
your problems, it's the only way that the package system will ever do
any of us any good - it'll allow more people to be involved in this
process, and share the results.

Daniel Vainsencher