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