[Cuis-dev] README.md Documentation

[Phil B]

Casey,

On Wed, May 8, 2019 at 1:15 AM Casey Ransberger via Cuis-dev <
cuis-dev at lists.cuis.st> wrote:

> (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.
>

(Smalltalk allClasses collect: [:eaClass| {'class'->eaClass.
'commentSize'->eaClass organization classComment size} asDictionary])
select: [:ea| (ea at: 'commentSize') < 10].


>
> 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.
>

I'd keep it simple to start:
1) Package comments (more and better than most (any?) of us do currently)
2) Class comments... this has been a problem forever, and long before Cuis
came along.
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.)

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)

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.


> 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?
>
>
Yes, see below.


> 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.
>
>
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.


> 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]
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20190508/7f8d3f4a/attachment-0001.html>