----boundary-LibPST-iamunique-1366875772_-_-
Content-type: text/plain
On Sun, 3 Aug 2003 ftkachov{([at]})nowhere.xy
> it is extremely difficult for the author to write from a perspective
> of someone who knows nothing about the subject.
> That's why the original scientific papers are incomprehensible.
Of course. I have a box full of scientific papers written by Ominc staff.
I have theses by Wolfgang Weck, Josef Templ, Stefan Gehring, and several
others. I do not understand much of what they are saying in their theses,
just like you said. This is fine. But the BlackBox docu should not be judged
by the same standards. The documentation of a software development system
is not a scientific paper, is it? It rather should help the customers use
the software to achieve *their* development goals, should it not? A good
technical writer writes a user manual from the user perspective. Are you
denying that BB documentation is, or should be, serving the role of the
user manual for the system (also a developer's manual, to be exact)?
> > The use of "one place only" and "multiple descriptions" are at variance
>
> again, this is the usual problems of any complex design
Complex design should not mean complex documentation. These are two
different things.
> -- is why there is so much ..ppy software out there.
What is .ppy software? I have not heard this term before.
> I'd rather choose imperfectly documented great software.
Well, yes, up to the point. Let me tell you from my own electronic
experience: the prime reason I am using certain chips is documentation.
Other chips may be perhaps better, but I need information to develop my
designs. Imperfectly documented chip is plain useless. Software is not
much different. There is a point where undocumented features become
too hard to find out, and thus useless. I am not saying BB has reached
this point, but some parts of the system are less than useful because
of the convoluted information.
> Wojtek, there was nothing of a reprimand in any of my messages,
I was joking. Just to find out if you are at work on Saturday. I am.
> > There must be some way that the Blackbox user community can help Ominc
> > improve its documentation.
>
> That's exactly the point. Let's shift the emphasis to what we can do
> as a community.
To be honest, we need to write documentation ourselves. Ominc will not
do it. They used to say something about business decisions, but I do not
believe them. I think they plainly do not know how to write good users'
manuals. This was always the case with ETH products. I have all the
Oberon books, and I do not think they make good user manuals. I think they
are good textbooks, but not good manuals. I think ETH did not teach this
particular subject well, how to write good software manuals. Nothing
personal, just an observation. This being the case, either we write
something ourselves, or it will not be done. This is lots of work, as you
know. To be concrete, I have this on my menu, to write user's manuals
for my own products. I am getting there, but slower than I would wish.
I guess this is always the case.
Concerning the physics initiative, we will not escape writing a book.
I guess you realise this, Fyodor, do not you? We are not looking forward
to it, but this needs to be done. You know, the kind of joint contributed
book, with chapters written by contributing authors. You can write up
your stuff, I will write mine, and alltogether there will be a book about
scientific applications of Blackbox. This is lots of work. It is not clear
at this point what to do about other flavors of Oberon. I think that a
well-focused book needs to address just BlackBox, otherwise it will not
be that useful. Other sub-communities will address their stuff, such as
BlueBottle, while we address ours.
I do not think we can escape writing the book. The tentative time scale
can be something like three years till publication. Otherwise it is not
interesting. This means that about 10% time needs to be set aside
to achieve this, if start sort of now. Say, this fall or winter.
Are you looking forward to this? I do not. Do you think it can be skipped?
I do not. We need to get started.
Cheers,
W.
--------------------------------------------
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-1366875772_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIE9uIFN1biwgMyBBdWcgMjAwMyBmdGthY2hvdkBt
czIuaW5yLmFjLnJ1IHdyb3RlOlxwYXINClxwYXINCj4gaXQgaXMgZXh0cmVtZWx5IGRpZmZpY3Vs
dCBmb3IgdGhlIGF1dGhvciB0byB3cml0ZSBmcm9tIGEgcGVyc3BlY3RpdmVccGFyDQo+IG9mIHNv
bWVvbmUgd2hvIGtub3dzIG5vdGhpbmcgYWJvdXQgdGhlIHN1YmplY3QuXHBhcg0KPiBUaGF0J3Mg
d2h5IHRoZSBvcmlnaW5hbCBzY2llbnRpZmljIHBhcGVycyBhcmUgaW5jb21wcmVoZW5zaWJsZS5c
cGFyDQpccGFyDQpPZiBjb3Vyc2UuIEkgaGF2ZSBhIGJveCBmdWxsIG9mIHNjaWVudGlmaWMgcGFw
ZXJzIHdyaXR0ZW4gYnkgT21pbmMgc3RhZmYuXHBhcg0KSSBoYXZlIHRoZXNlcyBieSBXb2xmZ2Fu
ZyBXZWNrLCBKb3NlZiBUZW1wbCwgU3RlZmFuIEdlaHJpbmcsIGFuZCBzZXZlcmFsXHBhcg0Kb3Ro
ZXJzLiBJIGRvIG5vdCB1bmRlcnN0YW5kIG11Y2ggb2Ygd2hhdCB0aGV5IGFyZSBzYXlpbmcgaW4g
dGhlaXIgdGhlc2VzLFxwYXINCmp1c3QgbGlrZSB5b3Ugc2FpZC4gVGhpcyBpcyBmaW5lLiBCdXQg
dGhlIEJsYWNrQm94IGRvY3Ugc2hvdWxkIG5vdCBiZSBqdWRnZWRccGFyDQpieSB0aGUgc2FtZSBz
dGFuZGFyZHMuIFRoZSBkb2N1bWVudGF0aW9uIG9mIGEgc29mdHdhcmUgZGV2ZWxvcG1lbnQgc3lz
dGVtXHBhcg0KaXMgbm90IGEgc2NpZW50aWZpYyBwYXBlciwgaXMgaXQ/IEl0IHJhdGhlciBzaG91
bGQgaGVscCB0aGUgY3VzdG9tZXJzIHVzZVxwYXINCnRoZSBzb2Z0d2FyZSB0byBhY2hpZXZlICp0
aGVpciogZGV2ZWxvcG1lbnQgZ29hbHMsIHNob3VsZCBpdCBub3Q/IEEgZ29vZFxwYXINCnRlY2hu
aWNhbCB3cml0ZXIgd3JpdGVzIGEgdXNlciBtYW51YWwgZnJvbSB0aGUgdXNlciBwZXJzcGVjdGl2
ZS4gQXJlIHlvdVxwYXINCmRlbnlpbmcgdGhhdCBCQiBkb2N1bWVudGF0aW9uIGlzLCBvciBzaG91
bGQgYmUsIHNlcnZpbmcgdGhlIHJvbGUgb2YgdGhlXHBhcg0KdXNlciBtYW51YWwgZm9yIHRoZSBz
eXN0ZW0gKGFsc28gYSBkZXZlbG9wZXIncyBtYW51YWwsIHRvIGJlIGV4YWN0KT9ccGFyDQpccGFy
DQpccGFyDQo+ID4gVGhlIHVzZSBvZiAib25lIHBsYWNlIG9ubHkiIGFuZCAibXVsdGlwbGUgZGVz
Y3JpcHRpb25zIiBhcmUgYXQgdmFyaWFuY2VccGFyDQo+XHBhcg0KPiBhZ2FpbiwgdGhpcyBpcyB0
aGUgdXN1YWwgcHJvYmxlbXMgb2YgYW55IGNvbXBsZXggZGVzaWduXHBhcg0KXHBhcg0KQ29tcGxl
eCBkZXNpZ24gc2hvdWxkIG5vdCBtZWFuIGNvbXBsZXggZG9jdW1lbnRhdGlvbi4gVGhlc2UgYXJl
IHR3b1xwYXINCmRpZmZlcmVudCB0aGluZ3MuXHBhcg0KXHBhcg0KXHBhcg0KPiAtLSBpcyB3aHkg
dGhlcmUgaXMgc28gbXVjaCAuLnBweSBzb2Z0d2FyZSBvdXQgdGhlcmUuXHBhcg0KXHBhcg0KV2hh
dCBpcyAucHB5IHNvZnR3YXJlPyBJIGhhdmUgbm90IGhlYXJkIHRoaXMgdGVybSBiZWZvcmUuXHBh
cg0KXHBhcg0KXHBhcg0KPiBJJ2QgcmF0aGVyIGNob29zZSBpbXBlcmZlY3RseSBkb2N1bWVudGVk
IGdyZWF0IHNvZnR3YXJlLlxwYXINClxwYXINCldlbGwsIHllcywgdXAgdG8gdGhlIHBvaW50LiBM
ZXQgbWUgdGVsbCB5b3UgZnJvbSBteSBvd24gZWxlY3Ryb25pY1xwYXINCmV4cGVyaWVuY2U6IHRo
ZSBwcmltZSByZWFzb24gSSBhbSB1c2luZyBjZXJ0YWluIGNoaXBzIGlzIGRvY3VtZW50YXRpb24u
XHBhcg0KT3RoZXIgY2hpcHMgbWF5IGJlIHBlcmhhcHMgYmV0dGVyLCBidXQgSSBuZWVkIGluZm9y
bWF0aW9uIHRvIGRldmVsb3AgbXlccGFyDQpkZXNpZ25zLiBJbXBlcmZlY3RseSBkb2N1bWVudGVk
IGNoaXAgaXMgcGxhaW4gdXNlbGVzcy4gU29mdHdhcmUgaXMgbm90XHBhcg0KbXVjaCBkaWZmZXJl
bnQuIFRoZXJlIGlzIGEgcG9pbnQgd2hlcmUgdW5kb2N1bWVudGVkIGZlYXR1cmVzIGJlY29tZVxw
YXINCnRvbyBoYXJkIHRvIGZpbmQgb3V0LCBhbmQgdGh1cyB1c2VsZXNzLiBJIGFtIG5vdCBzYXlp
bmcgQkIgaGFzIHJlYWNoZWRccGFyDQp0aGlzIHBvaW50LCBidXQgc29tZSBwYXJ0cyBvZiB0aGUg
c3lzdGVtIGFyZSBsZXNzIHRoYW4gdXNlZnVsIGJlY2F1c2VccGFyDQpvZiB0aGUgY29udm9sdXRl
ZCBpbmZvcm1hdGlvbi5ccGFyDQpccGFyDQpccGFyDQo+IFdvanRlaywgdGhlcmUgd2FzIG5vdGhp
bmcgb2YgYSByZXByaW1hbmQgaW4gYW55IG9mIG15IG1lc3NhZ2VzLFxwYXINClxwYXINCkkgd2Fz
IGpva2luZy4gSnVzdCB0byBmaW5kIG91dCBpZiB5b3UgYXJlIGF0IHdvcmsgb24gU2F0dXJkYXku
IEkgYW0uXHBhcg0KXHBhcg0KXHBhcg0KPiA+IFRoZXJlIG11c3QgYmUgc29tZSB3YXkgdGhhdCB0
aGUgQmxhY2tib3ggdXNlciBjb21tdW5pdHkgY2FuIGhlbHAgT21pbmNccGFyDQo+ID4gaW1wcm92
ZSBpdHMgZG9jdW1lbnRhdGlvbi5ccGFyDQo+XHBhcg0KPiBUaGF0J3MgZXhhY3RseSB0aGUgcG9p
bnQuIExldCdzIHNoaWZ0IHRoZSBlbXBoYXNpcyB0byB3aGF0IHdlIGNhbiBkb1xwYXINCj4gYXMg
YSBjb21tdW5pdHkuXHBhcg0KXHBhcg0KVG8gYmUgaG9uZXN0LCB3ZSBuZWVkIHRvIHdyaXRlIGRv
Y3VtZW50YXRpb24gb3Vyc2VsdmVzLiBPbWluYyB3aWxsIG5vdFxwYXINCmRvIGl0LiBUaGV5IHVz
ZWQgdG8gc2F5IHNvbWV0aGluZyBhYm91dCBidXNpbmVzcyBkZWNpc2lvbnMsIGJ1dCBJIGRvIG5v
dFxwYXINCmJlbGlldmUgdGhlbS4gSSB0aGluayB0aGV5IHBsYWlubHkgZG8gbm90IGtub3cgaG93
IHRvIHdyaXRlIGdvb2QgdXNlcnMnXHBhcg0KbWFudWFscy4gVGhpcyB3YXMgYWx3YXlzIHRoZSBj
YXNlIHdpdGggRVRIIHByb2R1Y3RzLiBJIGhhdmUgYWxsIHRoZVxwYXINCk9iZXJvbiBib29rcywg
YW5kIEkgZG8gbm90IHRoaW5rIHRoZXkgbWFrZSBnb29kIHVzZXIgbWFudWFscy4gSSB0aGluayB0
aGV5XHBhcg0KYXJlIGdvb2QgdGV4dGJvb2tzLCBidXQgbm90IGdvb2QgbWFudWFscy4gSSB0aGlu
ayBFVEggZGlkIG5vdCB0ZWFjaCB0aGlzXHBhcg0KcGFydGljdWxhciBzdWJqZWN0IHdlbGwsIGhv
dyB0byB3cml0ZSBnb29kIHNvZnR3YXJlIG1hbnVhbHMuIE5vdGhpbmdccGFyDQpwZXJzb25hbCwg
anVzdCBhbiBvYnNlcnZhdGlvbi4gVGhpcyBiZWluZyB0aGUgY2FzZSwgZWl0aGVyIHdlIHdyaXRl
XHBhcg0Kc29tZXRoaW5nIG91cnNlbHZlcywgb3IgaXQgd2lsbCBub3QgYmUgZG9uZS4gVGhpcyBp
cyBsb3RzIG9mIHdvcmssIGFzIHlvdVxwYXINCmtub3cuIFRvIGJlIGNvbmNyZXRlLCBJIGhhdmUg
dGhpcyBvbiBteSBtZW51LCB0byB3cml0ZSB1c2VyJ3MgbWFudWFsc1xwYXINCmZvciBteSBvd24g
cHJvZHVjdHMuIEkgYW0gZ2V0dGluZyB0aGVyZSwgYnV0IHNsb3dlciB0aGFuIEkgd291bGQgd2lz
aC5ccGFyDQpJIGd1ZXNzIHRoaXMgaXMgYWx3YXlzIHRoZSBjYXNlLlxwYXINClxwYXINCkNvbmNl
cm5pbmcgdGhlIHBoeXNpY3MgaW5pdGlhdGl2ZSwgd2Ugd2lsbCBub3QgZXNjYXBlIHdyaXRpbmcg
YSBib29rLlxwYXINCkkgZ3Vlc3MgeW91IHJlYWxpc2UgdGhpcywgRnlvZG9yLCBkbyBub3QgeW91
PyBXZSBhcmUgbm90IGxvb2tpbmcgZm9yd2FyZFxwYXINCnRvIGl0LCBidXQgdGhpcyBuZWVkcyB0
byBiZSBkb25lLiBZb3Uga25vdywgdGhlIGtpbmQgb2Ygam9pbnQgY29udHJpYnV0ZWRccGFyDQpi
b29rLCB3aXRoIGNoYXB0ZXJzIHdyaXR0ZW4gYnkgY29udHJpYnV0aW5nIGF1dGhvcnMuIFlvdSBj
YW4gd3JpdGUgdXBccGFyDQp5b3VyIHN0dWZmLCBJIHdpbGwgd3JpdGUgbWluZSwgYW5kIGFsbHRv
Z2V0aGVyIHRoZXJlIHdpbGwgYmUgYSBib29rIGFib3V0XHBhcg0Kc2NpZW50aWZpYyBhcHBsaWNh
dGlvbnMgb2YgQmxhY2tib3guIFRoaXMgaXMgbG90cyBvZiB3b3JrLiBJdCBpcyBub3QgY2xlYXJc
cGFyDQphdCB0aGlzIHBvaW50IHdoYXQgdG8gZG8gYWJvdXQgb3RoZXIgZmxhdm9ycyBvZiBPYmVy
b24uIEkgdGhpbmsgdGhhdCBhXHBhcg0Kd2VsbC1mb2N1c2VkIGJvb2sgbmVlZHMgdG8gYWRkcmVz
cyBqdXN0IEJsYWNrQm94LCBvdGhlcndpc2UgaXQgd2lsbCBub3RccGFyDQpiZSB0aGF0IHVzZWZ1
bC4gT3RoZXIgc3ViLWNvbW11bml0aWVzIHdpbGwgYWRkcmVzcyB0aGVpciBzdHVmZiwgc3VjaCBh
c1xwYXINCkJsdWVCb3R0bGUsIHdoaWxlIHdlIGFkZHJlc3Mgb3Vycy5ccGFyDQpccGFyDQpJIGRv
IG5vdCB0aGluayB3ZSBjYW4gZXNjYXBlIHdyaXRpbmcgdGhlIGJvb2suIFRoZSB0ZW50YXRpdmUg
dGltZSBzY2FsZVxwYXINCmNhbiBiZSBzb21ldGhpbmcgbGlrZSB0aHJlZSB5ZWFycyB0aWxsIHB1
YmxpY2F0aW9uLiBPdGhlcndpc2UgaXQgaXMgbm90XHBhcg0KaW50ZXJlc3RpbmcuIFRoaXMgbWVh
bnMgdGhhdCBhYm91dCAxMCUgdGltZSBuZWVkcyB0byBiZSBzZXQgYXNpZGVccGFyDQp0byBhY2hp
ZXZlIHRoaXMsIGlmIHN0YXJ0IHNvcnQgb2Ygbm93LiBTYXksIHRoaXMgZmFsbCBvciB3aW50ZXIu
XHBhcg0KXHBhcg0KQXJlIHlvdSBsb29raW5nIGZvcndhcmQgdG8gdGhpcz8gSSBkbyBub3QuIERv
IHlvdSB0aGluayBpdCBjYW4gYmUgc2tpcHBlZD9ccGFyDQpJIGRvIG5vdC4gV2UgbmVlZCB0byBn
ZXQgc3RhcnRlZC5ccGFyDQpccGFyDQpDaGVlcnMsXHBhcg0KXHBhcg0KVy5ccGFyDQpccGFyDQpc
cGFyDQpccGFyDQotLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLVxw
YXINClxwYXINClRvIHVuc3Vic2NyaWJlIGZyb20gdGhpcyBtYWlsaW5nIGxpc3QsIHNlbmQgYSBt
ZXNzYWdlIGNvbnRhaW5pbmcgdGhlIHdvcmQgInVuc3Vic2NyaWJlIiB0bzpccGFyDQogICBibGFj
a2JveC1yZXF1ZXN0QG9iZXJvbi5jaFxwYXINClxwYXINClRvIGdldCBhIGxpc3Qgb2YgdmFsaWQg
ZS1tYWlsIGNvbW1hbmRzIGFuZCBpbnN0cnVjdGlvbnMgb24gdGhlaXIgdXNhZ2UsIHNlbmQgYSBt
ZXNzYWdlIGNvbnRhaW5pbmcgdGhlIHdvcmQgImhlbHAiIHRvIHRoZSBhYm92ZSBhZGRyZXNzLlxw
YXINClxwYXINClNlbmQgYW55IHByb2JsZW0gcmVwb3J0cyBvciBxdWVzdGlvbnMgcmVsYXRlZCB0
byB0aGlzIGVtYWlsIGxpc3QgdG8gdGhlIGxpc3Qgb3duZXIgYXRccGFyDQogICBvd25lci1ibGFj
a2JveEBvYmVyb24uY2hccGFyDQpccGFyDQpDdXJyZW50IHBvc3RpbmcgcG9saWN5OlxwYXINClxw
YXINCmEpIFRvIHBvc3QgeW91IHNob3VsZCB1c2UgdGhlIHNhbWUgYWRkcmVzcyBieSB3aGljaCB5
b3UgYXJlIHN1YnNjcmliZWQgdG8gdGhlIG1haWxpbmcgbGlzdC4gVGhhdCB3YXksIHRoZSBsaXN0
IHNlcnZlciB3aWxsIHJlY29nbml6ZSB5b3UgYXMgc3Vic2NyaWJlciBhbmQgZm9yd2FyZCB5b3Vy
IHBvc3RpbmcgaW1tZWRpYXRlbHksIHdpdGhvdXQgY3JlYXRpbmcgYW55IG92ZXJoZWFkLlxwYXIN
ClxwYXINCmIpIElmLCBmb3Igc29tZSByZWFzb24sIHlvdSBjYW5ub3QgcG9zdCBmcm9tIHRoZSBh
ZGRyZXNzLCBieSB3aGljaCB5b3UgYXJlIHN1YnNjcmliZWQsIHlvdXIgbWVzc2FnZSB3aWxsIGJl
IG1vZGVyYXRlZCB0byBhdm9pZCBzcGFtLiBQbGVhc2UgdW5kZXJzdGFuZCB0aGF0IG1vZGVyYXRp
b24gd2lsbCBvZnRlbiBjYXVzZSBzb21lIGRlbGF5LCBpbiBwYXJ0aWN1bGFyIG92ZXIgd2Vla2Vu
ZHMgb3IgaG9seWRheX19AGYgdGhlIHN5c3RlbQ==
----boundary-LibPST-iamunique-1366875772_-_---
Received on Sun Aug 03 2003 - 02:16:19 UTC