----boundary-LibPST-iamunique-296293369_-_-
Content-type: text/plain
Hi,
>There must be some way that the Blackbox user community can help Ominc
>improve its documentation.
The best computer documentation is presented in 2 dimensions: as a
task-oriented manual for everyday use, and as a subject-oriented manual for
occasional reference. In my opinion the main failing of the BB documentation
is that it really only works as reference material - one dimension is
missing.
Martin Reiser's book 'The Oberon System' is a good example which uses both
dimensions. It is organised into 3 parts: User's guide, Reference and
Programming guide.
The User's Guide begins with a quick naming of parts: how to use the mouse,
what the visible parts of the system are, and so on. It continues by showing
you how to do things: use the editor, compiler , diskettes and network. So
this part is task-oriented, and geared around asking 'How do I ...?'
questions.
When you need more detail about the specific subjects described in the
how-to part, you have it all collected there in the reference part,
organised by subject.
The Programming guide then addresses itself to a specialist audience which
is a subset of the audience for the User's guide. But it uses a similar
structure to before: it shows the programmer how to use texts, access
parameters, work with files etc.
If we imagine a subject-oriented reference as a series of columns where each
column represents a complete single subject, then we can imagine a user's
guide as a set of rows where each row represents a function or task, which
uses one or more of the subjects for its completion. By learning how to
complete tasks we are introduced to the reference subjects through need and
use. Very few people can learn to use a tool by sitting down and reading a
dry reference manual. But when we've been shown the various parts in use,
and know they exist, we can later look more deeply at the component parts
and find novel ways to use them.
For instance, I may read the BB documentation about Domains until I know it
by heart, forwards and backwards, but that doesn't necessarily mean I know
what Domains are, or why they exist and what they're for. In fact, I have no
reason at all to read the Domains documentation. I don't know what a BB
Domain is, so I can't think of any use for one.
On the other hand, if I'm scratching my head asking myself 'How do I ...?' I
should be able to find some document that helps me answer that question.
This document may well talk about Domains as part of the solution to my
problem, give me enough information about Domains to solve the problem, and
refer me to the complete Domains documentation for when I need to dig below
the surface. I now have an interest in Domains, so I'm motivated to learn
about them and can make some productive use of the reference material and
perhaps do something new and imaginative that I wouldn't have been able to
do until I knew about domains.
A carpenter approaches his workbench to make a chair or table for a
customer, not to use his hammer and saw. Carpenters are taught to use
hammers and saws by making wooden things; they learn to use the tools only
when they can see the need.
Similarly, programmers don't sit down at their PC to use the Domains module
(if there is such a thing). They sit down at it to write software which will
be useful in the world.
I hope this is a useful contribution to this discussion about BB
documentation. Perhaps the next step is to start a 'How do I ...?' FAQ.
Regards,
Bob Walkden
_________________________________________________________________
Hotmail messages direct to your mobile phone
http://www.msn.co.uk/msnmobile
--------------------------------------------
To unsubscribe from this mailing list, send a message containing the word "unsubscribe" to:
blackbox-request{([at]})nowhere.xy
To get a list of valid e-mail commands and instructions on their usage, send a message containing the word "help" to the above address.
Send any problem reports or questions related to this email list to the list owner at
owner-blackbox{([at]})nowhere.xy
Current posting policy:
a) To post you should use the same address by which you are subscribed to the mailing list. That way, the list server will recognize you as subscriber and forward your posting immediately, without creating any overhead.
b) If, for some reason, you cannot post from the address, by which you are subscribed, your message will be moderated to avoid spam. Please understand that moderation will often cause some delay, in particular over weekends or holydays.
----boundary-LibPST-iamunique-296293369_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEhpLFxwYXINClxwYXINCj5UaGVyZSBtdXN0IGJl
IHNvbWUgd2F5IHRoYXQgdGhlIEJsYWNrYm94IHVzZXIgY29tbXVuaXR5IGNhbiBoZWxwIE9taW5j
IFxwYXINCj5pbXByb3ZlIGl0cyBkb2N1bWVudGF0aW9uLlxwYXINClxwYXINClRoZSBiZXN0IGNv
bXB1dGVyIGRvY3VtZW50YXRpb24gaXMgcHJlc2VudGVkIGluIDIgZGltZW5zaW9uczogYXMgYSBc
cGFyDQp0YXNrLW9yaWVudGVkIG1hbnVhbCBmb3IgZXZlcnlkYXkgdXNlLCBhbmQgYXMgYSBzdWJq
ZWN0LW9yaWVudGVkIG1hbnVhbCBmb3IgXHBhcg0Kb2NjYXNpb25hbCByZWZlcmVuY2UuIEluIG15
IG9waW5pb24gdGhlIG1haW4gZmFpbGluZyBvZiB0aGUgQkIgZG9jdW1lbnRhdGlvbiBccGFyDQpp
cyB0aGF0IGl0IHJlYWxseSBvbmx5IHdvcmtzIGFzIHJlZmVyZW5jZSBtYXRlcmlhbCAtIG9uZSBk
aW1lbnNpb24gaXMgXHBhcg0KbWlzc2luZy5ccGFyDQpccGFyDQpNYXJ0aW4gUmVpc2VyJ3MgYm9v
ayAnVGhlIE9iZXJvbiBTeXN0ZW0nIGlzIGEgZ29vZCBleGFtcGxlIHdoaWNoIHVzZXMgYm90aCBc
cGFyDQpkaW1lbnNpb25zLiBJdCBpcyBvcmdhbmlzZWQgaW50byAzIHBhcnRzOiBVc2VyJ3MgZ3Vp
ZGUsIFJlZmVyZW5jZSBhbmQgXHBhcg0KUHJvZ3JhbW1pbmcgZ3VpZGUuXHBhcg0KXHBhcg0KVGhl
IFVzZXIncyBHdWlkZSBiZWdpbnMgd2l0aCBhIHF1aWNrIG5hbWluZyBvZiBwYXJ0czogaG93IHRv
IHVzZSB0aGUgbW91c2UsIFxwYXINCndoYXQgdGhlIHZpc2libGUgcGFydHMgb2YgdGhlIHN5c3Rl
bSBhcmUsIGFuZCBzbyBvbi4gSXQgY29udGludWVzIGJ5IHNob3dpbmcgXHBhcg0KeW91IGhvdyB0
byBkbyB0aGluZ3M6IHVzZSB0aGUgZWRpdG9yLCBjb21waWxlciAsIGRpc2tldHRlcyBhbmQgbmV0
d29yay4gU28gXHBhcg0KdGhpcyBwYXJ0IGlzIHRhc2stb3JpZW50ZWQsIGFuZCBnZWFyZWQgYXJv
dW5kIGFza2luZyAnSG93IGRvIEkgLi4uPycgXHBhcg0KcXVlc3Rpb25zLlxwYXINClxwYXINCldo
ZW4geW91IG5lZWQgbW9yZSBkZXRhaWwgYWJvdXQgdGhlIHNwZWNpZmljIHN1YmplY3RzIGRlc2Ny
aWJlZCBpbiB0aGUgXHBhcg0KaG93LXRvIHBhcnQsIHlvdSBoYXZlIGl0IGFsbCBjb2xsZWN0ZWQg
dGhlcmUgaW4gdGhlIHJlZmVyZW5jZSBwYXJ0LCBccGFyDQpvcmdhbmlzZWQgYnkgc3ViamVjdC5c
cGFyDQpccGFyDQpUaGUgUHJvZ3JhbW1pbmcgZ3VpZGUgdGhlbiBhZGRyZXNzZXMgaXRzZWxmIHRv
IGEgc3BlY2lhbGlzdCBhdWRpZW5jZSB3aGljaCBccGFyDQppcyBhIHN1YnNldCBvZiB0aGUgYXVk
aWVuY2UgZm9yIHRoZSBVc2VyJ3MgZ3VpZGUuIEJ1dCBpdCB1c2VzIGEgc2ltaWxhciBccGFyDQpz
dHJ1Y3R1cmUgdG8gYmVmb3JlOiBpdCBzaG93cyB0aGUgcHJvZ3JhbW1lciBob3cgdG8gdXNlIHRl
eHRzLCBhY2Nlc3MgXHBhcg0KcGFyYW1ldGVycywgd29yayB3aXRoIGZpbGVzIGV0Yy5ccGFyDQpc
cGFyDQpJZiB3ZSBpbWFnaW5lIGEgc3ViamVjdC1vcmllbnRlZCByZWZlcmVuY2UgYXMgYSBzZXJp
ZXMgb2YgY29sdW1ucyB3aGVyZSBlYWNoIFxwYXINCmNvbHVtbiByZXByZXNlbnRzIGEgY29tcGxl
dGUgc2luZ2xlIHN1YmplY3QsIHRoZW4gd2UgY2FuIGltYWdpbmUgYSB1c2VyJ3MgXHBhcg0KZ3Vp
ZGUgYXMgYSBzZXQgb2Ygcm93cyB3aGVyZSBlYWNoIHJvdyByZXByZXNlbnRzIGEgZnVuY3Rpb24g
b3IgdGFzaywgd2hpY2ggXHBhcg0KdXNlcyBvbmUgb3IgbW9yZSBvZiB0aGUgc3ViamVjdHMgZm9y
IGl0cyBjb21wbGV0aW9uLiBCeSBsZWFybmluZyBob3cgdG8gXHBhcg0KY29tcGxldGUgdGFza3Mg
d2UgYXJlIGludHJvZHVjZWQgdG8gdGhlIHJlZmVyZW5jZSBzdWJqZWN0cyB0aHJvdWdoIG5lZWQg
YW5kIFxwYXINCnVzZS4gVmVyeSBmZXcgcGVvcGxlIGNhbiBsZWFybiB0byB1c2UgYSB0b29sIGJ5
IHNpdHRpbmcgZG93biBhbmQgcmVhZGluZyBhIFxwYXINCmRyeSByZWZlcmVuY2UgbWFudWFsLiBC
dXQgd2hlbiB3ZSd2ZSBiZWVuIHNob3duIHRoZSB2YXJpb3VzIHBhcnRzIGluIHVzZSwgXHBhcg0K
YW5kIGtub3cgdGhleSBleGlzdCwgd2UgY2FuIGxhdGVyIGxvb2sgbW9yZSBkZWVwbHkgYXQgdGhl
IGNvbXBvbmVudCBwYXJ0cyBccGFyDQphbmQgZmluZCBub3ZlbCB3YXlzIHRvIHVzZSB0aGVtLlxw
YXINClxwYXINCkZvciBpbnN0YW5jZSwgSSBtYXkgcmVhZCB0aGUgQkIgZG9jdW1lbnRhdGlvbiBh
Ym91dCBEb21haW5zIHVudGlsIEkga25vdyBpdCBccGFyDQpieSBoZWFydCwgZm9yd2FyZHMgYW5k
IGJhY2t3YXJkcywgYnV0IHRoYXQgZG9lc24ndCBuZWNlc3NhcmlseSBtZWFuIEkga25vdyBccGFy
DQp3aGF0IERvbWFpbnMgYXJlLCBvciB3aHkgdGhleSBleGlzdCBhbmQgd2hhdCB0aGV5J3JlIGZv
ci4gSW4gZmFjdCwgSSBoYXZlIG5vIFxwYXINCnJlYXNvbiBhdCBhbGwgdG8gcmVhZCB0aGUgRG9t
YWlucyBkb2N1bWVudGF0aW9uLiBJIGRvbid0IGtub3cgd2hhdCBhIEJCIFxwYXINCkRvbWFpbiBp
cywgc28gSSBjYW4ndCB0aGluayBvZiBhbnkgdXNlIGZvciBvbmUuXHBhcg0KXHBhcg0KT24gdGhl
IG90aGVyIGhhbmQsIGlmIEknbSBzY3JhdGNoaW5nIG15IGhlYWQgYXNraW5nIG15c2VsZiAnSG93
IGRvIEkgLi4uPycgSSBccGFyDQpzaG91bGQgYmUgYWJsZSB0byBmaW5kIHNvbWUgZG9jdW1lbnQg
dGhhdCBoZWxwcyBtZSBhbnN3ZXIgdGhhdCBxdWVzdGlvbi4gXHBhcg0KVGhpcyBkb2N1bWVudCBt
YXkgd2VsbCB0YWxrIGFib3V0IERvbWFpbnMgYXMgcGFydCBvZiB0aGUgc29sdXRpb24gdG8gbXkg
XHBhcg0KcHJvYmxlbSwgZ2l2ZSBtZSBlbm91Z2ggaW5mb3JtYXRpb24gYWJvdXQgRG9tYWlucyB0
byBzb2x2ZSB0aGUgcHJvYmxlbSwgYW5kIFxwYXINCnJlZmVyIG1lIHRvIHRoZSBjb21wbGV0ZSBE
b21haW5zIGRvY3VtZW50YXRpb24gZm9yIHdoZW4gSSBuZWVkIHRvIGRpZyBiZWxvdyBccGFyDQp0
aGUgc3VyZmFjZS4gSSBub3cgaGF2ZSBhbiBpbnRlcmVzdCBpbiBEb21haW5zLCBzbyBJJ20gbW90
aXZhdGVkIHRvIGxlYXJuIFxwYXINCmFib3V0IHRoZW0gYW5kIGNhbiBtYWtlIHNvbWUgcHJvZHVj
dGl2ZSB1c2Ugb2YgdGhlIHJlZmVyZW5jZSBtYXRlcmlhbCBhbmQgXHBhcg0KcGVyaGFwcyBkbyBz
b21ldGhpbmcgbmV3IGFuZCBpbWFnaW5hdGl2ZSB0aGF0IEkgd291bGRuJ3QgaGF2ZSBiZWVuIGFi
bGUgdG8gXHBhcg0KZG8gdW50aWwgSSBrbmV3IGFib3V0IGRvbWFpbnMuXHBhcg0KXHBhcg0KQSBj
YXJwZW50ZXIgYXBwcm9hY2hlcyBoaXMgd29ya2JlbmNoIHRvIG1ha2UgYSBjaGFpciBvciB0YWJs
ZSBmb3IgYSBccGFyDQpjdXN0b21lciwgbm90IHRvIHVzZSBoaXMgaGFtbWVyIGFuZCBzYXcuIENh
cnBlbnRlcnMgYXJlIHRhdWdodCB0byB1c2UgXHBhcg0KaGFtbWVycyBhbmQgc2F3cyBieSBtYWtp
bmcgd29vZGVuIHRoaW5nczsgdGhleSBsZWFybiB0byB1c2UgdGhlIHRvb2xzIG9ubHkgXHBhcg0K
d2hlbiB0aGV5IGNhbiBzZWUgdGhlIG5lZWQuXHBhcg0KXHBhcg0KU2ltaWxhcmx5LCBwcm9ncmFt
bWVycyBkb24ndCBzaXQgZG93biBhdCB0aGVpciBQQyB0byB1c2UgdGhlIERvbWFpbnMgbW9kdWxl
IFxwYXINCihpZiB0aGVyZSBpcyBzdWNoIGEgdGhpbmcpLiBUaGV5IHNpdCBkb3duIGF0IGl0IHRv
IHdyaXRlIHNvZnR3YXJlIHdoaWNoIHdpbGwgXHBhcg0KYmUgdXNlZnVsIGluIHRoZSB3b3JsZC5c
cGFyDQpccGFyDQpJIGhvcGUgdGhpcyBpcyBhIHVzZWZ1bCBjb250cmlidXRpb24gdG8gdGhpcyBk
aXNjdXNzaW9uIGFib3V0IEJCIFxwYXINCmRvY3VtZW50YXRpb24uIFBlcmhhcHMgdGhlIG5leHQg
c3RlcCBpcyB0byBzdGFydCBhICdIb3cgZG8gSSAuLi4/JyBGQVEuXHBhcg0KXHBhcg0KUmVnYXJk
cyxccGFyDQpccGFyDQpCb2IgV2Fsa2RlblxwYXINClxwYXINCl9fX19fX19fX19fX19fX19fX19f
X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fXHBhcg0KSG90bWFp
bCBtZXNzYWdlcyBkaXJlY3QgdG8geW91ciBtb2JpbGUgcGhvbmUgaHR0cDovL3d3dy5tc24uY28u
dWsvbXNubW9iaWxlXHBhcg0KXHBhcg0KLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t
LS0tLS0tLS0tLS1ccGFyDQpccGFyDQpUbyB1bnN1YnNjcmliZSBmcm9tIHRoaXMgbWFpbGluZyBs
aXN0LCBzZW5kIGEgbWVzc2FnZSBjb250YWluaW5nIHRoZSB3b3JkICJ1bnN1YnNjcmliZSIgdG86
XHBhcg0KICAgYmxhY2tib3gtcmVxdWVzdEBvYmVyb24uY2hccGFyDQpccGFyDQpUbyBnZXQgYSBs
aXN0IG9mIHZhbGlkIGUtbWFpbCBjb21tYW5kcyBhbmQgaW5zdHJ1Y3Rpb25zIG9uIHRoZWlyIHVz
YWdlLCBzZW5kIGEgbWVzc2FnZSBjb250YWluaW5nIHRoZSB3b3JkICJoZWxwIiB0byB0aGUgYWJv
dmUgYWRkcmVzcy5ccGFyDQpccGFyDQpTZW5kIGFueSBwcm9ibGVtIHJlcG9ydHMgb3IgcXVlc3Rp
b25zIHJlbGF0ZWQgdG8gdGhpcyBlbWFpbCBsaXN0IHRvIHRoZSBsaXN0IG93bmVyIGF0XHBhcg0K
ICAgb3duZXItYmxhY2tib3hAb2Jlcm9uLmNoXHBhcg0KXHBhcg0KQ3VycmVudCBwb3N0aW5nIHBv
bGljeTpccGFyDQpccGFyDQphKSBUbyBwb3N0IHlvdSBzaG91bGQgdXNlIHRoZSBzYW1lIGFkZHJl
c3MgYnkgd2hpY2ggeW91IGFyZSBzdWJzY3JpYmVkIHRvIHRoZSBtYWlsaW5nIGxpc3QuIFRoYXQg
d2F5LCB0aGUgbGlzdCBzZXJ2ZXIgd2lsbCByZWNvZ25pemUgeW91IGFzIHN1YnNjcmliZXIgYW5k
IGZvcndhcmQgeW91ciBwb3N0aW5nIGltbWVkaWF0ZWx5LCB3aXRob3V0IGNyZWF0aW5nIGFueSBv
dmVyaGVhZC5ccGFyDQpccGFyDQpiKSBJZiwgZm9yIHNvbWUgcmVhc29uLCB5b3UgY2Fubm90IHBv
c3QgZnJvbSB0aGUgYWRkcmVzcywgYnkgd2hpY2ggeW91IGFyZSBzdWJzY3JpYmVkLCB5b3VyIG1l
c3NhZ2Ugd2lsbCBiZSBtb2RlcmF0ZWQgdG8gYXZvaWQgc3BhbS4gUGxlYXNlIHVuZGVyc3RhbmQg
dGhhdCBtb2RlcmF0aW9uIHdpbGwgb2Z0ZW4gY2F1c2Ugc29tZSBkZWxheSwgaW4gcGFydGljdWxh
ciBvdmVyIHdlZWtlbmRzIG9yIGhvbHlkYXlzfX0AL8QXUO61/wckgUA=
----boundary-LibPST-iamunique-296293369_-_---
Received on Sun Aug 03 2003 - 11:21:25 UTC