[DOCS] Re: Documentation [was: Morphic tutorial]
Richard A. O'Keefe
ok at cs.otago.ac.nz
Thu Feb 13 23:02:11 UTC 2003
Hannes Hirzel <hannes.hirzel.squeaklist at bluewin.ch> wrote:
See Ralph Johnson's thoughts on documentation
of June 1999 http://minnow.cc.gatech.edu/squeak/736
He says we need
"Big picture" and cookbook
Exactly what I was getting at when I mentioned Brent Welch's Tcl/Tk book.
It doesn't say "Here are the built in procedures", that is what the
(abundant and detailed but not quite proof-read enough) man pages that
come with Tcl/Tk are foo. It gives you concepts and a cookbook.
However, when he says "A wiki is a very good way to capture documentation"
he is wrong. As I noted yesterday, if the information is locked up in a
wiki, people who _need_ it can't always be sure of _getting_ it. Second,
there he was back in June 1999 saying "There seem to be a lot of questions
about Morphic, so that might be a good place to start", and here we are
in 2003 still saying the same thing.
That's precisely why I'm sick of hearing people say "let's start a page
on the Swiki to talk about documentation".
To the new documentation team, ALL HAIL! More power to you,
and much thanks. But also a word of advice: don't be too ambitious.
Make the documentation straight standards-conforming HTML (use Html Tidy
to check) that Scamper can understand. Start by trying to explain
fairly thoroughly the ideas behind one thing and how to use it.
(PluggableListMorph might be a good place to start, as a very useful
morph in its own right.) As you do this, you will find a host of
background things that need to be explained. Don't stop to explain
them, just note them as they come up. When you've finished that bit,
you'll have documentation on PluggableListMorph (or whatever you chose)
that will be useful to some people. But more importantly, you will have
a list of essential background knowledge that you can start work on.
If you keep on doing this, you will end up with a topic map, and that
map will itself be important documentation.
More information about the Squeak-dev