On Thu, Apr 05, 2007 at 01:22:04AM -0700, Matthew Fulmer wrote:
> >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

Max OrHai reminded me that we already have an excellent medium
for storing Squeak documentation, better than Sophie, Pier, or
anything else:

COMMENTS!!!

This is much more concrete and practical than whatever I was
thinking about creating, so I replaced this point with a point
about comments and how they could be integrated into Pier.

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

I edited this to be more explicit about Magic Book and how the
point is document verification

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

This has been updated. Get the newer, saner version there.

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

Screw that. Comments already satisfy requests 1, 4, 5, and 6,
and, if combined with Pier, probably satisfy request 3 easily.
Request 2 is Magic Book, and has been moved to the end of the
roadmap task list.

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

Thank you Max for reminding me about comments.

(I am such an idiot for forgetting about comments)

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