- Tutorial or Documentation?

From: [at]} <Bob>
Date: Thu, 24 Mar 2005 22:07:53 +0000

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

Hi Douglas,

> Lets step back for a minute and take a look at the big picture.

> The new comer wants everything in one place.

What makes you think this?

What do you mean by one place? One file? One server?

[...]

> If you do use a 'map' then one needs an 'arena' in which to place the
> items such as a city with buildings and rooms (the ancient Roman orators
> used such mental devises to remember long speeches).

I think you are taking the analogy too literally.

> You can still have separate 'chapters' with linear orders that can be
> added and removed in a flexible manner.

One of the great benefits of adopting a topic-based approach is that it
is no longer necessary to have a single organization for the complete
document, or even a single document. Or even a complete document.

For this to be feasible it is important for the topic writers to be
aware, and not include phrases such as 'see below', or 'see Chapter
42', but instead to use hypertext links and trails.

The entire subject matter can have several distinct trails, which can
be written by different people before, during or a long time after the
main content topics.

The trails can include a traditional table of contents, of course.
Other types of trail could include:

      Prerequisites - for learning in a particular order
      Classifications - to group similar concepts
      Chronology - to show events happening in time order
      Structures - to show the parts of a structure
      Definition - to link related or similar definitions or terms
      Examples - to link the separate parts of a running example

> I have a good Finnish friend who is adament about good writing. He
> insists that computer technology should not obscure or obfuscate concepts.

What makes him think that computer technology necessarily does this?
If it's used properly it can clarify and simplify.

Who has not seen (and even written) large single documents which are obscure
and confusing?

> Let's not let computerize get in the way of descriptive and well
> organized prose.

I assume that the documentation will be on a computer, not a book. Why
should information presented on a computer be constrained by the
physical limitations of a book?

It is not the medium which determines clarity or confusion, it is
the quality of thinking, and the skill of the writer.

