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

[ken.dickey at whidbey.com]

Casey, 

Good summary about What. 

Change of view.  Let me throw out some random thoughts about Why. 

Usability. 

Good interfaces are about [A] What is here? and [B] What can I do with
it? 

We are continuously working on keeping a clean and small core to help us
understand and learn Cuis, but we frequently want something that may be
in a package (e.g. graphic or editing tools, network/Web-dev, .. or
code/use patterns).  How do we find them? 

We want to help share Cuis with both Smalltalk newbies and experts. 
What concept maps/guides can we build into our code which satisfy the
same goals as with Cuis in general: what practices are low-fat and carry
their own weight?   What helps explain and learn?  What is light enough
that we don't mind doing it? 

What tools do we need to build to help us be successful? 

My journey.  What is going on here?  How do they do that? 

I tend to build things to see how they work. 

Color -> Color Editor 

Layouts -> LayoutMorphEditPanel, LayoutSpecEditPanel 

Morphs -> Morphic-Misc1, Morph-MetaProperties 

Unicode -> UniCodes 

Timers -> Animator 

... 

I would like to know more about Cuis: 

- UI Events (crtical, underdocumented; can we abstract behaviors?) 

- Compiling and VM building/baselining/bootstrap; FFI; multi-core 

- Buncha stuff 

I feel that I am not just learning for me, but want to leave
tracks/comments/code which help others
learn/understand/replace-with-something-better.  What helps the Cuis
community? 

So for me, the checkpoint is not "comment for each <whatever>" but "how
can I make useful comments which are not just noise, but help people
learn/understand?".  Also, what is clear and terse?  What helps make
Cuis comprehensible? 

Sorry, I feel like I am starting a lecture here.  Not my intent. 

I guess what I am trying to say is that, for me, it would be more
interesting to start with something like "explaining how to put windows
and controls together", then drill down to bits like Layouts, Menus,
MenuItems, Mouse events, Text, .. and make sure "those comments there"
comments make sense to someone learning/explaining the code patterns. 

$0.02, 

-KenD 

On 2019-05-12 03:23, Casey Ransberger via Cuis-dev 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. 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/adcab0bd/attachment-0001.html>