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