[Cuis-dev] Summary of documentation concerns/needs/wants

[Dan Norton]

Hi Casey,

On Sun, 12 May 2019 03:23:38 -0700
Casey Ransberger via Cuis-dev <cuis-dev at lists.cuis.st> wrote:

> This is my quick summary of the recent discussion about
> documentation. Hopefully I’ve captured a solid overview of the
> concerns that were discussed, but if I’m leaving out an important
> point, please let me know, and I’ll add it. What I’m generally
> hearing: We need better package descriptions. This seems like fairly
> low-hanging fruit. Maybe tackle this first? Ken Dicky has proposed a
> structure for package documentation. Seems reasonable to me at first
> glance. It might make sense to put the docs in the package file. My
> brain grinds on this though, because the docs for some UNIX packages
> are just enormous and I often don’t download or install them unless I
> need to refer to them. My gut says that extended docs, outside of
> plain old comments, should be optional in every way possible. Of
> course there’s the counter-argument that keeping the docs unitary
> with the code is better for learning. I’m interested in what people’s
> opinions are on this detail. Class comments need love. Seems a bigger
> project than package descriptions. I say, punt until we’re happy at
> the package level. When we know what our packages do, then we can
> worry about what our classes do.

I'd just like to point out that there are classes that need comments in
the base. These are not in packages. The Class Comment Browser finds
143 of them currently.

Elsewhere, nearly all packages that I originated have no package
comments. I'll fix that.

> Seem logical? Phil B brought up
> method comments. This ends up being a lot of work, and is probably
> best tackled by dividing the task among area experts. We should
> probably come to some reasonable agreement as a group about what
> methods need comments (for example, I’d rather a garden variety
> accessor didn’t have a comment, but others might disagree,) and what
> should be included in a method comment. But that’s just fixing them!
> Finding method comments that need love is a whole other problem.
> Should we add something like?… self docFlag: ‘Unclear to me what ivar
> x is doing here. Cartesian or generic f(x)? --cbr’. What level of
> system integration do we want with docs? Personally I’d think I was
> in heaven if I could both peruse and edit extended documentation from
> within the image. 

It's far from heaven, but the Class Comment Browser helps you find
classes and then open a browser where you can make changes, including
class comments.

> Bringing this up not because we should do anything
> right away, but because we might want to later I guess? Seems nice to
> have. Whatever I’ve missed and anything else folks can think of.
> —Casey

 - Dan