[Squeak-doc] Roadmap proposal for the Squeak Documentation Team
in 2007
Lex Spoon
lex at lexspoon.org
Sat Apr 7 13:59:25 UTC 2007
tim Rowledge <tim at rowledge.org> writes:
> This problem of 'where to start' is why I pointed out the cross-
> linking capability.
>
> For each class involved in a package or subsystem, simply add a link
> back to the 'main' class. Put the major documentation there. For
> methods involved in a package that doesn't really involve most of the
> class, put the link in the method comment. Classes involved in many
> packages would need somewhat longer and more developed comments than
> we are used to. URL links would allow pointing out to more
> sophisticated doc on the web somewhere, in a form that is perhaps
> more easily updated
In addition to these explicit links, you can keep in mind common
places that programmers will look. Things to consider:
1. Think about what looks like he main classes of the package to begin
with. If there is a Seaside class, then people wanting to read
about Seaside are going to go there. In Morphic, everybody is
going to look at class Marph, so make sure it has a good comment.
2. You can create classes just for documentation. There is nothing at
all wrong with making a class like SMAAAReadme as starting point in
some category.
3. Likewise for categories. You can perfectly well make a
Morphic-Tutorials category if you like.
3. The same things apply to methods, as to classes. It works well to
put "examples" methods on the class side of important methods.
Just a few thoughts. In general, there is a world of possibility with
the existing documentation tools.
Lex
More information about the Squeak-dev
mailing list
|