[Cuis-dev] README.md Documentation

[Casey Ransberger]

(Top post)

Ken, Dan, people of Cuis,

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. 

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. 

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. 

Ken:

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.

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?

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. 

;)

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. 

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. 

—C [EOM]

> On May 7, 2019, at 7:09 AM, Dan Norton via Cuis-dev <cuis-dev at lists.cuis.st> wrote:
> 
> A lot of classes need class comments. The implicit notion that no
> class comment or explanation is needed is bogus :)
> 
> - Dan
> 
> On Mon, 06 May 2019 15:24:22 -0700
> "ken.dickey--- via Cuis-dev" <cuis-dev at lists.cuis.st> wrote:
> 
>> On 2019-05-05 20:56, Casey Ransberger via Cuis-dev wrote:
>> ..
>> If someone made a list of things that need better or updated 
>> documentation, I can dig in, investigate, talk to people etc and
>> write some updated words. I'd have the advantage of "fresh eyes" in
>> the sense that things have changed a lot since I was last in the loop.
>> 
>> It'll help me catch up on the state of things in the system while I'm
>> at it. Seems win/win, so I'm game to give it a shot. Doesn't need to
>> be limited to repo README stuff either. What's in the image seems
>> fair game too.
>> 
>> --Casey
>> 
>> Hi Casey,
>> 
>> I guess you get my 2 cents, since I raised the issue.
>> 
>> I see three things to relate: the README.md file, the Package Comment 
>> (perhaps expanded) and the Package itself (da code).
>> 
>> One of the things I am interested in is to make things
>> comprehensible. How do I make things simple enough that even I
>> understand?
>> 
>> Part of this in matching interest and learn-ability.
>> 
>> If you take a look at the "package reference" I started,
>> 
>> 
>> https://github.com/Cuis-Smalltalk/Learning-Cuis/blob/master/PackageRef.md
>> 
>> you will see
>>   URL of source package
>>   SYNOPSIS
>>     brief description <one line>
>>     provides
>>     requires
>>   Of Interest <illustrative code techniques/usage>
>> 
>> This last allows me to ask: "I want to do X, what something does
>> that?" so I can read and learn from code.
>> 
>> Since a package does not have to be in the base image, this "what
>> does that?" can be more interesting than can be covered by the Terse
>> Guide.
>> 
>> My thought is that if we structured the README.md's a bit, a Package 
>> Guide could be just the (?alpha-sorted?) README.md's of all the 
>> packages.  That way we do not separate the Package Guide from the 
>> Package(s).  Perhaps we could write a simple browser which presents 
>> things well, perhaps using PetitParser.
>> 
>> For viewing packages in brief, I would hope to see something we could 
>> glean from a CodePackage object.
>>   Package Name
>>   Package Comment [terse description]
>>   provides [e.g. what to "Feature require:"]
>>   requires
>> 
>> I would like to see in a Package README.md
>> 
>>   PACKAGE NAME
>>   SYNOPSIS
>>     brief description <one line>
>>     provides
>>     requires
>>   [Usage Detail OR Class code to look at -- if interesting]
>>   [Screen shot -- if interesting]
>>   [Of Interest <illustrative code techniques/usage>]
>> ??? What would you like to see here ???
>> 
>> One thing which I try to update from time to time, but frequently
>> gets behind, is the Cuis ver.rev where the Package was last tested
>> and known to work.  Even dated, this gives info on what breakage
>> might be expected (e.g. last worked on Cuis 4.0 vXXXX might have more
>> breakage than, say, Cuis 5.0 v3720).
>> 
>> So that balance is [A] What is useful to someone learning the system?
>> vs [B] What is lean/quick/easy enough that I will create and maintain
>> it?
>> 
>> What is everyone's take on this?  What is useful?  What am I missing?
>> 
>> Given the modest README.md markup, is there someone out there with
>> the time to create a "parse and present" package browser?
>> 
>> Can we agree on a README.md template for Packages?
>> 
>> -KenD
> 
> -- 
> Cuis-dev mailing list
> Cuis-dev at lists.cuis.st
> https://lists.cuis.st/mailman/listinfo/cuis-dev