- Tutorial or Documentation?

From: [at]} <Rex>
Date: Fri, 25 Mar 2005 15:06:37 -0600

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

        Whatever is decided on, I would like to encourage adoption of a few principles, at the risk of repeating some ideas.

1. Chapters (or sections) are nice. Each subject should be presented coherently, and not fragmented. The sequence of presentation is crucial. Hypertext can indeed be a jumble of fragmented information, with too many undefined terms that can only be deciphered by traversing a whole web of disjointed information.

        Books are great because they present a sequence, while preserving random access. Even though they lack cross links, I still find them preferable to on-line documentation because they are coherent and presented in the proper sequence. They have a definite beginning and a clearly organized table of contents. Hyperspace lacks sequence.

        There's nothing inherent about the printed medium vs. electronic medium that makes it superior. It's just the way it's used. As long as the material is tightly organized, on-line information is great -- cross-links and all.

2. Keep it simple. I don't want to bring out examples, but there are many places in the current documentation where you have to ask what in the world they are talking about. Be careful with the computerese. The industry as a whole is bad enough, but BB seems additionally to have its own vocabulary and concepts. I've been programming quite a bit for 20 years.

3. Organizational concepts should be kept familiar. For example, people know what a table of contents is.

4. Bob Walkden, when I said it needs to be better written than the average language manual because the material is unfamiliar, I did not mean that we need to rewrite the manual. I think that is quite good.

5. Inside BB or outside BB? Documentation inside has obvious advantages, and it's easy to start there. It really should be visible from the outside, however, in order to snag new users. Wojtek's PDF presentation caused my head to turn. Do I remember correctly that there is a nice package for writing HTML or (gasp) PDF?

6. Where? OMS servers + users' servers or computers preferable. I don't know anything at all about Wiki's, but the one I did see looked pretty ragged. On the other hand it sounds like a good idea. I strongly suggest, however, that write access be restricted to the group, and not open to the world.

7. Who? Doug Danforth has volunteered to lead the effort, and that makes him uniquely qualified, in my opinion. :-)

Rex Couture

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



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

