Documentation Team

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

Regards,

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.

Em 20-04-2010 16:32, Ralph Boland escreveu:

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.

  

If I could suggest something it would be:

1. Split repositories:
1. 4.1 (the distro)
2. 4.1-updates (bug fixes mainly)
3. 4.1-upgrades (new versions of - stable - packages)
4. 4.1-extras (things that doesn't belong to the distro but may run with it...
5. 4.1-rawhide (alpha/beta stuff)
2. To be in 4.1, 4.1-updates, 4.1-upgrades, 4.1-extras packages should conform with some documentation standards, stability issues, modularity, compatibility, etc.
3. The community should discuss documentation standards of (2) under mediation of SOB.
4. Documentation team should be responsible to oversee that documentation is OK otherwise packages would be put under 4.1-rawhide.
5. Instead of having a single "repository URL" users should be able to define a "repository path" defining where they want to update from (only 4.1, 4.1-updates also, etc).
   

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!

Regards,

Ralph Boland




  

Regards,

Casimiro Barreto

On Tue, Apr 20, 2010 at 2:32 PM, Ralph Boland <[hidden email]> wrote:
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!