----boundary-LibPST-iamunique-1824415734_-_-
Content-type: text/plain
Rex,
I agree, but first there is a meta-level that needs to be worked out:
Who creates the documentation, how is the documentation coordinated
between the creators, and where does the documentation reside?
-Doug
Rex Couture wrote:
> 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>
>
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy
----boundary-LibPST-iamunique-1824415734_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIFJleCxccGFyDQpccGFyDQpJIGFncmVlLCBidXQg
Zmlyc3QgdGhlcmUgaXMgYSBtZXRhLWxldmVsIHRoYXQgbmVlZHMgdG8gYmUgd29ya2VkIG91dDog
XHBhcg0KV2hvIGNyZWF0ZXMgdGhlIGRvY3VtZW50YXRpb24sIGhvdyBpcyB0aGUgZG9jdW1lbnRh
dGlvbiBjb29yZGluYXRlZCBccGFyDQpiZXR3ZWVuIHRoZSBjcmVhdG9ycywgYW5kIHdoZXJlIGRv
ZXMgdGhlIGRvY3VtZW50YXRpb24gcmVzaWRlP1xwYXINClxwYXINCi1Eb3VnXHBhcg0KXHBhcg0K
UmV4IENvdXR1cmUgd3JvdGU6XHBhcg0KPiAgICAgICAgICBUaGUgbGl0dGxlIGRvY3VtZW50YXRp
b24gcHJvamVjdCBzZWVtcyB0byBiZSBhYm91dCBhcyBkb3JtYW50IGFzIEkgaGF2ZS4gIEkgZ3Vl
c3MgZXZlcnlvbmUgaGFzIGJlZW4gYXMgYnVzeSBhcyBJIGhhdmUgYmVlbi5ccGFyDQo+IFxwYXIN
Cj4gICAgICAgICBJIHRoaW5rIFdvanRlayBTa3Vsc2tpIHN0YXRlZCB0aGUgcHJvYmxlbSBleGFj
dGx5IHdoZW4gaGUgc2FpZCwgZXNzZW50aWFsbHksIHRoYXQgdGhlIEJCIGRvY3VtZW50YXRpb24g
d2FzIHdyaXR0ZW4gZnJvbSB0aGUgaW5zaWRlIG91dCwgbGlrZSB0aGUgdW5yZWFkYWJsZSBkb2N1
bWVudGF0aW9uIGZvciBhIGNvbXB1dGVyIGNoaXAuICBJIHJlYWxseSB0aGluayBkb2N1bWVudGF0
aW9uIGlzIHRoZSBzaW5nbGUgYmlnZ2VzdCBwcm9ibGVtIHdpdGggYWRvcHRhdGlvbiBvZiBhbnkg
T2Jlcm9uIGxhbmd1YWdlLiAgVGhlcmUgYXJlIG90aGVyIHByb2JsZW1zLCBsaWtlIGJlaW5nIGVt
YmVkZGVkIGluIGEgZnJhbWV3b3JrLiAgQnV0IHRoZSBmcmFtZXdvcmsgaXMgc3VwcG9zZWQgdG8g
YmUgdXNlZnVsLiAgQWdhaW4sIHRoZSBwcm9ibGVtIGlzIGRvY3VtZW50YXRpb24uICBXaHkgaXMg
aXQgdXNlZnVsPyAgUGVvcGxlIG5lZWQgdG8gYmUgc2hvd24gaW4gYSBzaW1wbGUsIGNvbmNpc2Us
IHdheS4gIFNpbmNlIEJsYWNrQm94IGlzIGEgYml0IHVuY29udmVudGlvbmFsLCBhbmQgdXNlcyBz
b21lIHVuZXhwZWN0ZWQgdGVybWlub2xvZ3kgYW5kIGNvbmNlcHRzLCBJIHRoaW5rIHRoZSBkb2N1
bWVudGF0aW9uIGhhcyB0byBiZSBhIGxpdHRsZSBiZXR0ZXIgdGhhbiB0aGUgYXZlcmFnZSBsYW5n
dWFnZSBtYW51YWwuICBUdXRvcmlhbHMgYXJlIGV4Y2VsbGVudCwgYnV0IHRoZXJlIG5lZWRzIHRv
IGJlIGEgbWFudWFsIHRvby5ccGFyDQo+IFxwYXINCj4gICAgICAgICBGb3J0dW5hdGVseSwgSSBk
b24ndCB0aGluayBpdCBsb29rcyBvdmVyd2hlbG1pbmcuICBGaXJzdCBvZiBhbGwsIHRoZSBjdXJy
ZW50IGRvY3VtZW50YXRpb24gaXMgc28gZWFzaWx5IGVkaXRlZC4gIEkgZmluZCB0aGF0IGV2ZW4g
YXMgSSByZWFkIHRocm91Z2ggdGhlIGRvY3VtZW50YXRpb24sIHdoZW4gSSBmaW5hbGx5IGRlY2lw
aGVyIHdoYXQgdGhleSBhcmUgdGFsa2luZyBhYm91dCwgaXQgaXMgdmVyeSBlYXN5IHRvIGFkZCBh
IHNpbXBsZSBleHBsYW5hdGlvbiwgb3IgYXQgbGVhc3QgYW4gaW50cm9kdWN0aW9uLiAgSSBqdXN0
IHB1dCBteSBjaGFuZ2VzIGluIHJlZCBmb3IgdHJhY2tpbmcuXHBhcg0KPiBccGFyDQo+ICAgICAg
ICAgVGhlIGZpcnN0IHRoaW5nIGl0IG5lZWRzIGlzIGEgc2ltcGxlIG92ZXJ2aWV3LiAgQnJpZWZs
eSwgd2hlcmUgZG8geW91IGZpbmQgb3V0IGhvdyB0byBkbyB3aGF0IG5lZWRzIHRvIGJlIGRvbmU/
ICBFYWNoIG1vZHVsZSwgb3IgZWFjaCBsaWJyYXJ5LCBvciB3aGF0ZXZlciwgc2hvdWxkIGhhdmUg
YSBicmllZiBkZXNjcmlwdGlvbiBpbiBwbGFpbiBFbmdsaXNoLiAgTWFrZSBzdXJlIGVhY2ggbW9k
dWxlIGlzIGRlc2NyaWJlZC4gIChGb3IgZXhhbXBsZSwgdGhlIGhlbHAgZG9jdW1lbnQgZG9lcyBu
b3QgaGF2ZSBhIHNpbmdsZSB3b3JkIGFib3V0IHNlcmlhbCBjb21tdW5pY2F0aW9ucy4gIEkgaGFk
IGFic29sdXRlbHkgbm8gaWRlYSB0aGF0IEJsYWNrQm94IGhhZCBhIG5pY2UgY29tbXVuaWNhdGlv
bnMgcGFja2FnZS4pICBNYWtlIHN1cmUgdGl0bGVzIGFuZCBncm91cGluZ3Mgb2YgbW9kdWxlcyAo
c3Vic3lzdGVtcykgYXJlIGNvbnNpc3RlbnQgYW5kIGNsZWFyIHRocm91Z2hvdXQuICAoRm9yIGV4
YW1wbGUsIHRoZSBSb2FkbWFwIHRhbGtzIGFib3V0IENvbW1hbmRzIGFuZCBWaWV3cywgYW5kIG5v
dCBtdWNoIGVsc2UuICBXaGVyZSBpbiB0aGUgcmVzdCBvZiB0aGUgbWFudWFsIGRvIEkgZmluZCBv
dXQgYWJvdXQgY29tbWFuZHMgYW5kIHZpZXdzPyAgSW5mb3JtYXRpb24gc2VlbXMgdG8gYmUgc2Nh
dHRlcmVkIHRocm91Z2hvdXQuKSAgU29tZSBvZiB0aGUgZGV2ZWxvcG1lbnQgc3lzdGVtIHNlZW1z
IHRvIGJlIGluIFVzZXIgTWFudWFscyBpbnN0ZWFkIG9mIERldmVsb3BlciBNYW51YWxzLlxwYXIN
Cj4gXHBhcg0KPiAgICAgICAgIEVhY2ggbW9kdWxlIG9yIHN1YnN5c3RlbSBhbHNvIG5lZWRzIGEg
c2ltcGxlIGludHJvZHVjdGlvbiB0aGF0IHRlbGxzIHdoYXQgdGhpbmdzIGRvIGFuZCB3aGVyZSB0
byBmaW5kIHRoaW5ncy4gIFNvbWV3aGVyZSB0aGVyZSBuZWVkcyB0byBiZSBhIGRlc2NyaXB0aW9u
IG9mIHRoZSBtZW51IGl0ZW1zLiAgVGhlIGV4YW1wbGVzIGFyZSBnb29kLCBidXQgdGhleSBhcmUg
YWxsIHRocm93biB0b2dldGhlci4gIFRoZXkgbmVlZCB0byBiZSByZWxvY2F0ZWQgdG8gdGhlIGFw
cHJvcHJpYXRlIG1vZHVsZXMuXHBhcg0KPiBccGFyDQo+ICAgICAgICAgVGhlcmUgbmVlZHMgdG8g
YmUgYSBzaW1wbGUsIHByb21pbmVudCwgYW5kIHVuaWZpZWQgZGVzY3JpcHRpb24gb2YgSS9PLiAg
QXMgYSBtaW5pbXVtLCB0aGVyZSBuZWVkcyB0byBiZSBhIHNlY3Rpb24gb24gd29ya2luZyB3aXRo
IGZvcmVpZ24gZmlsZXMsIGJlY2F1c2UgdGhhdCBpcyB3aGF0IHRoZSByZXN0IG9mIHRoZSB3b3Js
ZCB1c2VzLiAgVGhlcmUgbmVlZHMgdG8gYmUgYSBzaW1wbGUgZGVzY3JpcHRpb24gb2YgSS9PIGZy
b20gZmlsZXMsIGtleWJvYXJkK21vbml0b3IsIGFuZCBtb3VzZS5ccGFyDQo+IFxwYXINCj4gICAg
ICAgICBTbyBob3cgYmlnIGEgam9iIGlzIHRoaXM/ICBXaGF0IGRvIHlvdSB0aGluaz9ccGFyDQo+
IFxwYXINCj4gUmV4IENvdXR1cmVccGFyDQo+IFJleCBDb3V0dXJlLCBQaC4gRC5ccGFyDQo+IERl
cHQuIG9mIEVhcnRoIGFuZCBQbGFuZXRhcnkgU2NpZW5jZXNccGFyDQo+IENhbXB1cyBCb3ggMTE2
OVxwYXINCj4gV2FzaGluZ3RvbiBVbml2ZXJzaXR5IGluIFN0LiBMb3Vpc1xwYXINCj4gMSBCcm9v
a2luZ3MgRHIuXHBhcg0KPiBTdC4gTG91aXMgTU8gNjMxMzBccGFyDQo+IFxwYXINCj4gVm9pY2U6
ICAoMzE0KSA5MzUtNDE5NFxwYXINCj4gRmF4OiAgKDMxNCkgOTM1LTczNjFccGFyDQo+IHJleEBs
ZXZlZS53dXN0bC5lZHVccGFyDQo+IFxwYXINCj4gLS0tIEJsYWNrQm94XHBhcg0KPiAtLS0gc2Vu
ZCBzdWJqZWN0IEhFTFAgb3IgVU5TVUJTQ1JJQkUgdG8gYmxhY2tib3hAb2Jlcm9uLmNoXHBhcg0K
PiBccGFyDQo+IFxwYXINClxwYXINCi0tLSBCbGFja0JveFxwYXINCi0tLSBzZW5kIHN1YmplY3Qg
SEVMUCBvciBVTlNVQlNDUklCRSB0byBibGFja2JveEBvYmVyb24uY2hccGFyDQpccGFyDQp9
----boundary-LibPST-iamunique-1824415734_-_---
Received on Fri Mar 18 2005 - 18:12:45 UTC