[DOCS] Blast Off - The Squeak Documentation Project

goran.hultgren at bluefish.se goran.hultgren at bluefish.se
Mon Feb 10 09:00:25 UTC 2003


Hi all!

shane at shaneroberts.com wrote:
> Hi All,
> This is the official unofficial launch of the latest round of
> documentation effort.

Good work Shane. Go, go!

> I found a page on the swiki that has not been changed since 1999
> called:  "Documentation - tasks to do"
> 
> It is:
> http://minnow.cc.gatech.edu/squeak/808
> 
> Let's start using this as a central Swiki scratchpad for cooperation
> on the documentation project.

Oh yes. You make my all warm - someone who actually searches the Swiki
*before* creating
yet-another-exactly-the-same-page-as-we-already-have-ten-of. :-)

[SNIP]
> Since the "to do" swiki page is a scratchpad, feel free to make a
> mess of it, add all your suggestions and comments there, and we
> will sort them out as we go.

Ah, I wrote a little wishlist in a post. Perhaps one of you can pick out
the cherries of that post as you see fit?
 
> To reduce clutter on the swiki in general, I suggest we make every
> effort to edit and clean up existing pages, rather than make new
> ones.  I don't think deleting pages is good, broken links are a drag.

Yes! Yes! :-)

> The comment has been made that "external documentation is
> immediately obsolete".  This is only partly true.  The Smalltalk
> language is stable, so any discussions on the swiki of this sort, will
> not be obsolesced.  Otherwise I agree, most of the documentation
> should be within Squeak, and kept up to date (somehow).  The
> swiki is useful, but people may not find it easily, so the
> documentation needs to be in Squeak.

But (I assume) you will *begin* using the Swiki. As Hannes said - we can
always move stuff into something "image loadable" later.

> Following are seven main ideas that have been discussed on the
> list to improve documentation:

I had a few more - like the "cleanup week" and the "list of classes for
cleanup" (as described in my other post).
 
> *******
> Write SUnit tests - this verifies that what is documented, executes,
> as well as providing documentation.
> 
> More Code Comments - any questions?
> 
> A "Magic Book" - documentation within Squeak which uses its
> multi-media capabilities to illustrate the use and power of Squeak
> for both developers and naïve users.

I think the connection with unit tests to keep it "automatically
staleness detecting" is important. But you all know that of course. Unit
tests is our only mechanism to really "tie" documentation to the code
making sure it stays updated.

> Code Comment "Scooper" - a tool which sweeps all the code
> comments into a format which allows them to be scanned and
> cross referenced (hyperlinked)  easily (more easily than using the
> existing browsers).  The idea here being to provide a different
> cognitive "view" on the code, not to add yet another browser.  So it
> needs to be powerful enough to justify its existence.

Note that (if you haven't seen it) you can hyperlink inside code and
class comments. Seldom used but it works.

> Don't Bloat The Image - new documentation and tools should not
> add yet more bloat to the image.  Code comments are fine, they
> don't add bloat.  Other new tools and documentation need to be
> very small, or optional to the standard contents of the image.  For

Actually *everything* we do from now on (since OOPSLA in fact) *should*
be in packages. But using SqueakMap this doesn't mean it will be hard to
reach.

> naïve users we may want something like a "Take the Tour" button,
> which loads the magic book.  I realize there is already a "tour" so
> this could be added.

IMHO the Magic book should not be monolithical. It would be better if we
set up an architecture to maintain the TOC and the index with search
capability and make a nice UI for that. And then establish some standard
form to compose a "chapter" in this book - one obvious way of doing it
would be to use Projects.

So, again IMHO some ideas of how it could work:
- The book tool should be a package on SqueakMap easily accessible
through the open... menu (just like the package loader is today).
- The contents of the book should be loaded on demand from the net and
cached locally on disk. TOC, index and perhaps search index (using
Scott's long forgotten engine for this) can be loaded/downloaded when
started and each chapter loaded on demand when viewed, perhaps as
Projects somehow embedded in the book.

regards, Göran



More information about the Squeak-dev mailing list