<div dir="ltr"><div dir="ltr"><div dir="ltr"><br></div>Casey,<div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, May 8, 2019 at 1:15 AM Casey Ransberger via Cuis-dev <<a href="mailto:cuis-dev@lists.cuis.st">cuis-dev@lists.cuis.st</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">(Top post)<br>
<br>
Ken, Dan, people of Cuis,<br>
<br>
Sorry about the delay. I’ve flagged this thread for follow-up. If you want to pile on, please either reply directly to me or (preferably) reply to this thread. <br>
<br>
Dan: seems easy enough to doit in a workspace and find things w/o class comments. Haven’t got the incantation in my head, but should be easy. <br></blockquote><div><br></div><div>(Smalltalk allClasses collect: [:eaClass| {'class'->eaClass. 'commentSize'->eaClass organization classComment size} asDictionary]) select: [:ea| (ea at: 'commentSize') < 10].</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
I guess what I’m proposing here is that we keep a list of things that either need docs written, or updated. Funny thing about ST, we don’t spend a lot of time looking at stuff we aren’t using. So I need folks to point out missing or “bogus” docs for me to find the areas that need attention. We should make a list, and keep it versioned in git; I can cross things off it and do something productive. Of course, it’s a never-ending task, because ST is this permanently moving target. So I’m not offering a permanent solution (he’ll, *I* am not permanent,) I’m more interested in figuring out what the process should be, putting in what I can this time in one good sweep, and then hoping that others will follow suit. <br></blockquote><div><br></div><div>I'd keep it simple to start:</div><div>1) Package comments (more and better than most (any?) of us do currently)</div><div>2) Class comments... this has been a problem forever, and long before Cuis came along.</div><div>3) Methods (not all of them... just start with the 100-200 or so most-used methods and make sure at least the top level implementer has *something* telling people what it means and does.)</div><div><br></div><div>The nice thing about this (esp 1&2) is that we can start with the simple stuff: what's missing?  Add it. (easily done with queries like the one I did above)  Then move on to more intermediate stuff: what's inadequate (terse/incomplete descriptions etc)  Expand on it. (also easily done with queries)  Then move on to the harder stuff: what's unclear/hard to follow?  Rewrite it. etc. (a bit more work.  maybe just treat it as break/fix as people complain about it?)  Then start thinking about how to best integrate other doc sources (Terse guide etc)</div><div><br></div><div>Only then should we even think about *more* doc locations/formats, IMO.  The facilities we already have available are insufficiently used. Until we fix that, why add more places for people to avoid putting docs in?  Also, if we do a better job in-image, it will make it more obvious where the gaps are so we have better requirements for anything else we need to add/build.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Ken:<br>
<br>
So, if we used PetitParser or Ometa, it seems like we’re making a potential new user install a parser-generator just to make sense of documentation. That seems a lot to ask, from my point of view, but it seems like the heart ❤️ of your idea is solid and resolute.<br>
<br>
My question to you is this: can you find a way to accomplish the same thing using only the built-in syntax that we get for free? Why not just represent everything with a small, clever DSL that uses existing Smalltalk syntax?<br>
<br></blockquote><div><br>Yes, see below.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I do like your proposal, in that we should expect at minimum these particular “fields” to be filled with documentation, and your DSL seems to present a very reasonable set of expectations. That seems like a pretty basic request that ought to be addressed in every circumstance. I disagree that we need a parser-generator to do it. Cuis should be a minimal system, with a tiny but complete documentation system that’s trivial to install if you need/want docs. <br>
<br>
;)<br>
<br>
The matter of stuff that necessarily lives outside of the image is philosophically burdensome to me. If anything, I say let’s make a class called DocMaker and what that does is externalizations of information that’s available from within Cuis, if you’ve installed documentation. <br>
<br></blockquote><div><br></div><div>I agree with everything you say (i.e. no new dependencies on parsers, keep it in-image etc.)  One place that would be a natural for any missing metadata/docs at the package level: in the package file itself.  Similar to how it currently stores the description and requirements, we could just as easily add a key/value metadata field (i.e. an infinitely flexible schema so we don't have to keep changing the file format/parser or worry about it blowing up when people try to install the wrong package file version in the wrong version of Cuis.  Keep the existing description field a reasonably short very high-level summary, put more expansive docs in other fields).  Then you can generate Readme files etc. from that.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Okay, now, everybody shoot holes in the above any way you can, let’s stress test what I’ve written hypothetically, learn what we can from the experience, and then I’ll start doing stuff. <br>
<br>
—C [EOM]<br><br>
</blockquote></div></div></div></div>