- BlackBox documentation: user vs. developer

From: [at]} <skulski{>
Date: Tue, 22 Feb 2005 13:22:10 -0500 (EST)

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

"Bob Walkden" <bob{([at]})nowhere.xy

> Current thinking among technical writers seems to be that the
> documentation should be presented from the reader's point of view.
> Most of the BB documentation is presented from the developer's point
> of view.

This discussion is no longer about blinking an LED. We had discussed the
BB docu more than once and nobody seems to like it. I think Bob has hit
the nail in the head. The BB documentation is presented from the
developer's point of view. I tend to think of the core BlackBox, i.e., the
one downloadable from the ouS website, as a developer's framework. So the
documentation is adequate. However, every new user seems to stumble upon
the same snag, that is "how in the Earth do I use this thing"? Not every
new user will be willing to disentangle the developer's thicket. I have
seen it more than once.

Think of it this way. In the hardware world, the BB would be roughly
equivalent to a HW standard such as a Versa Module Europe (VME) standard.
I am reading through a VMEbus handbook by Wade Peterson right now. It
describes all the electrical connections, voltage levels, and protocols of
the VMEbus. It is a developer's handbook. It describes how the VME
framework works internally. There is not much application-level info in
the Peterson's book. If I did not know already what VME can do, I would
not learn from that book. It does not tell me what a VME module should be
doing, what application it can possibly address, or why I should build a
VME module rather than some other kind of module.

There are some examples in the Peterson's book of some simple VME modules,
but they are just illustrations. If I formed my judgement about VME based
on those examples, I would easily conclude that VME is not powerful and it
lacks interesting applications. Neither of which would be true.

If I do not blame Peterson for writing a meticulous description of all 320
VME pins, then I should not blame OuS for providing a similarly boring
reference for a few hundred BB API functions. The references are not to be
enjoyed. I have not purchased Peterson's book to learn if VMEbus is
useful. I know the answer from some other source. Same with BlackBox. If I
already know it is useful, then finding information is not that hard, once
I assume the answer to my questions must be there somewhere. I just use my
intelligence. If the answer does not pop up right away, I try again until
I find it. Or I e-mail the user's group and someone will help me.

> This makes BlackBox, which is the best and most enjoyable software I
> have ever worked with, seem far more difficult than it really is.

 A good tutorial will help, so let's try to put one together.

W.

--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy



----boundary-LibPST-iamunique-1102345774_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"

e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwICJCb2IgV2Fsa2RlbiIgPGJvYkB3ZWItb3B0aW9u
cy5jb20+IHdyb3RlXHBhcg0KXHBhcg0KPiBDdXJyZW50IHRoaW5raW5nIGFtb25nIHRlY2huaWNh
bCB3cml0ZXJzIHNlZW1zIHRvIGJlIHRoYXQgdGhlXHBhcg0KPiBkb2N1bWVudGF0aW9uIHNob3Vs
ZCBiZSBwcmVzZW50ZWQgZnJvbSB0aGUgcmVhZGVyJ3MgcG9pbnQgb2Ygdmlldy5ccGFyDQo+IE1v
c3Qgb2YgdGhlIEJCIGRvY3VtZW50YXRpb24gaXMgcHJlc2VudGVkIGZyb20gdGhlIGRldmVsb3Bl
cidzIHBvaW50XHBhcg0KPiBvZiB2aWV3LlxwYXINClxwYXINClRoaXMgZGlzY3Vzc2lvbiBpcyBu
byBsb25nZXIgYWJvdXQgYmxpbmtpbmcgYW4gTEVELiBXZSBoYWQgZGlzY3Vzc2VkIHRoZVxwYXIN
CkJCIGRvY3UgbW9yZSB0aGFuIG9uY2UgYW5kIG5vYm9keSBzZWVtcyB0byBsaWtlIGl0LiBJIHRo
aW5rIEJvYiBoYXMgaGl0XHBhcg0KdGhlIG5haWwgaW4gdGhlIGhlYWQuIFRoZSBCQiBkb2N1bWVu
dGF0aW9uIGlzIHByZXNlbnRlZCBmcm9tIHRoZVxwYXINCmRldmVsb3BlcidzIHBvaW50IG9mIHZp
ZXcuIEkgdGVuZCB0byB0aGluayBvZiB0aGUgY29yZSBCbGFja0JveCwgaS5lLiwgdGhlXHBhcg0K
b25lIGRvd25sb2FkYWJsZSBmcm9tIHRoZSBvdVMgd2Vic2l0ZSwgYXMgYSBkZXZlbG9wZXIncyBm
cmFtZXdvcmsuIFNvIHRoZVxwYXINCmRvY3VtZW50YXRpb24gaXMgYWRlcXVhdGUuIEhvd2V2ZXIs
IGV2ZXJ5IG5ldyB1c2VyIHNlZW1zIHRvIHN0dW1ibGUgdXBvblxwYXINCnRoZSBzYW1lIHNuYWcs
IHRoYXQgaXMgImhvdyBpbiB0aGUgRWFydGggZG8gSSB1c2UgdGhpcyB0aGluZyI/IE5vdCBldmVy
eVxwYXINCm5ldyB1c2VyIHdpbGwgYmUgd2lsbGluZyB0byBkaXNlbnRhbmdsZSB0aGUgZGV2ZWxv
cGVyJ3MgdGhpY2tldC4gSSBoYXZlXHBhcg0Kc2VlbiBpdCBtb3JlIHRoYW4gb25jZS5ccGFyDQpc
cGFyDQpUaGluayBvZiBpdCB0aGlzIHdheS4gSW4gdGhlIGhhcmR3YXJlIHdvcmxkLCB0aGUgQkIg
d291bGQgYmUgcm91Z2hseVxwYXINCmVxdWl2YWxlbnQgdG8gYSBIVyBzdGFuZGFyZCBzdWNoIGFz
IGEgVmVyc2EgTW9kdWxlIEV1cm9wZSAoVk1FKSBzdGFuZGFyZC5ccGFyDQpJIGFtIHJlYWRpbmcg
dGhyb3VnaCBhIFZNRWJ1cyBoYW5kYm9vayBieSBXYWRlIFBldGVyc29uIHJpZ2h0IG5vdy4gSXRc
cGFyDQpkZXNjcmliZXMgYWxsIHRoZSBlbGVjdHJpY2FsIGNvbm5lY3Rpb25zLCB2b2x0YWdlIGxl
dmVscywgYW5kIHByb3RvY29scyBvZlxwYXINCnRoZSBWTUVidXMuIEl0IGlzIGEgZGV2ZWxvcGVy
J3MgaGFuZGJvb2suIEl0IGRlc2NyaWJlcyBob3cgdGhlIFZNRVxwYXINCmZyYW1ld29yayB3b3Jr
cyBpbnRlcm5hbGx5LiBUaGVyZSBpcyBub3QgbXVjaCBhcHBsaWNhdGlvbi1sZXZlbCBpbmZvIGlu
XHBhcg0KdGhlIFBldGVyc29uJ3MgYm9vay4gSWYgSSBkaWQgbm90IGtub3cgYWxyZWFkeSB3aGF0
IFZNRSBjYW4gZG8sIEkgd291bGRccGFyDQpub3QgbGVhcm4gZnJvbSB0aGF0IGJvb2suIEl0IGRv
ZXMgbm90IHRlbGwgbWUgd2hhdCBhIFZNRSBtb2R1bGUgc2hvdWxkIGJlXHBhcg0KZG9pbmcsIHdo
YXQgYXBwbGljYXRpb24gaXQgY2FuIHBvc3NpYmx5IGFkZHJlc3MsIG9yIHdoeSBJIHNob3VsZCBi
dWlsZCBhXHBhcg0KVk1FIG1vZHVsZSByYXRoZXIgdGhhbiBzb21lIG90aGVyIGtpbmQgb2YgbW9k
dWxlLlxwYXINClxwYXINClRoZXJlIGFyZSBzb21lIGV4YW1wbGVzIGluIHRoZSBQZXRlcnNvbidz
IGJvb2sgb2Ygc29tZSBzaW1wbGUgVk1FIG1vZHVsZXMsXHBhcg0KYnV0IHRoZXkgYXJlIGp1c3Qg
aWxsdXN0cmF0aW9ucy4gSWYgSSBmb3JtZWQgbXkganVkZ2VtZW50IGFib3V0IFZNRSBiYXNlZFxw
YXINCm9uIHRob3NlIGV4YW1wbGVzLCBJIHdvdWxkIGVhc2lseSBjb25jbHVkZSB0aGF0IFZNRSBp
cyBub3QgcG93ZXJmdWwgYW5kIGl0XHBhcg0KbGFja3MgaW50ZXJlc3RpbmcgYXBwbGljYXRpb25z
LiBOZWl0aGVyIG9mIHdoaWNoIHdvdWxkIGJlIHRydWUuXHBhcg0KXHBhcg0KSWYgSSBkbyBub3Qg
YmxhbWUgUGV0ZXJzb24gZm9yIHdyaXRpbmcgYSBtZXRpY3Vsb3VzIGRlc2NyaXB0aW9uIG9mIGFs
bCAzMjBccGFyDQpWTUUgcGlucywgdGhlbiBJIHNob3VsZCBub3QgYmxhbWUgT3VTIGZvciBwcm92
aWRpbmcgYSBzaW1pbGFybHkgYm9yaW5nXHBhcg0KcmVmZXJlbmNlIGZvciBhIGZldyBodW5kcmVk
IEJCIEFQSSBmdW5jdGlvbnMuIFRoZSByZWZlcmVuY2VzIGFyZSBub3QgdG8gYmVccGFyDQplbmpv
eWVkLiBJIGhhdmUgbm90IHB1cmNoYXNlZCBQZXRlcnNvbidzIGJvb2sgdG8gbGVhcm4gaWYgVk1F
YnVzIGlzXHBhcg0KdXNlZnVsLiBJIGtub3cgdGhlIGFuc3dlciBmcm9tIHNvbWUgb3RoZXIgc291
cmNlLiBTYW1lIHdpdGggQmxhY2tCb3guIElmIElccGFyDQphbHJlYWR5IGtub3cgaXQgaXMgdXNl
ZnVsLCB0aGVuIGZpbmRpbmcgaW5mb3JtYXRpb24gaXMgbm90IHRoYXQgaGFyZCwgb25jZVxwYXIN
CkkgYXNzdW1lIHRoZSBhbnN3ZXIgdG8gbXkgcXVlc3Rpb25zIG11c3QgYmUgdGhlcmUgc29tZXdo
ZXJlLiBJIGp1c3QgdXNlIG15XHBhcg0KaW50ZWxsaWdlbmNlLiBJZiB0aGUgYW5zd2VyIGRvZXMg
bm90IHBvcCB1cCByaWdodCBhd2F5LCBJIHRyeSBhZ2FpbiB1bnRpbFxwYXINCkkgZmluZCBpdC4g
T3IgSSBlLW1haWwgdGhlIHVzZXIncyBncm91cCBhbmQgc29tZW9uZSB3aWxsIGhlbHAgbWUuXHBh
cg0KXHBhcg0KPiBUaGlzIG1ha2VzIEJsYWNrQm94LCB3aGljaCBpcyB0aGUgYmVzdCBhbmQgbW9z
dCBlbmpveWFibGUgc29mdHdhcmUgSVxwYXINCj4gaGF2ZSBldmVyIHdvcmtlZCB3aXRoLCBzZWVt
IGZhciBtb3JlIGRpZmZpY3VsdCB0aGFuIGl0IHJlYWxseSBpcy5ccGFyDQpccGFyDQogQSBnb29k
IHR1dG9yaWFsIHdpbGwgaGVscCwgc28gbGV0J3MgdHJ5IHRvIHB1dCBvbmUgdG9nZXRoZXIuXHBh
cg0KXHBhcg0KVy5ccGFyDQpccGFyDQotLS0gQmxhY2tCb3hccGFyDQotLS0gc2VuZCBzdWJqZWN0
IEhFTFAgb3IgVU5TVUJTQ1JJQkUgdG8gYmxhY2tib3hAb2Jlcm9uLmNofX0AZSAoUG9zdGZpeA=


----boundary-LibPST-iamunique-1102345774_-_---
Received on Tue Feb 22 2005 - 19:22:10 UTC