[Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

Matthew Fulmer tapplek at gmail.com
Fri Apr 6 19:23:01 UTC 2007


On Fri, Apr 06, 2007 at 10:21:06AM -0600, Brian Brown wrote:
> I agree with Tim and Matt that using comments would be great way to  
> go, with one caveat :)
> 
> The biggest frustration with using comments is that there is no good  
> "starting place" for a given class category. For example, go browse  
> the Seaside classes and categories and figure out where one should  
> start. You can repeat this exercise for any number of categories. I  
> propose that we we add a documentation attribute to the PackageInfo  
> stuff, so there is a category level documentation spot, with links to  
> the appropriate class comments.
> 
> Any thoughts?

SqueakMap and Universes both have comment mechanisms, and are
probably the best place to start. Adding a comment mechanism to
PackageInfo would be an excellent solution in both the short
term and long term. PackageInfo is probably here to stay for a
while, and, even if it is not, the feature would have to be
supported in any future packaging system (spoon, classboxes,
etc).

Distributing other documents, such as tutorials, is not so
feasible right now, as only code is distributable at the moment.
Spoon is probably the only long-term solution to this issue.

However, this is not the immediate concern. The bigger issue is
to have a working document available *at all*. We have to create
the documentation before we can relevantly worry about where to
store it. Once we have a document that the community is willing
to adopt as "The Official Squeak Documentation", then we can
worry about distributing it and making it more accessible from
within and without the image.

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



More information about the Squeak-dev mailing list