- Tutorial or Documentation?

From: [at]} <Bob>
Date: Sat, 19 Mar 2005 12:12:27 +0000

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

Hi Rex,

Friday, March 18, 2005, 3:40:07 PM, you 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.

Yes. This is likely to be the biggest risk to a project such as this.

[...]
> 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.

I don't believe we need a language manual. The language is well
documented, in my opinion. I believe we need documentation which
tells people how to do certain desirable things using the BB
framework.

[...]

> The first thing it needs is a simple overview. Briefly,
> where do you find out how to do what needs to be done?

Maybe. But the zeroth thing it needs is an answer to your question
"What needs to be done?". When we have the answer we can start
explaining how to use the BB framework to do it.

Example: How do I use serial comms?

This is a task-centred approach. Contrast it with something called
"Using CommV24".

> Each module,
> or each library, or whatever, should have a brief description in
> plain English. Make sure each module is described. (For example,
[...]

This is reference information, which is essential, and exists in
abundance. The main thing missing, in my opinion, is the task-centred
information.

> 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?

It is a very big job. In fact, it is probably infinite. But if you
accept that such a job can never be finished, you can begin to define
an approach to it.

My view is that we should take it on in bite-sized chunks, and write
many small, independent topics rather than the single document that
somebody else has proposed. This is consistent with current thinking
in the world of technical writing, and is the approach favoured by the
major standards bodies.

IBM has put forward something called the Darwin Information Type
Architecture. The useful aspect of it, for these purposes, is that it
provides a method for classifying information, and for determining
what chunks of information to include with any information type, to
write small, consistent topics.

A similar approach is called Information Mapping, or Structured Writing,
but it is a proprietary method; information about it is quite difficult
to find without going on an expensive course.

Both of these are structured, bottom-up approaches, which fit very well
into a hypertext style of navigation.

Writing small topics makes it much easier to apply many different routes
through the documentation, tailored to specific needs, than the single
document approach.

If you have access to a good library or bookshop you can find more
about these techniques here: http://tinyurl.com/3we6g.

As we identify topics, the person who wants to write the topic 'books
it out', writes it, then publishes it whereever. When it needs to be
changed somebody else, or perhaps the original writer, can book it out
and make the change. As many people as wish to do so can then work on
as many topics as necessary without bottlenecks. This requires some
central point for listing topics and their status (new, booked,
finished, ...). Perhaps Wiki is a good way of doing this - but I don't
really know much about Wiki.

-- 
Regards,
 Bob
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy----boundary-LibPST-iamunique-397147145_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEhpIFJleCxccGFyDQpccGFyDQpGcmlkYXksIE1h
cmNoIDE4LCAyMDA1LCAzOjQwOjA3IFBNLCB5b3Ugd3JvdGU6XHBhcg0KXHBhcg0KPiAgICAgICAg
ICBUaGUgbGl0dGxlIGRvY3VtZW50YXRpb24gcHJvamVjdCBzZWVtcyB0byBiZSBhYm91dCBhc1xw
YXINCj4gZG9ybWFudCBhcyBJIGhhdmUuICBJIGd1ZXNzIGV2ZXJ5b25lIGhhcyBiZWVuIGFzIGJ1
c3kgYXMgSSBoYXZlIGJlZW4uXHBhcg0KXHBhcg0KWWVzLiBUaGlzIGlzIGxpa2VseSB0byBiZSB0
aGUgYmlnZ2VzdCByaXNrIHRvIGEgcHJvamVjdCBzdWNoIGFzIHRoaXMuXHBhcg0KXHBhcg0KWy4u
Ll1ccGFyDQo+IGNvbmNlcHRzLCBJIHRoaW5rIHRoZSBkb2N1bWVudGF0aW9uIGhhcyB0byBiZSBh
IGxpdHRsZSBiZXR0ZXIgdGhhblxwYXINCj4gdGhlIGF2ZXJhZ2UgbGFuZ3VhZ2UgbWFudWFsLiAg
VHV0b3JpYWxzIGFyZSBleGNlbGxlbnQsIGJ1dCB0aGVyZVxwYXINCj4gbmVlZHMgdG8gYmUgYSBt
YW51YWwgdG9vLlxwYXINClxwYXINCkkgZG9uJ3QgYmVsaWV2ZSB3ZSBuZWVkIGEgbGFuZ3VhZ2Ug
bWFudWFsLiBUaGUgbGFuZ3VhZ2UgaXMgd2VsbFxwYXINCmRvY3VtZW50ZWQsIGluIG15IG9waW5p
b24uIEkgYmVsaWV2ZSB3ZSBuZWVkIGRvY3VtZW50YXRpb24gd2hpY2hccGFyDQp0ZWxscyBwZW9w
bGUgaG93IHRvIGRvIGNlcnRhaW4gZGVzaXJhYmxlIHRoaW5ncyB1c2luZyB0aGUgQkJccGFyDQpm
cmFtZXdvcmsuXHBhcg0KXHBhcg0KWy4uLl1ccGFyDQpccGFyDQo+ICAgICAgICAgVGhlIGZpcnN0
IHRoaW5nIGl0IG5lZWRzIGlzIGEgc2ltcGxlIG92ZXJ2aWV3LiAgQnJpZWZseSxccGFyDQo+IHdo
ZXJlIGRvIHlvdSBmaW5kIG91dCBob3cgdG8gZG8gd2hhdCBuZWVkcyB0byBiZSBkb25lP1xwYXIN
ClxwYXINCk1heWJlLiBCdXQgdGhlIHplcm90aCB0aGluZyBpdCBuZWVkcyBpcyBhbiBhbnN3ZXIg
dG8geW91ciBxdWVzdGlvblxwYXINCiJXaGF0IG5lZWRzIHRvIGJlIGRvbmU/Ii4gV2hlbiB3ZSBo
YXZlIHRoZSBhbnN3ZXIgd2UgY2FuIHN0YXJ0XHBhcg0KZXhwbGFpbmluZyBob3cgdG8gdXNlIHRo
ZSBCQiBmcmFtZXdvcmsgdG8gZG8gaXQuXHBhcg0KXHBhcg0KRXhhbXBsZTogSG93IGRvIEkgdXNl
IHNlcmlhbCBjb21tcz9ccGFyDQpccGFyDQpUaGlzIGlzIGEgdGFzay1jZW50cmVkIGFwcHJvYWNo
LiBDb250cmFzdCBpdCB3aXRoIHNvbWV0aGluZyBjYWxsZWRccGFyDQoiVXNpbmcgQ29tbVYyNCIu
XHBhcg0KXHBhcg0KPiBFYWNoIG1vZHVsZSxccGFyDQo+IG9yIGVhY2ggbGlicmFyeSwgb3Igd2hh
dGV2ZXIsIHNob3VsZCBoYXZlIGEgYnJpZWYgZGVzY3JpcHRpb24gaW5ccGFyDQo+IHBsYWluIEVu
Z2xpc2guICBNYWtlIHN1cmUgZWFjaCBtb2R1bGUgaXMgZGVzY3JpYmVkLiAgKEZvciBleGFtcGxl
LFxwYXINClsuLi5dXHBhcg0KXHBhcg0KVGhpcyBpcyByZWZlcmVuY2UgaW5mb3JtYXRpb24sIHdo
aWNoIGlzIGVzc2VudGlhbCwgYW5kIGV4aXN0cyBpblxwYXINCmFidW5kYW5jZS4gVGhlIG1haW4g
dGhpbmcgbWlzc2luZywgaW4gbXkgb3BpbmlvbiwgaXMgdGhlIHRhc2stY2VudHJlZFxwYXINCmlu
Zm9ybWF0aW9uLlxwYXINClxwYXINCj4gICAgICAgICBUaGVyZSBuZWVkcyB0byBiZSBhIHNpbXBs
ZSwgcHJvbWluZW50LCBhbmQgdW5pZmllZFxwYXINCj4gZGVzY3JpcHRpb24gb2YgSS9PLiAgQXMg
YSBtaW5pbXVtLCB0aGVyZSBuZWVkcyB0byBiZSBhIHNlY3Rpb24gb25ccGFyDQo+IHdvcmtpbmcg
d2l0aCBmb3JlaWduIGZpbGVzLCBiZWNhdXNlIHRoYXQgaXMgd2hhdCB0aGUgcmVzdCBvZiB0aGVc
cGFyDQo+IHdvcmxkIHVzZXMuICBUaGVyZSBuZWVkcyB0byBiZSBhIHNpbXBsZSBkZXNjcmlwdGlv
biBvZiBJL08gZnJvbVxwYXINCj4gZmlsZXMsIGtleWJvYXJkK21vbml0b3IsIGFuZCBtb3VzZS5c
cGFyDQpccGFyDQo+ICAgICAgICAgU28gaG93IGJpZyBhIGpvYiBpcyB0aGlzPyAgV2hhdCBkbyB5
b3UgdGhpbms/XHBhcg0KXHBhcg0KSXQgaXMgYSB2ZXJ5IGJpZyBqb2IuIEluIGZhY3QsIGl0IGlz
IHByb2JhYmx5IGluZmluaXRlLiBCdXQgaWYgeW91XHBhcg0KYWNjZXB0IHRoYXQgc3VjaCBhIGpv
YiBjYW4gbmV2ZXIgYmUgZmluaXNoZWQsIHlvdSBjYW4gYmVnaW4gdG8gZGVmaW5lXHBhcg0KYW4g
YXBwcm9hY2ggdG8gaXQuXHBhcg0KXHBhcg0KTXkgdmlldyBpcyB0aGF0IHdlIHNob3VsZCB0YWtl
IGl0IG9uIGluIGJpdGUtc2l6ZWQgY2h1bmtzLCBhbmQgd3JpdGVccGFyDQptYW55IHNtYWxsLCBp
bmRlcGVuZGVudCB0b3BpY3MgcmF0aGVyIHRoYW4gdGhlIHNpbmdsZSBkb2N1bWVudCB0aGF0XHBh
cg0Kc29tZWJvZHkgZWxzZSBoYXMgcHJvcG9zZWQuIFRoaXMgaXMgY29uc2lzdGVudCB3aXRoIGN1
cnJlbnQgdGhpbmtpbmdccGFyDQppbiB0aGUgd29ybGQgb2YgdGVjaG5pY2FsIHdyaXRpbmcsIGFu
ZCBpcyB0aGUgYXBwcm9hY2ggZmF2b3VyZWQgYnkgdGhlXHBhcg0KbWFqb3Igc3RhbmRhcmRzIGJv
ZGllcy5ccGFyDQpccGFyDQpJQk0gaGFzIHB1dCBmb3J3YXJkIHNvbWV0aGluZyBjYWxsZWQgdGhl
IERhcndpbiBJbmZvcm1hdGlvbiBUeXBlXHBhcg0KQXJjaGl0ZWN0dXJlLiBUaGUgdXNlZnVsIGFz
cGVjdCBvZiBpdCwgZm9yIHRoZXNlIHB1cnBvc2VzLCBpcyB0aGF0IGl0XHBhcg0KcHJvdmlkZXMg
YSBtZXRob2QgZm9yIGNsYXNzaWZ5aW5nIGluZm9ybWF0aW9uLCBhbmQgZm9yIGRldGVybWluaW5n
XHBhcg0Kd2hhdCBjaHVua3Mgb2YgaW5mb3JtYXRpb24gdG8gaW5jbHVkZSB3aXRoIGFueSBpbmZv
cm1hdGlvbiB0eXBlLCB0b1xwYXINCndyaXRlIHNtYWxsLCBjb25zaXN0ZW50IHRvcGljcy5ccGFy
DQpccGFyDQpBIHNpbWlsYXIgYXBwcm9hY2ggaXMgY2FsbGVkIEluZm9ybWF0aW9uIE1hcHBpbmcs
IG9yIFN0cnVjdHVyZWQgV3JpdGluZyxccGFyDQpidXQgaXQgaXMgYSBwcm9wcmlldGFyeSBtZXRo
b2Q7IGluZm9ybWF0aW9uIGFib3V0IGl0IGlzIHF1aXRlIGRpZmZpY3VsdFxwYXINCnRvIGZpbmQg
d2l0aG91dCBnb2luZyBvbiBhbiBleHBlbnNpdmUgY291cnNlLlxwYXINClxwYXINCkJvdGggb2Yg
dGhlc2UgYXJlIHN0cnVjdHVyZWQsIGJvdHRvbS11cCBhcHByb2FjaGVzLCB3aGljaCBmaXQgdmVy
eSB3ZWxsXHBhcg0KaW50byBhIGh5cGVydGV4dCBzdHlsZSBvZiBuYXZpZ2F0aW9uLlxwYXINClxw
YXINCldyaXRpbmcgc21hbGwgdG9waWNzIG1ha2VzIGl0IG11Y2ggZWFzaWVyIHRvIGFwcGx5IG1h
bnkgZGlmZmVyZW50IHJvdXRlc1xwYXINCnRocm91Z2ggdGhlIGRvY3VtZW50YXRpb24sIHRhaWxv
cmVkIHRvIHNwZWNpZmljIG5lZWRzLCB0aGFuIHRoZSBzaW5nbGVccGFyDQpkb2N1bWVudCBhcHBy
b2FjaC5ccGFyDQpccGFyDQpJZiB5b3UgaGF2ZSBhY2Nlc3MgdG8gYSBnb29kIGxpYnJhcnkgb3Ig
Ym9va3Nob3AgeW91IGNhbiBmaW5kIG1vcmVccGFyDQphYm91dCB0aGVzZSB0ZWNobmlxdWVzIGhl
cmU6IGh0dHA6Ly90aW55dXJsLmNvbS8zd2U2Zy5ccGFyDQpccGFyDQpBcyB3ZSBpZGVudGlmeSB0
b3BpY3MsIHRoZSBwZXJzb24gd2hvIHdhbnRzIHRvIHdyaXRlIHRoZSB0b3BpYyAnYm9va3NccGFy
DQppdCBvdXQnLCB3cml0ZXMgaXQsIHRoZW4gcHVibGlzaGVzIGl0IHdoZXJlZXZlci4gV2hlbiBp
dCBuZWVkcyB0byBiZVxwYXINCmNoYW5nZWQgc29tZWJvZHkgZWxzZSwgb3IgcGVyaGFwcyB0aGUg
b3JpZ2luYWwgd3JpdGVyLCBjYW4gYm9vayBpdCBvdXRccGFyDQphbmQgbWFrZSB0aGUgY2hhbmdl
LiBBcyBtYW55IHBlb3BsZSBhcyB3aXNoIHRvIGRvIHNvIGNhbiB0aGVuIHdvcmsgb25ccGFyDQph
cyBtYW55IHRvcGljcyBhcyBuZWNlc3Nhcnkgd2l0aG91dCBib3R0bGVuZWNrcy4gVGhpcyByZXF1
aXJlcyBzb21lXHBhcg0KY2VudHJhbCBwb2ludCBmb3IgbGlzdGluZyB0b3BpY3MgYW5kIHRoZWly
IHN0YXR1cyAobmV3LCBib29rZWQsXHBhcg0KZmluaXNoZWQsIC4uLikuIFBlcmhhcHMgV2lraSBp
cyBhIGdvb2Qgd2F5IG9mIGRvaW5nIHRoaXMgLSBidXQgSSBkb24ndFxwYXINCnJlYWxseSBrbm93
IG11Y2ggYWJvdXQgV2lraS5ccGFyDQpccGFyDQotLSBccGFyDQpSZWdhcmRzLFxwYXINCiBCb2Jc
cGFyDQpccGFyDQotLS0gQmxhY2tCb3hccGFyDQotLS0gc2VuZCBzdWJqZWN0IEhFTFAgb3IgVU5T
VUJTQ1JJQkUgdG8gYmxhY2tib3hAb2Jlcm9uLmNoXHBhcg0KfX0Aay4NCg==
----boundary-LibPST-iamunique-397147145_-_---

Received on Sat Mar 19 2005 - 13:12:27 UTC