[Cuis-dev] README.md Documentation

[ken.dickey at whidbey.com]

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