-- 
Regards,
 Bob
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy----boundary-LibPST-iamunique-272769057_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEhpIERvdWdsYXMsXHBhcg0KXHBhcg0KPiBMZXRz
IHN0ZXAgYmFjayBmb3IgYSBtaW51dGUgYW5kIHRha2UgYSBsb29rIGF0IHRoZSBiaWcgcGljdHVy
ZS5ccGFyDQpccGFyDQo+IFRoZSBuZXcgY29tZXIgd2FudHMgZXZlcnl0aGluZyBpbiBvbmUgcGxh
Y2UuXHBhcg0KXHBhcg0KV2hhdCBtYWtlcyB5b3UgdGhpbmsgdGhpcz9ccGFyDQpccGFyDQpXaGF0
IGRvIHlvdSBtZWFuIGJ5IG9uZSBwbGFjZT8gT25lIGZpbGU/IE9uZSBzZXJ2ZXI/XHBhcg0KXHBh
cg0KWy4uLl1ccGFyDQpccGFyDQo+IElmIHlvdSBkbyB1c2UgYSAnbWFwJyB0aGVuIG9uZSBuZWVk
cyBhbiAnYXJlbmEnIGluIHdoaWNoIHRvIHBsYWNlIHRoZVxwYXINCj4gaXRlbXMgc3VjaCBhcyBh
IGNpdHkgd2l0aCBidWlsZGluZ3MgYW5kIHJvb21zICh0aGUgYW5jaWVudCBSb21hbiBvcmF0b3Jz
XHBhcg0KPiB1c2VkIHN1Y2ggbWVudGFsIGRldmlzZXMgdG8gcmVtZW1iZXIgbG9uZyBzcGVlY2hl
cykuXHBhcg0KXHBhcg0KSSB0aGluayB5b3UgYXJlIHRha2luZyB0aGUgYW5hbG9neSB0b28gbGl0
ZXJhbGx5LlxwYXINClxwYXINCj4gWW91IGNhbiBzdGlsbCBoYXZlIHNlcGFyYXRlICdjaGFwdGVy
cycgd2l0aCBsaW5lYXIgb3JkZXJzIHRoYXQgY2FuIGJlXHBhcg0KPiBhZGRlZCBhbmQgcmVtb3Zl
ZCBpbiBhIGZsZXhpYmxlIG1hbm5lci5ccGFyDQpccGFyDQpPbmUgb2YgdGhlIGdyZWF0IGJlbmVm
aXRzIG9mIGFkb3B0aW5nIGEgdG9waWMtYmFzZWQgYXBwcm9hY2ggaXMgdGhhdCBpdFxwYXINCmlz
IG5vIGxvbmdlciBuZWNlc3NhcnkgdG8gaGF2ZSBhIHNpbmdsZSBvcmdhbml6YXRpb24gZm9yIHRo
ZSBjb21wbGV0ZVxwYXINCmRvY3VtZW50LCBvciBldmVuIGEgc2luZ2xlIGRvY3VtZW50LiBPciBl
dmVuIGEgY29tcGxldGUgZG9jdW1lbnQuXHBhcg0KXHBhcg0KRm9yIHRoaXMgdG8gYmUgZmVhc2li
bGUgaXQgaXMgaW1wb3J0YW50IGZvciB0aGUgdG9waWMgd3JpdGVycyB0byBiZVxwYXINCmF3YXJl
LCBhbmQgbm90IGluY2x1ZGUgcGhyYXNlcyBzdWNoIGFzICdzZWUgYmVsb3cnLCBvciAnc2VlIENo
YXB0ZXJccGFyDQo0MicsIGJ1dCBpbnN0ZWFkIHRvIHVzZSBoeXBlcnRleHQgbGlua3MgYW5kIHRy
YWlscy5ccGFyDQpccGFyDQpUaGUgZW50aXJlIHN1YmplY3QgbWF0dGVyIGNhbiBoYXZlIHNldmVy
YWwgZGlzdGluY3QgdHJhaWxzLCB3aGljaCBjYW5ccGFyDQpiZSB3cml0dGVuIGJ5IGRpZmZlcmVu
dCBwZW9wbGUgYmVmb3JlLCBkdXJpbmcgb3IgYSBsb25nIHRpbWUgYWZ0ZXIgdGhlXHBhcg0KbWFp
biBjb250ZW50IHRvcGljcy5ccGFyDQpccGFyDQpUaGUgdHJhaWxzIGNhbiBpbmNsdWRlIGEgdHJh
ZGl0aW9uYWwgdGFibGUgb2YgY29udGVudHMsIG9mIGNvdXJzZS5ccGFyDQpPdGhlciB0eXBlcyBv
ZiB0cmFpbCBjb3VsZCBpbmNsdWRlOlxwYXINClxwYXINCiAgICAgIFByZXJlcXVpc2l0ZXMgLSBm
b3IgbGVhcm5pbmcgaW4gYSBwYXJ0aWN1bGFyIG9yZGVyXHBhcg0KICAgICAgQ2xhc3NpZmljYXRp
b25zIC0gdG8gZ3JvdXAgc2ltaWxhciBjb25jZXB0c1xwYXINCiAgICAgIENocm9ub2xvZ3kgLSB0
byBzaG93IGV2ZW50cyBoYXBwZW5pbmcgaW4gdGltZSBvcmRlclxwYXINCiAgICAgIFN0cnVjdHVy
ZXMgLSB0byBzaG93IHRoZSBwYXJ0cyBvZiBhIHN0cnVjdHVyZVxwYXINCiAgICAgIERlZmluaXRp
b24gLSB0byBsaW5rIHJlbGF0ZWQgb3Igc2ltaWxhciBkZWZpbml0aW9ucyBvciB0ZXJtc1xwYXIN
CiAgICAgIEV4YW1wbGVzIC0gdG8gbGluayB0aGUgc2VwYXJhdGUgcGFydHMgb2YgYSBydW5uaW5n
IGV4YW1wbGVccGFyDQpccGFyDQo+IEkgaGF2ZSBhIGdvb2QgRmlubmlzaCBmcmllbmQgd2hvIGlz
IGFkYW1lbnQgYWJvdXQgZ29vZCB3cml0aW5nLiAgSGUgXHBhcg0KPiBpbnNpc3RzIHRoYXQgY29t
cHV0ZXIgdGVjaG5vbG9neSBzaG91bGQgbm90IG9ic2N1cmUgb3Igb2JmdXNjYXRlIGNvbmNlcHRz
LlxwYXINClxwYXINCldoYXQgbWFrZXMgaGltIHRoaW5rIHRoYXQgY29tcHV0ZXIgdGVjaG5vbG9n
eSBuZWNlc3NhcmlseSBkb2VzIHRoaXM/XHBhcg0KSWYgaXQncyB1c2VkIHByb3Blcmx5IGl0IGNh
biBjbGFyaWZ5IGFuZCBzaW1wbGlmeS5ccGFyDQpccGFyDQpXaG8gaGFzIG5vdCBzZWVuIChhbmQg
ZXZlbiB3cml0dGVuKSBsYXJnZSBzaW5nbGUgZG9jdW1lbnRzIHdoaWNoIGFyZSBvYnNjdXJlXHBh
cg0KYW5kIGNvbmZ1c2luZz9ccGFyDQpccGFyDQo+IExldCdzIG5vdCBsZXQgY29tcHV0ZXJpemUg
Z2V0IGluIHRoZSB3YXkgb2YgZGVzY3JpcHRpdmUgYW5kIHdlbGwgXHBhcg0KPiBvcmdhbml6ZWQg
cHJvc2UuXHBhcg0KXHBhcg0KSSBhc3N1bWUgdGhhdCB0aGUgZG9jdW1lbnRhdGlvbiB3aWxsIGJl
IG9uIGEgY29tcHV0ZXIsIG5vdCBhIGJvb2suIFdoeVxwYXINCnNob3VsZCBpbmZvcm1hdGlvbiBw
cmVzZW50ZWQgb24gYSBjb21wdXRlciBiZSBjb25zdHJhaW5lZCBieSB0aGVccGFyDQpwaHlzaWNh
bCBsaW1pdGF0aW9ucyBvZiBhIGJvb2s/XHBhcg0KXHBhcg0KSXQgaXMgbm90IHRoZSBtZWRpdW0g
d2hpY2ggZGV0ZXJtaW5lcyBjbGFyaXR5IG9yIGNvbmZ1c2lvbiwgaXQgaXNccGFyDQp0aGUgcXVh
bGl0eSBvZiB0aGlua2luZywgYW5kIHRoZSBza2lsbCBvZiB0aGUgd3JpdGVyLlxwYXINClxwYXIN
Ci0tIFxwYXINClJlZ2FyZHMsXHBhcg0KIEJvYlxwYXINClxwYXINCi0tLSBCbGFja0JveFxwYXIN
Ci0tLSBzZW5kIHN1YmplY3QgSEVMUCBvciBVTlNVQlNDUklCRSB0byBibGFja2JveEBvYmVyb24u
Y2h9fQBuLmNoAFNNVFAA
----boundary-LibPST-iamunique-272769057_-_---

Received on Thu Mar 24 2005 - 23:07:53 UTC