[squeak-dev] Documentation Team

Ralph Boland rpboland at gmail.com
Tue Apr 20 19:32:40 UTC 2010

> 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.
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.

Of course, if the documentation team uses poor judgment they can
alienate developers.  If this happens the solution is to fix the
documentation team, not remove its authority.

For a package loadable into Squeak the documentation team would
have no such authority unless the developers of the package wish
do submit to the documentation team's authority and the documentation
team agrees to accept the responsibility.

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

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.

All hail the documentation team!


Ralph Boland

Volume * Density = Mass.
Volume / Density = Intelligence.
The latter equation explains the equal intelligence
of men and woman and the capabilities of some
well known operating systems.

More information about the Squeak-dev mailing list