On Tue, Apr 20, 2010 at 2:32 PM, Ralph Boland <rpboland at gmail.com> wrote:
>> I don't want to silo all documentation on a "documentation team" either. To
>> my mind the role of a docs team is to support the broader community in an
>> effort to improve documentation, not to write it all in a vacuum. Proposal
>> is coming.
>
> One of my major complaints about Squeak is the lack of documentation
> (some of which should be outside of the image).
> I propose that the documentation team be given some teeth.  For each
> release the code/documentation for any new features should be inspected
> by the  documentation team and if the feature is not up to snuff
> documentation wise according to the team then the feature cannot be
> added to the release.

A big "-1" on this.

This isn't "teeth" because someone could just write some minimal
verbiage that isn't helpful anyway.

This is a volunteer community.  As such we can't "make" people do
things.  A system "harvesting what we do have" is what is needed for
progress.  If you think more docs are needed, please write them and
Squeak will harvest it to the degree it can.

> The documentation team at that point may choose to correct the
> deficiencies themselves or tell the developers to correct the situation
> or the feature will be dropped.  No one has the authority to override
> the documentation team's decisions on this matter.

Let's wait until we have something worthy to write *about* before we
enslave the whole community to paper pushing while trying to get
there.

> I also suggest that for each release the documentation team
> set of goal of bringing some aspect of Squeak up to snuff
> documentation wise.

I suggest we employ SqueakMap as a means for in-image, live-running,
documentation included in the package being documented.  Maui and
MaSarPackage are all the tools necessary to do this.  I hope to find
time to demonstrate this!

> If there were a TestCase team it should be given similar authority.
>
> I sure many feel that giving this level of authority to the documentation
> team is excessive but to my mind the level of documentation available
> in Squeak demonstrates otherwise.

Well, there is tons of external documentation!  Update that wiki!

> All hail the documentation team!

Heh heh, ok I'm glad you're joking!