[Cuis-dev] README.md Documentation

[Phil B]

One thing I forgot to mention regarding the package file: if we did extend
its schema, put the doc/meta fields at the end of the file so that if we
ever get really crazy and start embedding markup / images / whatever (i.e.
we could base64 encode binary content etc) and it starts adding significant
size to the file, we could implement a 'quick load' feature.  That way we
could just stop reading the file once it starts seeing the meta fields (and
put the package into a read-only mode when loaded that way so that people
don't start accidentally submit pull reqs for modified versions of the
truncated packages)

On Wed, May 8, 2019 at 2:13 AM Phil B <pbpublist at gmail.com> wrote:

>
> 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/b981504a/attachment.html>