Re: Documentation and pointers

From: [at]} <Wojtek>
Date: Sun, 3 Aug 2003 16:45:05 -0400 (EDT)

----boundary-LibPST-iamunique-162073461_-_-
Content-type: text/plain

On Sun, 3 Aug 2003, Bob Walkden wrote:

> 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.

I think your discussion is right. I stand corrected concerning the
Reiser's book. It is a good example to follow.

In practice it had a fatal flaw: it described Oberon System V1, while
the version which was released outside ETH was V2, later replaced
by V4. The Reiser's book was not very relevant concerning the most
valuable part of the Oberon System, which was Szyperski's Write
and Write Elements, which in V4 became the central part of the GUI.
The example part of the book described the subsystem which never
became widely used, while the one which became widely used was not
documented in the book.

It is an important requirement that good documentation should be up to
date to be of practical value. This was illustrated by the Reiser's book,
unfortunately to the Oberon System's peril. This brings the time dimension
to the problem: it is not enough to write a nice book once, it also needs
to be updated with every major software release. We are speaking of
documentation of evolving software, not of scientific dissertations
which are published once and then left frozen.

Wojtek


--------------------------------------------

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-162073461_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"

e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIE9uIFN1biwgMyBBdWcgMjAwMywgQm9iIFdhbGtk
ZW4gd3JvdGU6XHBhcg0KXHBhcg0KPiBNYXJ0aW4gUmVpc2VyJ3MgYm9vayAnVGhlIE9iZXJvbiBT
eXN0ZW0nIGlzIGEgZ29vZCBleGFtcGxlIHdoaWNoIHVzZXMgYm90aFxwYXINCj4gZGltZW5zaW9u
cy4gSXQgaXMgb3JnYW5pc2VkIGludG8gMyBwYXJ0czogVXNlcidzIGd1aWRlLCBSZWZlcmVuY2Ug
YW5kXHBhcg0KPiBQcm9ncmFtbWluZyBndWlkZS5ccGFyDQpccGFyDQpJIHRoaW5rIHlvdXIgZGlz
Y3Vzc2lvbiBpcyByaWdodC4gSSBzdGFuZCBjb3JyZWN0ZWQgY29uY2VybmluZyB0aGVccGFyDQpS
ZWlzZXIncyBib29rLiBJdCBpcyBhIGdvb2QgZXhhbXBsZSB0byBmb2xsb3cuXHBhcg0KXHBhcg0K
SW4gcHJhY3RpY2UgaXQgaGFkIGEgZmF0YWwgZmxhdzogaXQgZGVzY3JpYmVkIE9iZXJvbiBTeXN0
ZW0gVjEsIHdoaWxlXHBhcg0KdGhlIHZlcnNpb24gd2hpY2ggd2FzIHJlbGVhc2VkIG91dHNpZGUg
RVRIIHdhcyBWMiwgbGF0ZXIgcmVwbGFjZWRccGFyDQpieSBWNC4gVGhlIFJlaXNlcidzIGJvb2sg
d2FzIG5vdCB2ZXJ5IHJlbGV2YW50IGNvbmNlcm5pbmcgdGhlIG1vc3RccGFyDQp2YWx1YWJsZSBw
YXJ0IG9mIHRoZSBPYmVyb24gU3lzdGVtLCB3aGljaCB3YXMgU3p5cGVyc2tpJ3MgV3JpdGVccGFy
DQphbmQgV3JpdGUgRWxlbWVudHMsIHdoaWNoIGluIFY0IGJlY2FtZSB0aGUgY2VudHJhbCBwYXJ0
IG9mIHRoZSBHVUkuXHBhcg0KVGhlIGV4YW1wbGUgcGFydCBvZiB0aGUgYm9vayBkZXNjcmliZWQg
dGhlIHN1YnN5c3RlbSB3aGljaCBuZXZlclxwYXINCmJlY2FtZSB3aWRlbHkgdXNlZCwgd2hpbGUg
dGhlIG9uZSB3aGljaCBiZWNhbWUgd2lkZWx5IHVzZWQgd2FzIG5vdFxwYXINCmRvY3VtZW50ZWQg
aW4gdGhlIGJvb2suXHBhcg0KXHBhcg0KSXQgaXMgYW4gaW1wb3J0YW50IHJlcXVpcmVtZW50IHRo
YXQgZ29vZCBkb2N1bWVudGF0aW9uIHNob3VsZCBiZSB1cCB0b1xwYXINCmRhdGUgdG8gYmUgb2Yg
cHJhY3RpY2FsIHZhbHVlLiBUaGlzIHdhcyBpbGx1c3RyYXRlZCBieSB0aGUgUmVpc2VyJ3MgYm9v
ayxccGFyDQp1bmZvcnR1bmF0ZWx5IHRvIHRoZSBPYmVyb24gU3lzdGVtJ3MgcGVyaWwuIFRoaXMg
YnJpbmdzIHRoZSB0aW1lIGRpbWVuc2lvblxwYXINCnRvIHRoZSBwcm9ibGVtOiBpdCBpcyBub3Qg
ZW5vdWdoIHRvIHdyaXRlIGEgbmljZSBib29rIG9uY2UsIGl0IGFsc28gbmVlZHNccGFyDQp0byBi
ZSB1cGRhdGVkIHdpdGggZXZlcnkgbWFqb3Igc29mdHdhcmUgcmVsZWFzZS4gV2UgYXJlIHNwZWFr
aW5nIG9mXHBhcg0KZG9jdW1lbnRhdGlvbiBvZiBldm9sdmluZyBzb2Z0d2FyZSwgbm90IG9mIHNj
aWVudGlmaWMgZGlzc2VydGF0aW9uc1xwYXINCndoaWNoIGFyZSBwdWJsaXNoZWQgb25jZSBhbmQg
dGhlbiBsZWZ0IGZyb3plbi5ccGFyDQpccGFyDQpXb2p0ZWtccGFyDQpccGFyDQpccGFyDQotLS0t
LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLVxwYXINClxwYXINClRvIHVu
c3Vic2NyaWJlIGZyb20gdGhpcyBtYWlsaW5nIGxpc3QsIHNlbmQgYSBtZXNzYWdlIGNvbnRhaW5p
bmcgdGhlIHdvcmQgInVuc3Vic2NyaWJlIiB0bzpccGFyDQogICBibGFja2JveC1yZXF1ZXN0QG9i
ZXJvbi5jaFxwYXINClxwYXINClRvIGdldCBhIGxpc3Qgb2YgdmFsaWQgZS1tYWlsIGNvbW1hbmRz
IGFuZCBpbnN0cnVjdGlvbnMgb24gdGhlaXIgdXNhZ2UsIHNlbmQgYSBtZXNzYWdlIGNvbnRhaW5p
bmcgdGhlIHdvcmQgImhlbHAiIHRvIHRoZSBhYm92ZSBhZGRyZXNzLlxwYXINClxwYXINClNlbmQg
YW55IHByb2JsZW0gcmVwb3J0cyBvciBxdWVzdGlvbnMgcmVsYXRlZCB0byB0aGlzIGVtYWlsIGxp
c3QgdG8gdGhlIGxpc3Qgb3duZXIgYXRccGFyDQogICBvd25lci1ibGFja2JveEBvYmVyb24uY2hc
cGFyDQpccGFyDQpDdXJyZW50IHBvc3RpbmcgcG9saWN5OlxwYXINClxwYXINCmEpIFRvIHBvc3Qg
eW91IHNob3VsZCB1c2UgdGhlIHNhbWUgYWRkcmVzcyBieSB3aGljaCB5b3UgYXJlIHN1YnNjcmli
ZWQgdG8gdGhlIG1haWxpbmcgbGlzdC4gVGhhdCB3YXksIHRoZSBsaXN0IHNlcnZlciB3aWxsIHJl
Y29nbml6ZSB5b3UgYXMgc3Vic2NyaWJlciBhbmQgZm9yd2FyZCB5b3VyIHBvc3RpbmcgaW1tZWRp
YXRlbHksIHdpdGhvdXQgY3JlYXRpbmcgYW55IG92ZXJoZWFkLlxwYXINClxwYXINCmIpIElmLCBm
b3Igc29tZSByZWFzb24sIHlvdSBjYW5ub3QgcG9zdCBmcm9tIHRoZSBhZGRyZXNzLCBieSB3aGlj
aCB5b3UgYXJlIHN1YnNjcmliZWQsIHlvdXIgbWVzc2FnZSB3aWxsIGJlIG1vZGVyYXRlZCB0byBh
dm9pZCBzcGFtLiBQbGVhc2UgdW5kZXJzdGFuZCB0aGF0IG1vZGVyYXRpb24gd2lsbCBvZnRlbiBj
YXVzZSBzb21lIGRlbGF5LCBpbiBwYXJ0aWN1bGFyIG92ZXIgd2Vla2VuZHMgb3IgaG9seWRheXN9
fQBUSU1FPVszMTFEQw==


----boundary-LibPST-iamunique-162073461_-_---
Received on Sun Aug 03 2003 - 22:45:05 UTC