- 'blink a led'?

From: [at]} <Bob>
Date: Tue, 22 Feb 2005 09:31:20 +0000

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

Hi Douglas,

Tuesday, February 22, 2005, 4:22:03 AM, you wrote:

> Rex,
> I totally agree with you concerning the documentation and locating those
> elements that seem basic.

> Several years ago I gave a quicky solution on how to open a "file" to a
> new comer and was chastized by a member of the BlackBox crew for not
> giving a full general formulation. My response was that the new comer
> had to be able to walk before he could fly.

> I use a very small fraction of the BlackBox framework and still am able
> to get alot accomplished. There is always a trade-off between
> generality and specificity. I believe the BB documentation is just a
> little too general.

The main problem, in my opinion, is that the documentation is written
from the inside out.

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.

A 'quicky' solution is exactly what people need when they are trying
to solve a problem right now. Think of it as 'just in time'
documentation. Having to understand the entire module hierarchy before
you can move on is not realistic and is a great hindrance to
productivity. The 'just in time' documentation should, of course, allow
you to explore more deeply when you want to.

The BB documentation seems to consist almost entirely of concept
information, with very little 'How to' information. Of course, the
concept information is necessary, but it is not sufficient, and ought
to be presented in the context of the problems it solves.

On top of that, it is rather monolithic, like software before
structured programming.

The 'how to' information that is there is mostly lost in the thicket
of concept information, instead of the types being clearly
separated.

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

Unfortunately none of us has the time to do anything about it (apart
from grumble!).

