Hi all,
since Tim raised the subject, let's return to caesar
https://en.wikipedia.org/wiki/Literate_programming
Otherwise, what Subbu said makes a lot of sense for me.

Le lun. 23 mars 2020 à 07:14, K K Subbu <kksubbu.ml at gmail.com> a écrit :

> On 23/03/20 4:16 AM, tim Rowledge wrote:
> > Maybe you would include them in your list of 'guides' but I'd say
> > there is a third type, the system description; not a bare operation
> > by operation reference but a soldi description of the intent,
> > limitations, usage and ethos of the system.
>
> Thanks for making it explicit. Yes, I include them under guide. The
> Implementation part of BlueBook is an example.
>
> My email was already too long, so I didn't elaborate further.
> Essentially, a guide should help us understand the five aspects of a
> system - Principles, Concepts, Facts, Processes and Procedures.
> Researchers depend on the first two, programmers on middle three and
> field support on the last two.
>
> Principles deal with perpetual invariants in the system (e.g. everything
> is an object, class-metaclass). This part does not change from release
> to release. These invariants are what makes Squeak squeak ;-).
>
> Facts also deals with invariants but these are subject to change in the
> future releases through enhancement, deprecation or obsolescence. E.g.
> Character is now an immediate object.
>
> Concepts deals with new features introduced in a release (e.g. jit,
> object representation, new bytecodes). Being new, the burden to create
> new help nodes will fall on the authors. Others can step in to
> interconnect these nodes into the help graph before release.
>
> Processes deal with rules/rationale (why?), choice (tradeoffs) and time
> (how? workflows?). E.g. Passwords should not be stored in clear text
> (rule), why should ProtoObject be left alone (rationale). why can't we
> get all instances of a Character (tradeoffs), how to submit a fix
> (workflow). This is the most tedious part of writing help text. But if
> other four are taken are of, then many people can step in to ease the load.
>
> Procedures describe the precise steps (what to do) to be taken to
> complete an operation (e.g. how to run benchmarks) or to work around
> faults and exceptions. Squeak makes it easy to encode these into the
> system itself. But if the method name changes, the doc should also be
> changed to be in sync.
>
> Regards .. Subbu
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20200323/4fc5921e/attachment.html>