<div dir="ltr"><div>Hi all,</div><div>since Tim raised the subject, let's return to caesar <a href="https://en.wikipedia.org/wiki/Literate_programming">https://en.wikipedia.org/wiki/Literate_programming</a></div><div>Otherwise, what Subbu said makes a lot of sense for me.<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Le lun. 23 mars 2020 à 07:14, K K Subbu <<a href="mailto:kksubbu.ml@gmail.com">kksubbu.ml@gmail.com</a>> a écrit :<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 23/03/20 4:16 AM, tim Rowledge wrote:<br>
> Maybe you would include them in your list of 'guides' but I'd say<br>
> there is a third type, the system description; not a bare operation<br>
> by operation reference but a soldi description of the intent,<br>
> limitations, usage and ethos of the system.<br>
<br>
Thanks for making it explicit. Yes, I include them under guide. The <br>
Implementation part of BlueBook is an example.<br>
<br>
My email was already too long, so I didn't elaborate further. <br>
Essentially, a guide should help us understand the five aspects of a <br>
system - Principles, Concepts, Facts, Processes and Procedures. <br>
Researchers depend on the first two, programmers on middle three and <br>
field support on the last two.<br>
<br>
Principles deal with perpetual invariants in the system (e.g. everything <br>
is an object, class-metaclass). This part does not change from release <br>
to release. These invariants are what makes Squeak squeak ;-).<br>
<br>
Facts also deals with invariants but these are subject to change in the <br>
future releases through enhancement, deprecation or obsolescence. E.g. <br>
Character is now an immediate object.<br>
<br>
Concepts deals with new features introduced in a release (e.g. jit, <br>
object representation, new bytecodes). Being new, the burden to create <br>
new help nodes will fall on the authors. Others can step in to <br>
interconnect these nodes into the help graph before release.<br>
<br>
Processes deal with rules/rationale (why?), choice (tradeoffs) and time <br>
(how? workflows?). E.g. Passwords should not be stored in clear text <br>
(rule), why should ProtoObject be left alone (rationale). why can't we <br>
get all instances of a Character (tradeoffs), how to submit a fix <br>
(workflow). This is the most tedious part of writing help text. But if <br>
other four are taken are of, then many people can step in to ease the load.<br>
<br>
Procedures describe the precise steps (what to do) to be taken to <br>
complete an operation (e.g. how to run benchmarks) or to work around <br>
faults and exceptions. Squeak makes it easy to encode these into the <br>
system itself. But if the method name changes, the doc should also be <br>
changed to be in sync.<br>
<br>
Regards .. Subbu<br>
<br>
</blockquote></div>