e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwICAgICAgICAgV2hhdGV2ZXIgaXMgZGVjaWRlZCBv
biwgSSB3b3VsZCBsaWtlIHRvIGVuY291cmFnZSBhZG9wdGlvbiBvZiBhIGZldyBwcmluY2lwbGVz
LCBhdCB0aGUgcmlzayBvZiByZXBlYXRpbmcgc29tZSBpZGVhcy5ccGFyDQpccGFyDQoxLiBDaGFw
dGVycyAob3Igc2VjdGlvbnMpIGFyZSBuaWNlLiAgRWFjaCBzdWJqZWN0IHNob3VsZCBiZSBwcmVz
ZW50ZWQgY29oZXJlbnRseSwgYW5kIG5vdCBmcmFnbWVudGVkLiAgVGhlIHNlcXVlbmNlIG9mIHBy
ZXNlbnRhdGlvbiBpcyBjcnVjaWFsLiAgSHlwZXJ0ZXh0IGNhbiBpbmRlZWQgYmUgYSBqdW1ibGUg
b2YgZnJhZ21lbnRlZCBpbmZvcm1hdGlvbiwgd2l0aCB0b28gbWFueSB1bmRlZmluZWQgdGVybXMg
dGhhdCBjYW4gb25seSBiZSBkZWNpcGhlcmVkIGJ5IHRyYXZlcnNpbmcgYSB3aG9sZSB3ZWIgb2Yg
ZGlzam9pbnRlZCBpbmZvcm1hdGlvbi5ccGFyDQpccGFyDQogICAgICAgIEJvb2tzIGFyZSBncmVh
dCBiZWNhdXNlIHRoZXkgcHJlc2VudCBhIHNlcXVlbmNlLCB3aGlsZSBwcmVzZXJ2aW5nIHJhbmRv
bSBhY2Nlc3MuICBFdmVuIHRob3VnaCB0aGV5IGxhY2sgY3Jvc3MgbGlua3MsIEkgc3RpbGwgZmlu
ZCB0aGVtIHByZWZlcmFibGUgdG8gb24tbGluZSBkb2N1bWVudGF0aW9uIGJlY2F1c2UgdGhleSBh
cmUgY29oZXJlbnQgYW5kIHByZXNlbnRlZCBpbiB0aGUgcHJvcGVyIHNlcXVlbmNlLiAgVGhleSBo
YXZlIGEgZGVmaW5pdGUgYmVnaW5uaW5nIGFuZCBhIGNsZWFybHkgb3JnYW5pemVkIHRhYmxlIG9m
IGNvbnRlbnRzLiAgSHlwZXJzcGFjZSBsYWNrcyBzZXF1ZW5jZS5ccGFyDQpccGFyDQogICAgICAg
IFRoZXJlJ3Mgbm90aGluZyBpbmhlcmVudCBhYm91dCB0aGUgcHJpbnRlZCBtZWRpdW0gdnMuIGVs
ZWN0cm9uaWMgbWVkaXVtIHRoYXQgbWFrZXMgaXQgc3VwZXJpb3IuICBJdCdzIGp1c3QgdGhlIHdh
eSBpdCdzIHVzZWQuICBBcyBsb25nIGFzIHRoZSBtYXRlcmlhbCBpcyB0aWdodGx5IG9yZ2FuaXpl
ZCwgb24tbGluZSBpbmZvcm1hdGlvbiBpcyBncmVhdCAtLSBjcm9zcy1saW5rcyBhbmQgYWxsLlxw
YXINClxwYXINCjIuIEtlZXAgaXQgc2ltcGxlLiAgSSBkb24ndCB3YW50IHRvIGJyaW5nIG91dCBl
eGFtcGxlcywgYnV0IHRoZXJlIGFyZSBtYW55IHBsYWNlcyBpbiB0aGUgY3VycmVudCBkb2N1bWVu
dGF0aW9uIHdoZXJlIHlvdSBoYXZlIHRvIGFzayB3aGF0IGluIHRoZSB3b3JsZCB0aGV5IGFyZSB0
YWxraW5nIGFib3V0LiAgQmUgY2FyZWZ1bCB3aXRoIHRoZSBjb21wdXRlcmVzZS4gIFRoZSBpbmR1
c3RyeSBhcyBhIHdob2xlIGlzIGJhZCBlbm91Z2gsIGJ1dCBCQiBzZWVtcyBhZGRpdGlvbmFsbHkg
dG8gaGF2ZSBpdHMgb3duIHZvY2FidWxhcnkgYW5kIGNvbmNlcHRzLiAgSSd2ZSBiZWVuIHByb2dy
YW1taW5nIHF1aXRlIGEgYml0IGZvciAyMCB5ZWFycy5ccGFyDQpccGFyDQozLiBPcmdhbml6YXRp
b25hbCBjb25jZXB0cyBzaG91bGQgYmUga2VwdCBmYW1pbGlhci4gIEZvciBleGFtcGxlLCBwZW9w
bGUga25vdyB3aGF0IGEgdGFibGUgb2YgY29udGVudHMgaXMuXHBhcg0KXHBhcg0KNC4gQm9iIFdh
bGtkZW4sIHdoZW4gSSBzYWlkIGl0IG5lZWRzIHRvIGJlIGJldHRlciB3cml0dGVuIHRoYW4gdGhl
IGF2ZXJhZ2UgbGFuZ3VhZ2UgbWFudWFsIGJlY2F1c2UgdGhlIG1hdGVyaWFsIGlzIHVuZmFtaWxp
YXIsIEkgZGlkIG5vdCBtZWFuIHRoYXQgd2UgbmVlZCB0byByZXdyaXRlIHRoZSBtYW51YWwuICBJ
IHRoaW5rIHRoYXQgaXMgcXVpdGUgZ29vZC5ccGFyDQpccGFyDQo1LiBJbnNpZGUgQkIgb3Igb3V0
c2lkZSBCQj8gIERvY3VtZW50YXRpb24gaW5zaWRlIGhhcyBvYnZpb3VzIGFkdmFudGFnZXMsIGFu
ZCBpdCdzIGVhc3kgdG8gc3RhcnQgdGhlcmUuICBJdCByZWFsbHkgc2hvdWxkIGJlIHZpc2libGUg
ZnJvbSB0aGUgb3V0c2lkZSwgaG93ZXZlciwgaW4gb3JkZXIgdG8gc25hZyBuZXcgdXNlcnMuICBX
b2p0ZWsncyBQREYgcHJlc2VudGF0aW9uIGNhdXNlZCBteSBoZWFkIHRvIHR1cm4uICBEbyBJIHJl
bWVtYmVyIGNvcnJlY3RseSB0aGF0IHRoZXJlIGlzIGEgbmljZSBwYWNrYWdlIGZvciB3cml0aW5n
IEhUTUwgb3IgKGdhc3ApIFBERj9ccGFyDQpccGFyDQo2LiBXaGVyZT8gIE9NUyBzZXJ2ZXJzICsg
dXNlcnMnIHNlcnZlcnMgb3IgY29tcHV0ZXJzIHByZWZlcmFibGUuICBJIGRvbid0IGtub3cgYW55
dGhpbmcgYXQgYWxsIGFib3V0IFdpa2kncywgYnV0IHRoZSBvbmUgSSBkaWQgc2VlIGxvb2tlZCBw
cmV0dHkgcmFnZ2VkLiAgT24gdGhlIG90aGVyIGhhbmQgaXQgc291bmRzIGxpa2UgYSBnb29kIGlk
ZWEuICBJIHN0cm9uZ2x5IHN1Z2dlc3QsIGhvd2V2ZXIsIHRoYXQgd3JpdGUgYWNjZXNzIGJlIHJl
c3RyaWN0ZWQgdG8gdGhlIGdyb3VwLCBhbmQgbm90IG9wZW4gdG8gdGhlIHdvcmxkLlxwYXINClxw
YXINCjcuIFdobz8gIERvdWcgRGFuZm9ydGggaGFzIHZvbHVudGVlcmVkIHRvIGxlYWQgdGhlIGVm
Zm9ydCwgYW5kIHRoYXQgbWFrZXMgaGltIHVuaXF1ZWx5IHF1YWxpZmllZCwgaW4gbXkgb3Bpbmlv
bi4gIDotKVxwYXINClxwYXINClJleCBDb3V0dXJlXHBhcg0KXHBhcg0KLS0tIEJsYWNrQm94XHBh
cg0KLS0tIHNlbmQgc3ViamVjdCBIRUxQIG9yIFVOU1VCU0NSSUJFIHRvIGJsYWNrYm94QG9iZXJv
bi5jaH19ABNhNOMTYXhdIC0=


----boundary-LibPST-iamunique-2118275762_-_---
Received on Fri Mar 25 2005 - 22:06:37 UTC