<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /></head><body style='font-size: 10pt; font-family: Verdana,Geneva,sans-serif'> 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: <blockquote type="cite" style="padding: 0 0.4em; border-left: #1010ff 2px solid; margin: 0"> <div>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:</div> <ul> <li style="margin: 0px; font-stretch: normal; line-height: normal; font-family: 'Helvetica Neue';">We need better package descriptions. This seems like fairly low-hanging fruit. Maybe tackle this first?</li> <li style="margin: 0px; font-stretch: normal; line-height: normal; font-family: 'Helvetica Neue';">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.</li> <li style="margin: 0px; font-stretch: normal; line-height: normal; font-family: 'Helvetica Neue';">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?</li> <li style="margin: 0px; font-stretch: normal; line-height: normal; font-family: 'Helvetica Neue';">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?...</li> <li style="margin: 0px; font-stretch: normal; line-height: normal; font-family: 'Helvetica Neue';">self docFlag: 'Unclear to me what ivar x is doing here. Cartesian or generic f(x)? --cbr'.</li> <li style="margin: 0px; font-stretch: normal; line-height: normal; font-family: 'Helvetica Neue';">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.</li> <li style="margin: 0px; font-stretch: normal; line-height: normal; font-family: 'Helvetica Neue';">Whatever I've missed and anything else folks can think of.</li> </ul> <div>—Casey</div>  <div class="pre" style="margin: 0; padding: 0; font-family: monospace"> </div> </blockquote> </body></html>