----boundary-LibPST-iamunique-1880675250_-_-
Content-type: text/plain
H. v. L. wrote:
>
>> A good tutorial will help, so let's try to put one together.
>
>
>> I have spent some time today looking around for the documentation ...
>
>
> So, what is wanted, a Documentation or a Tutorial? And then, at what level?
>
> To me the Documentation of the BB Library seems fairly good (anything
> might of course be improved).
>
> As for a Tutorial or similar stuff there are the books by Stan Warford
> and Karlheinz Hug and there is a Tutorial (in german) I wrote (and
> still am writing). But I suppose all this is too basic as it more or
> less aims at beginners. Therefore I should like to know some details of
> what you have in mind.
>
> Harro
The question that must be asked is "Who is the audience?". For whom are
you writing?
I believe Oberon Microsystems Inc assumed the reader was (is) a
sophisticated computer programmer interested in component programming
with an emphasis on computer science.
It seems to me that quite a few of the BB users are actually engineers
and physicists who need to get a specific job accomplished.
I also get a sense that long pages of tutorial documentation would not
be greatly beneficial to most of us (to some, yes).
Proposal:
Write short topics composed of "why", "what", and "how" with a table
of contents listing the topics.
Nobody seems to include the "why" in their documentation. By this I
mean the *motivation* for including a function or module. What is the
problem the item is trying to solve?
The "what" simply states where the thing is, its name, and its parts.
The "how" gives a brief example of the calling sequence and the
preconditions that must be satisfied.
The "why", "what", and "how" should be kept together as a unit.
Any other thoughts on this?
-Doug
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy
----boundary-LibPST-iamunique-1880675250_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEguIHYuIEwuIHdyb3RlOlxwYXINCj4gXHBhcg0K
Pj4gIEEgZ29vZCB0dXRvcmlhbCB3aWxsIGhlbHAsIHNvIGxldCdzIHRyeSB0byBwdXQgb25lIHRv
Z2V0aGVyLlxwYXINCj4gXHBhcg0KPiBccGFyDQo+PiAgSSBoYXZlIHNwZW50IHNvbWUgdGltZSB0
b2RheSBsb29raW5nIGFyb3VuZCBmb3IgdGhlIGRvY3VtZW50YXRpb24gLi4uXHBhcg0KPiBccGFy
DQo+IFxwYXINCj4gU28sIHdoYXQgaXMgd2FudGVkLCBhIERvY3VtZW50YXRpb24gb3IgYSBUdXRv
cmlhbD8gQW5kIHRoZW4sIGF0IHdoYXQgbGV2ZWw/XHBhcg0KPiBccGFyDQo+IFRvIG1lIHRoZSBE
b2N1bWVudGF0aW9uIG9mIHRoZSBCQiBMaWJyYXJ5IHNlZW1zIGZhaXJseSBnb29kIChhbnl0aGlu
ZyAgXHBhcg0KPiBtaWdodCBvZiBjb3Vyc2UgYmUgaW1wcm92ZWQpLlxwYXINCj4gXHBhcg0KPiBB
cyBmb3IgYSBUdXRvcmlhbCBvciBzaW1pbGFyIHN0dWZmIHRoZXJlIGFyZSB0aGUgYm9va3MgYnkg
U3RhbiBXYXJmb3JkIFxwYXINCj4gYW5kICBLYXJsaGVpbnogSHVnIGFuZCB0aGVyZSBpcyBhIFR1
dG9yaWFsIChpbiBnZXJtYW4pIEkgd3JvdGUgKGFuZCBccGFyDQo+IHN0aWxsIGFtICB3cml0aW5n
KS4gQnV0IEkgc3VwcG9zZSBhbGwgdGhpcyBpcyB0b28gYmFzaWMgYXMgaXQgbW9yZSBvciBccGFy
DQo+IGxlc3MgYWltcyBhdCAgYmVnaW5uZXJzLiBUaGVyZWZvcmUgSSBzaG91bGQgbGlrZSB0byBr
bm93IHNvbWUgZGV0YWlscyBvZiBccGFyDQo+IHdoYXQgeW91IGhhdmUgIGluIG1pbmQuXHBhcg0K
PiBccGFyDQo+IEhhcnJvXHBhcg0KXHBhcg0KVGhlIHF1ZXN0aW9uIHRoYXQgbXVzdCBiZSBhc2tl
ZCBpcyAiV2hvIGlzIHRoZSBhdWRpZW5jZT8iLiAgRm9yIHdob20gYXJlIFxwYXINCnlvdSB3cml0
aW5nP1xwYXINClxwYXINCkkgYmVsaWV2ZSBPYmVyb24gTWljcm9zeXN0ZW1zIEluYyBhc3N1bWVk
IHRoZSByZWFkZXIgd2FzIChpcykgYSBccGFyDQpzb3BoaXN0aWNhdGVkIGNvbXB1dGVyIHByb2dy
YW1tZXIgaW50ZXJlc3RlZCBpbiBjb21wb25lbnQgcHJvZ3JhbW1pbmcgXHBhcg0Kd2l0aCBhbiBl
bXBoYXNpcyBvbiBjb21wdXRlciBzY2llbmNlLlxwYXINClxwYXINCkl0IHNlZW1zIHRvIG1lIHRo
YXQgcXVpdGUgYSBmZXcgb2YgdGhlIEJCIHVzZXJzIGFyZSBhY3R1YWxseSBlbmdpbmVlcnMgXHBh
cg0KYW5kIHBoeXNpY2lzdHMgd2hvIG5lZWQgdG8gZ2V0IGEgc3BlY2lmaWMgam9iIGFjY29tcGxp
c2hlZC5ccGFyDQpccGFyDQpJIGFsc28gZ2V0IGEgc2Vuc2UgdGhhdCBsb25nIHBhZ2VzIG9mIHR1
dG9yaWFsIGRvY3VtZW50YXRpb24gd291bGQgbm90IFxwYXINCmJlIGdyZWF0bHkgYmVuZWZpY2lh
bCB0byBtb3N0IG9mIHVzICh0byBzb21lLCB5ZXMpLlxwYXINClxwYXINClByb3Bvc2FsOlxwYXIN
CiAgIFdyaXRlIHNob3J0IHRvcGljcyBjb21wb3NlZCBvZiAid2h5IiwgIndoYXQiLCBhbmQgImhv
dyIgd2l0aCBhIHRhYmxlIFxwYXINCm9mIGNvbnRlbnRzIGxpc3RpbmcgdGhlIHRvcGljcy5ccGFy
DQpccGFyDQpOb2JvZHkgc2VlbXMgdG8gaW5jbHVkZSB0aGUgIndoeSIgaW4gdGhlaXIgZG9jdW1l
bnRhdGlvbi4gIEJ5IHRoaXMgSSBccGFyDQptZWFuIHRoZSAqbW90aXZhdGlvbiogZm9yIGluY2x1
ZGluZyBhIGZ1bmN0aW9uIG9yIG1vZHVsZS4gIFdoYXQgaXMgdGhlIFxwYXINCnByb2JsZW0gdGhl
IGl0ZW0gaXMgdHJ5aW5nIHRvIHNvbHZlP1xwYXINClxwYXINClRoZSAid2hhdCIgc2ltcGx5IHN0
YXRlcyB3aGVyZSB0aGUgdGhpbmcgaXMsIGl0cyBuYW1lLCBhbmQgaXRzIHBhcnRzLlxwYXINClxw
YXINClRoZSAiaG93IiBnaXZlcyBhIGJyaWVmIGV4YW1wbGUgb2YgdGhlIGNhbGxpbmcgc2VxdWVu
Y2UgYW5kIHRoZSBccGFyDQpwcmVjb25kaXRpb25zIHRoYXQgbXVzdCBiZSBzYXRpc2ZpZWQuXHBh
cg0KXHBhcg0KVGhlICJ3aHkiLCAid2hhdCIsIGFuZCAiaG93IiBzaG91bGQgYmUga2VwdCB0b2dl
dGhlciBhcyBhIHVuaXQuXHBhcg0KXHBhcg0KQW55IG90aGVyIHRob3VnaHRzIG9uIHRoaXM/XHBh
cg0KXHBhcg0KLURvdWdccGFyDQpccGFyDQotLS0gQmxhY2tCb3hccGFyDQotLS0gc2VuZCBzdWJq
ZWN0IEhFTFAgb3IgVU5TVUJTQ1JJQkUgdG8gYmxhY2tib3hAb2Jlcm9uLmNofX0AZWluQFZlcndh
bA==
----boundary-LibPST-iamunique-1880675250_-_---
Received on Tue Feb 22 2005 - 20:56:40 UTC