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

[Casey Ransberger]

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. 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. 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20190512/2acda792/attachment.html>