>From discussions I have had on IRC with Derek O'Connell, Max
OrHai, and Paul Bennett, I have decided it is time to propose an
official road map for the Squeak Documentation Team for 2007:

We are currently in the formative stages, and a clear goal is
starting to emerge, along with a path to get there. We would
like to see a Squeak where:
- Tutorials exist in the main image
- All core functionality is documented and up-to-date
- The documentation can be viewed and edited both within the
  image and from a central website
- The documentation can be easily maintained indefinitely

How can we get there? There are several steps we must take, and
they can be done mostly in parallel:
- Collect all existing documentation together in one place.
-- This is nearly complete. We have assembled a list of nearly
   all Squeak documentation that exists outside of the image:
-- Squeak Tutorials (Links)[1]
-- Category Index[2]
- Categorize and index all of this documentation. 
-- We are undertaking this task in the small at Squeak
   Tutorials[3], where we are concerned only with categorizing
   and indexing Squeak Tutorials. From there, we will probably
   use this hierarchy as a basis for our new index. We stand to
   gain two things from completing this project:
--- A strong core Documentation team, willing and capable of
    facing the larger challenges ahead
--- A first-pass at a usable introductory guide to Squeak
-- The next step will be to fix the problems listed at
   Refactoring the Swiki[4], and complete the Documentation
   Table of Contents[5].
- Implement Magic Book[6], which will allow the Documentation to
  be kept up-to-date indefinitely. This will draw from the work
  done by the implementors of Sophie, Pier, SUnit, and perhaps
  Gjallar
- Get permission and republish the documentation in a form
  suitable for distribution and collaboration
-- Paul Bennett has volunteered for this task.
- Integrate SUnit tests into the documentation. Thanks to the
  3.10 release team, there should be plenty of
  unit tests by the time we get to this stage.

A hyperlinked version of this proposal is on the Doc team home
page:
http://wiki.squeak.org/squeak/808

With a clear plan and a clear goal, we can eliminate the
criticism that Squeak needs better documentation. There are
tasks to be done. If this road map seems good to the community,
we can start systematically dividing up the tasks and assigning
responsibilities. I will divide up the tasks into week-long
chunks, so that one can contribute by sacrificing 2 to 10 hours
per week. 

I especially need help from the developers of Sophie, Pier,
SUnit, Monticello, and Spoon to evaluate how difficult it will
be to:
- Create a system for browsing Documentation along side the code
- Embed unit tests within documentation so that it can be
  auto-tested for correctness
- Edit from both the image and the web
- Distribute this documentation with the image
- Distribute such documentation as part of a packages
- Edit the documentation locally and commit it to a central
  (official) image/universe and make it available via the update
  mechanism (somewhat like a distributed wiki)

I know it is late, but tasks 1-4 would make a great Google
Summer of Code project.

Thank you for reading this proposal, and thanks to all who
reminded me how important good documentation really is. You know
who you are :)

[1] Squeak Tutorials (Links):
    http://wiki.squeak.org/squeak/792#Links

[2] Category Index:
    http://wiki.squeak.org/squeak/5871

[3] Squeak Tutorials:
    http://wiki.squeak.org/squeak/792

[4] Refactoring the Swiki:
    http://wiki.squeak.org/squeak/2352

[5] Documentation Table of Contents:
    http://wiki.squeak.org/squeak/2983

[6] Magic Book:
    http://wiki.squeak.org/squeak/3004

-- 
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808