----boundary-LibPST-iamunique-1619990833_-_-
Content-type: text/plain
The little documentation project seems to be about as dormant as I have. I guess everyone has been as busy as I have been.
I think Wojtek Skulski stated the problem exactly when he said, essentially, that the BB documentation was written from the inside out, like the unreadable documentation for a computer chip. I really think documentation is the single biggest problem with adoptation of any Oberon language. There are other problems, like being embedded in a framework. But the framework is supposed to be useful. Again, the problem is documentation. Why is it useful? People need to be shown in a simple, concise, way. Since BlackBox is a bit unconventional, and uses some unexpected terminology and concepts, I think the documentation has to be a little better than the average language manual. Tutorials are excellent, but there needs to be a manual too.
Fortunately, I don't think it looks overwhelming. First of all, the current documentation is so easily edited. I find that even as I read through the documentation, when I finally decipher what they are talking about, it is very easy to add a simple explanation, or at least an introduction. I just put my changes in red for tracking.
The first thing it needs is a simple overview. Briefly, where do you find out how to do what needs to be done? Each module, or each library, or whatever, should have a brief description in plain English. Make sure each module is described. (For example, the help document does not have a single word about serial communications. I had absolutely no idea that BlackBox had a nice communications package.) Make sure titles and groupings of modules (subsystems) are consistent and clear throughout. (For example, the Roadmap talks about Commands and Views, and not much else. Where in the rest of the manual do I find out about commands and views? Information seems to be scattered throughout.) Some of the development system seems to be in User Manuals instead of Developer Manuals.
Each module or subsystem also needs a simple introduction that tells what things do and where to find things. Somewhere there needs to be a description of the menu items. The examples are good, but they are all thrown together. They need to be relocated to the appropriate modules.
There needs to be a simple, prominent, and unified description of I/O. As a minimum, there needs to be a section on working with foreign files, because that is what the rest of the world uses. There needs to be a simple description of I/O from files, keyboard+monitor, and mouse.
So how big a job is this? What do you think?
Rex Couture
Rex Couture, Ph. D.
Dept. of Earth and Planetary Sciences
Campus Box 1169
Washington University in St. Louis
1 Brookings Dr.
St. Louis MO 63130
Voice: (314) 935-4194
Fax: (314) 935-7361
rex{([at]})nowhere.xy
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy
----boundary-LibPST-iamunique-1619990833_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwICAgICAgICAgIFRoZSBsaXR0bGUgZG9jdW1lbnRh
dGlvbiBwcm9qZWN0IHNlZW1zIHRvIGJlIGFib3V0IGFzIGRvcm1hbnQgYXMgSSBoYXZlLiAgSSBn
dWVzcyBldmVyeW9uZSBoYXMgYmVlbiBhcyBidXN5IGFzIEkgaGF2ZSBiZWVuLlxwYXINClxwYXIN
CiAgICAgICAgSSB0aGluayBXb2p0ZWsgU2t1bHNraSBzdGF0ZWQgdGhlIHByb2JsZW0gZXhhY3Rs
eSB3aGVuIGhlIHNhaWQsIGVzc2VudGlhbGx5LCB0aGF0IHRoZSBCQiBkb2N1bWVudGF0aW9uIHdh
cyB3cml0dGVuIGZyb20gdGhlIGluc2lkZSBvdXQsIGxpa2UgdGhlIHVucmVhZGFibGUgZG9jdW1l
bnRhdGlvbiBmb3IgYSBjb21wdXRlciBjaGlwLiAgSSByZWFsbHkgdGhpbmsgZG9jdW1lbnRhdGlv
biBpcyB0aGUgc2luZ2xlIGJpZ2dlc3QgcHJvYmxlbSB3aXRoIGFkb3B0YXRpb24gb2YgYW55IE9i
ZXJvbiBsYW5ndWFnZS4gIFRoZXJlIGFyZSBvdGhlciBwcm9ibGVtcywgbGlrZSBiZWluZyBlbWJl
ZGRlZCBpbiBhIGZyYW1ld29yay4gIEJ1dCB0aGUgZnJhbWV3b3JrIGlzIHN1cHBvc2VkIHRvIGJl
IHVzZWZ1bC4gIEFnYWluLCB0aGUgcHJvYmxlbSBpcyBkb2N1bWVudGF0aW9uLiAgV2h5IGlzIGl0
IHVzZWZ1bD8gIFBlb3BsZSBuZWVkIHRvIGJlIHNob3duIGluIGEgc2ltcGxlLCBjb25jaXNlLCB3
YXkuICBTaW5jZSBCbGFja0JveCBpcyBhIGJpdCB1bmNvbnZlbnRpb25hbCwgYW5kIHVzZXMgc29t
ZSB1bmV4cGVjdGVkIHRlcm1pbm9sb2d5IGFuZCBjb25jZXB0cywgSSB0aGluayB0aGUgZG9jdW1l
bnRhdGlvbiBoYXMgdG8gYmUgYSBsaXR0bGUgYmV0dGVyIHRoYW4gdGhlIGF2ZXJhZ2UgbGFuZ3Vh
Z2UgbWFudWFsLiAgVHV0b3JpYWxzIGFyZSBleGNlbGxlbnQsIGJ1dCB0aGVyZSBuZWVkcyB0byBi
ZSBhIG1hbnVhbCB0b28uXHBhcg0KXHBhcg0KICAgICAgICBGb3J0dW5hdGVseSwgSSBkb24ndCB0
aGluayBpdCBsb29rcyBvdmVyd2hlbG1pbmcuICBGaXJzdCBvZiBhbGwsIHRoZSBjdXJyZW50IGRv
Y3VtZW50YXRpb24gaXMgc28gZWFzaWx5IGVkaXRlZC4gIEkgZmluZCB0aGF0IGV2ZW4gYXMgSSBy
ZWFkIHRocm91Z2ggdGhlIGRvY3VtZW50YXRpb24sIHdoZW4gSSBmaW5hbGx5IGRlY2lwaGVyIHdo
YXQgdGhleSBhcmUgdGFsa2luZyBhYm91dCwgaXQgaXMgdmVyeSBlYXN5IHRvIGFkZCBhIHNpbXBs
ZSBleHBsYW5hdGlvbiwgb3IgYXQgbGVhc3QgYW4gaW50cm9kdWN0aW9uLiAgSSBqdXN0IHB1dCBt
eSBjaGFuZ2VzIGluIHJlZCBmb3IgdHJhY2tpbmcuXHBhcg0KXHBhcg0KICAgICAgICBUaGUgZmly
c3QgdGhpbmcgaXQgbmVlZHMgaXMgYSBzaW1wbGUgb3ZlcnZpZXcuICBCcmllZmx5LCB3aGVyZSBk
byB5b3UgZmluZCBvdXQgaG93IHRvIGRvIHdoYXQgbmVlZHMgdG8gYmUgZG9uZT8gIEVhY2ggbW9k
dWxlLCBvciBlYWNoIGxpYnJhcnksIG9yIHdoYXRldmVyLCBzaG91bGQgaGF2ZSBhIGJyaWVmIGRl
c2NyaXB0aW9uIGluIHBsYWluIEVuZ2xpc2guICBNYWtlIHN1cmUgZWFjaCBtb2R1bGUgaXMgZGVz
Y3JpYmVkLiAgKEZvciBleGFtcGxlLCB0aGUgaGVscCBkb2N1bWVudCBkb2VzIG5vdCBoYXZlIGEg
c2luZ2xlIHdvcmQgYWJvdXQgc2VyaWFsIGNvbW11bmljYXRpb25zLiAgSSBoYWQgYWJzb2x1dGVs
eSBubyBpZGVhIHRoYXQgQmxhY2tCb3ggaGFkIGEgbmljZSBjb21tdW5pY2F0aW9ucyBwYWNrYWdl
LikgIE1ha2Ugc3VyZSB0aXRsZXMgYW5kIGdyb3VwaW5ncyBvZiBtb2R1bGVzIChzdWJzeXN0ZW1z
KSBhcmUgY29uc2lzdGVudCBhbmQgY2xlYXIgdGhyb3VnaG91dC4gIChGb3IgZXhhbXBsZSwgdGhl
IFJvYWRtYXAgdGFsa3MgYWJvdXQgQ29tbWFuZHMgYW5kIFZpZXdzLCBhbmQgbm90IG11Y2ggZWxz
ZS4gIFdoZXJlIGluIHRoZSByZXN0IG9mIHRoZSBtYW51YWwgZG8gSSBmaW5kIG91dCBhYm91dCBj
b21tYW5kcyBhbmQgdmlld3M/ICBJbmZvcm1hdGlvbiBzZWVtcyB0byBiZSBzY2F0dGVyZWQgdGhy
b3VnaG91dC4pICBTb21lIG9mIHRoZSBkZXZlbG9wbWVudCBzeXN0ZW0gc2VlbXMgdG8gYmUgaW4g
VXNlciBNYW51YWxzIGluc3RlYWQgb2YgRGV2ZWxvcGVyIE1hbnVhbHMuXHBhcg0KXHBhcg0KICAg
ICAgICBFYWNoIG1vZHVsZSBvciBzdWJzeXN0ZW0gYWxzbyBuZWVkcyBhIHNpbXBsZSBpbnRyb2R1
Y3Rpb24gdGhhdCB0ZWxscyB3aGF0IHRoaW5ncyBkbyBhbmQgd2hlcmUgdG8gZmluZCB0aGluZ3Mu
ICBTb21ld2hlcmUgdGhlcmUgbmVlZHMgdG8gYmUgYSBkZXNjcmlwdGlvbiBvZiB0aGUgbWVudSBp
dGVtcy4gIFRoZSBleGFtcGxlcyBhcmUgZ29vZCwgYnV0IHRoZXkgYXJlIGFsbCB0aHJvd24gdG9n
ZXRoZXIuICBUaGV5IG5lZWQgdG8gYmUgcmVsb2NhdGVkIHRvIHRoZSBhcHByb3ByaWF0ZSBtb2R1
bGVzLlxwYXINClxwYXINCiAgICAgICAgVGhlcmUgbmVlZHMgdG8gYmUgYSBzaW1wbGUsIHByb21p
bmVudCwgYW5kIHVuaWZpZWQgZGVzY3JpcHRpb24gb2YgSS9PLiAgQXMgYSBtaW5pbXVtLCB0aGVy
ZSBuZWVkcyB0byBiZSBhIHNlY3Rpb24gb24gd29ya2luZyB3aXRoIGZvcmVpZ24gZmlsZXMsIGJl
Y2F1c2UgdGhhdCBpcyB3aGF0IHRoZSByZXN0IG9mIHRoZSB3b3JsZCB1c2VzLiAgVGhlcmUgbmVl
ZHMgdG8gYmUgYSBzaW1wbGUgZGVzY3JpcHRpb24gb2YgSS9PIGZyb20gZmlsZXMsIGtleWJvYXJk
K21vbml0b3IsIGFuZCBtb3VzZS5ccGFyDQpccGFyDQogICAgICAgIFNvIGhvdyBiaWcgYSBqb2Ig
aXMgdGhpcz8gIFdoYXQgZG8geW91IHRoaW5rP1xwYXINClxwYXINClJleCBDb3V0dXJlXHBhcg0K
UmV4IENvdXR1cmUsIFBoLiBELlxwYXINCkRlcHQuIG9mIEVhcnRoIGFuZCBQbGFuZXRhcnkgU2Np
ZW5jZXNccGFyDQpDYW1wdXMgQm94IDExNjlccGFyDQpXYXNoaW5ndG9uIFVuaXZlcnNpdHkgaW4g
U3QuIExvdWlzXHBhcg0KMSBCcm9va2luZ3MgRHIuXHBhcg0KU3QuIExvdWlzIE1PIDYzMTMwXHBh
cg0KXHBhcg0KVm9pY2U6ICAoMzE0KSA5MzUtNDE5NFxwYXINCkZheDogICgzMTQpIDkzNS03MzYx
XHBhcg0KcmV4QGxldmVlLnd1c3RsLmVkdVxwYXINClxwYXINCi0tLSBCbGFja0JveFxwYXINCi0t
LSBzZW5kIHN1YmplY3QgSEVMUCBvciBVTlNVQlNDUklCRSB0byBibGFja2JveEBvYmVyb24uY2h9
fQAyLjY0ICgyMDA0
----boundary-LibPST-iamunique-1619990833_-_---
Received on Fri Mar 18 2005 - 16:40:07 UTC