-- 
Regards,
 Bob
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy----boundary-LibPST-iamunique-2040848174_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEhpIERvdWdsYXMsXHBhcg0KXHBhcg0KVHVlc2Rh
eSwgRmVicnVhcnkgMjIsIDIwMDUsIDQ6MjI6MDMgQU0sIHlvdSB3cm90ZTpccGFyDQpccGFyDQo+
IFJleCxccGFyDQo+IEkgdG90YWxseSBhZ3JlZSB3aXRoIHlvdSBjb25jZXJuaW5nIHRoZSBkb2N1
bWVudGF0aW9uIGFuZCBsb2NhdGluZyB0aG9zZVxwYXINCj4gZWxlbWVudHMgdGhhdCBzZWVtIGJh
c2ljLlxwYXINClxwYXINCj4gU2V2ZXJhbCB5ZWFycyBhZ28gSSBnYXZlIGEgcXVpY2t5IHNvbHV0
aW9uIG9uIGhvdyB0byBvcGVuIGEgImZpbGUiIHRvIGFccGFyDQo+IG5ldyBjb21lciBhbmQgd2Fz
IGNoYXN0aXplZCBieSBhIG1lbWJlciBvZiB0aGUgQmxhY2tCb3ggY3JldyBmb3Igbm90XHBhcg0K
PiBnaXZpbmcgYSBmdWxsIGdlbmVyYWwgZm9ybXVsYXRpb24uICBNeSByZXNwb25zZSB3YXMgdGhh
dCB0aGUgbmV3IGNvbWVyXHBhcg0KPiBoYWQgdG8gYmUgYWJsZSB0byB3YWxrIGJlZm9yZSBoZSBj
b3VsZCBmbHkuXHBhcg0KXHBhcg0KPiBJIHVzZSBhIHZlcnkgc21hbGwgZnJhY3Rpb24gb2YgdGhl
IEJsYWNrQm94IGZyYW1ld29yayBhbmQgc3RpbGwgYW0gYWJsZVxwYXINCj4gdG8gZ2V0IGFsb3Qg
YWNjb21wbGlzaGVkLiAgVGhlcmUgaXMgYWx3YXlzIGEgdHJhZGUtb2ZmIGJldHdlZW4gXHBhcg0K
PiBnZW5lcmFsaXR5IGFuZCBzcGVjaWZpY2l0eS4gIEkgYmVsaWV2ZSB0aGUgQkIgZG9jdW1lbnRh
dGlvbiBpcyBqdXN0IGFccGFyDQo+IGxpdHRsZSB0b28gZ2VuZXJhbC5ccGFyDQpccGFyDQpUaGUg
bWFpbiBwcm9ibGVtLCBpbiBteSBvcGluaW9uLCBpcyB0aGF0IHRoZSBkb2N1bWVudGF0aW9uIGlz
IHdyaXR0ZW5ccGFyDQpmcm9tIHRoZSBpbnNpZGUgb3V0LlxwYXINClxwYXINCkN1cnJlbnQgdGhp
bmtpbmcgYW1vbmcgdGVjaG5pY2FsIHdyaXRlcnMgc2VlbXMgdG8gYmUgdGhhdCB0aGVccGFyDQpk
b2N1bWVudGF0aW9uIHNob3VsZCBiZSBwcmVzZW50ZWQgZnJvbSB0aGUgcmVhZGVyJ3MgcG9pbnQg
b2Ygdmlldy5ccGFyDQpNb3N0IG9mIHRoZSBCQiBkb2N1bWVudGF0aW9uIGlzIHByZXNlbnRlZCBm
cm9tIHRoZSBkZXZlbG9wZXIncyBwb2ludFxwYXINCm9mIHZpZXcuXHBhcg0KXHBhcg0KQSAncXVp
Y2t5JyBzb2x1dGlvbiBpcyBleGFjdGx5IHdoYXQgcGVvcGxlIG5lZWQgd2hlbiB0aGV5IGFyZSB0
cnlpbmdccGFyDQp0byBzb2x2ZSBhIHByb2JsZW0gcmlnaHQgbm93LiBUaGluayBvZiBpdCBhcyAn
anVzdCBpbiB0aW1lJ1xwYXINCmRvY3VtZW50YXRpb24uIEhhdmluZyB0byB1bmRlcnN0YW5kIHRo
ZSBlbnRpcmUgbW9kdWxlIGhpZXJhcmNoeSBiZWZvcmVccGFyDQp5b3UgY2FuIG1vdmUgb24gaXMg
bm90IHJlYWxpc3RpYyBhbmQgaXMgYSBncmVhdCBoaW5kcmFuY2UgdG9ccGFyDQpwcm9kdWN0aXZp
dHkuIFRoZSAnanVzdCBpbiB0aW1lJyBkb2N1bWVudGF0aW9uIHNob3VsZCwgb2YgY291cnNlLCBh
bGxvd1xwYXINCnlvdSB0byBleHBsb3JlIG1vcmUgZGVlcGx5IHdoZW4geW91IHdhbnQgdG8uXHBh
cg0KXHBhcg0KVGhlIEJCIGRvY3VtZW50YXRpb24gc2VlbXMgdG8gY29uc2lzdCBhbG1vc3QgZW50
aXJlbHkgb2YgY29uY2VwdFxwYXINCmluZm9ybWF0aW9uLCB3aXRoIHZlcnkgbGl0dGxlICdIb3cg
dG8nIGluZm9ybWF0aW9uLiBPZiBjb3Vyc2UsIHRoZVxwYXINCmNvbmNlcHQgaW5mb3JtYXRpb24g
aXMgbmVjZXNzYXJ5LCBidXQgaXQgaXMgbm90IHN1ZmZpY2llbnQsIGFuZCBvdWdodFxwYXINCnRv
IGJlIHByZXNlbnRlZCBpbiB0aGUgY29udGV4dCBvZiB0aGUgcHJvYmxlbXMgaXQgc29sdmVzLlxw
YXINClxwYXINCk9uIHRvcCBvZiB0aGF0LCBpdCBpcyByYXRoZXIgbW9ub2xpdGhpYywgbGlrZSBz
b2Z0d2FyZSBiZWZvcmVccGFyDQpzdHJ1Y3R1cmVkIHByb2dyYW1taW5nLlxwYXINClxwYXINClRo
ZSAnaG93IHRvJyBpbmZvcm1hdGlvbiB0aGF0IGlzIHRoZXJlIGlzIG1vc3RseSBsb3N0IGluIHRo
ZSB0aGlja2V0XHBhcg0Kb2YgY29uY2VwdCBpbmZvcm1hdGlvbiwgaW5zdGVhZCBvZiB0aGUgdHlw
ZXMgYmVpbmcgY2xlYXJseVxwYXINCnNlcGFyYXRlZC5ccGFyDQpccGFyDQpUaGlzIG1ha2VzIEJs
YWNrQm94LCB3aGljaCBpcyB0aGUgYmVzdCBhbmQgbW9zdCBlbmpveWFibGUgc29mdHdhcmUgSVxw
YXINCmhhdmUgZXZlciB3b3JrZWQgd2l0aCwgc2VlbSBmYXIgbW9yZSBkaWZmaWN1bHQgdGhhbiBp
dCByZWFsbHkgaXMuXHBhcg0KXHBhcg0KVW5mb3J0dW5hdGVseSBub25lIG9mIHVzIGhhcyB0aGUg
dGltZSB0byBkbyBhbnl0aGluZyBhYm91dCBpdCAoYXBhcnRccGFyDQpmcm9tIGdydW1ibGUhKS5c
cGFyDQpccGFyDQotLSBccGFyDQpSZWdhcmRzLFxwYXINCiBCb2JccGFyDQpccGFyDQotLS0gQmxh
Y2tCb3hccGFyDQotLS0gc2VuZCBzdWJqZWN0IEhFTFAgb3IgVU5TVUJTQ1JJQkUgdG8gYmxhY2ti
b3hAb2Jlcm9uLmNofX0AE2G+oxAZnW4A3Q==
----boundary-LibPST-iamunique-2040848174_-_---

Received on Tue Feb 22 2005 - 10:31:20 UTC