[Cuis-dev] README.md Documentation

[Dan Norton]

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