- Tutorial or Documentation?

From: Douglas G. Danforth <"Douglas>
Date: Thu, 24 Mar 2005 15:59:57 -0500

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

Campbell, Robert D (UK Edinburgh) wrote:
> Yes, I used the name 'Map'. Generally I try to model my
> Docu's on the Oms precedents. They use 'Map', or rather
> 'Sys-Map', as a top-level introduction / contents list.
>
> The 'essbase' example posted is called 'infomap'.
>
> At a rather more general level I find that many small
> byperlinked Docu's work better for me than 1 large
> monolithic document as has been proposed. For an example
> see the 'Docupack' I put together for the half dozen subsystems
> that make up Chill_09.

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

The new comer wants everything in one place. The experienced user wants
flexibility to restructure as needed.

In place of 'Map' I suggest 'Table of Contents', a well known form used
in 'books' for indicating what is included. A table of contents can
be(and frequently is) hyperlinked.

A 'Map' is a two dimension representation, whereas a 'Table of Contents'
indicates the linear ordering of topics. It is easier to think of
linear orders than to think of things spread all over the place. A
linear order also implies a passage or transition from one stage to the
next, a prerequisit of knowledge in order to move on to the next stage.
  That is what a novice would like to have, a guiding hand. The expert
just wants to jump to that part needed for a quick refresher.

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).

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

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

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

-Doug

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



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

e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIENhbXBiZWxsLCBSb2JlcnQgRCAoVUsgRWRpbmJ1
cmdoKSB3cm90ZTpccGFyDQo+IFllcywgSSB1c2VkIHRoZSBuYW1lICdNYXAnLiBHZW5lcmFsbHkg
SSB0cnkgdG8gbW9kZWwgbXlccGFyDQo+IERvY3UncyBvbiB0aGUgT21zIHByZWNlZGVudHMuIFRo
ZXkgdXNlICdNYXAnLCBvciByYXRoZXJccGFyDQo+ICdTeXMtTWFwJywgYXMgYSB0b3AtbGV2ZWwg
aW50cm9kdWN0aW9uIC8gY29udGVudHMgbGlzdC5ccGFyDQo+IFxwYXINCj4gVGhlICdlc3NiYXNl
JyBleGFtcGxlIHBvc3RlZCBpcyBjYWxsZWQgJ2luZm9tYXAnLlxwYXINCj4gXHBhcg0KPiBBdCBh
IHJhdGhlciBtb3JlIGdlbmVyYWwgbGV2ZWwgSSBmaW5kIHRoYXQgbWFueSBzbWFsbFxwYXINCj4g
YnlwZXJsaW5rZWQgRG9jdSdzIHdvcmsgYmV0dGVyIGZvciBtZSB0aGFuIDEgbGFyZ2VccGFyDQo+
IG1vbm9saXRoaWMgZG9jdW1lbnQgYXMgaGFzIGJlZW4gcHJvcG9zZWQuIEZvciBhbiBleGFtcGxl
XHBhcg0KPiBzZWUgdGhlICdEb2N1cGFjaycgSSBwdXQgdG9nZXRoZXIgZm9yIHRoZSBoYWxmIGRv
emVuIHN1YnN5c3RlbXNccGFyDQo+IHRoYXQgbWFrZSB1cCBDaGlsbF8wOS5ccGFyDQpccGFyDQpM
ZXRzIHN0ZXAgYmFjayBmb3IgYSBtaW51dGUgYW5kIHRha2UgYSBsb29rIGF0IHRoZSBiaWcgcGlj
dHVyZS5ccGFyDQpccGFyDQpUaGUgbmV3IGNvbWVyIHdhbnRzIGV2ZXJ5dGhpbmcgaW4gb25lIHBs
YWNlLiAgVGhlIGV4cGVyaWVuY2VkIHVzZXIgd2FudHMgXHBhcg0KZmxleGliaWxpdHkgdG8gcmVz
dHJ1Y3R1cmUgYXMgbmVlZGVkLlxwYXINClxwYXINCkluIHBsYWNlIG9mICdNYXAnIEkgc3VnZ2Vz
dCAnVGFibGUgb2YgQ29udGVudHMnLCBhIHdlbGwga25vd24gZm9ybSB1c2VkIFxwYXINCmluICdi
b29rcycgZm9yIGluZGljYXRpbmcgd2hhdCBpcyBpbmNsdWRlZC4gIEEgdGFibGUgb2YgY29udGVu
dHMgY2FuIFxwYXINCmJlKGFuZCBmcmVxdWVudGx5IGlzKSBoeXBlcmxpbmtlZC5ccGFyDQpccGFy
DQpBICdNYXAnIGlzIGEgdHdvIGRpbWVuc2lvbiByZXByZXNlbnRhdGlvbiwgd2hlcmVhcyBhICdU
YWJsZSBvZiBDb250ZW50cycgXHBhcg0KaW5kaWNhdGVzIHRoZSBsaW5lYXIgb3JkZXJpbmcgb2Yg
dG9waWNzLiAgSXQgaXMgZWFzaWVyIHRvIHRoaW5rIG9mIFxwYXINCmxpbmVhciBvcmRlcnMgdGhh
biB0byB0aGluayBvZiB0aGluZ3Mgc3ByZWFkIGFsbCBvdmVyIHRoZSBwbGFjZS4gIEEgXHBhcg0K
bGluZWFyIG9yZGVyIGFsc28gaW1wbGllcyBhIHBhc3NhZ2Ugb3IgdHJhbnNpdGlvbiBmcm9tIG9u
ZSBzdGFnZSB0byB0aGUgXHBhcg0KbmV4dCwgYSBwcmVyZXF1aXNpdCBvZiBrbm93bGVkZ2UgaW4g
b3JkZXIgdG8gbW92ZSBvbiB0byB0aGUgbmV4dCBzdGFnZS4gXHBhcg0KICBUaGF0IGlzIHdoYXQg
YSBub3ZpY2Ugd291bGQgbGlrZSB0byBoYXZlLCBhIGd1aWRpbmcgaGFuZC4gIFRoZSBleHBlcnQg
XHBhcg0KanVzdCB3YW50cyB0byBqdW1wIHRvIHRoYXQgcGFydCBuZWVkZWQgZm9yIGEgcXVpY2sg
cmVmcmVzaGVyLlxwYXINClxwYXINCklmIHlvdSBkbyB1c2UgYSAnbWFwJyB0aGVuIG9uZSBuZWVk
cyBhbiAnYXJlbmEnIGluIHdoaWNoIHRvIHBsYWNlIHRoZSBccGFyDQppdGVtcyBzdWNoIGFzIGEg
Y2l0eSB3aXRoIGJ1aWxkaW5ncyBhbmQgcm9vbXMgKHRoZSBhbmNpZW50IFJvbWFuIG9yYXRvcnMg
XHBhcg0KdXNlZCBzdWNoIG1lbnRhbCBkZXZpc2VzIHRvIHJlbWVtYmVyIGxvbmcgc3BlZWNoZXMp
LlxwYXINClxwYXINCllvdSBjYW4gc3RpbGwgaGF2ZSBzZXBhcmF0ZSAnY2hhcHRlcnMnIHdpdGgg
bGluZWFyIG9yZGVycyB0aGF0IGNhbiBiZSBccGFyDQphZGRlZCBhbmQgcmVtb3ZlZCBpbiBhIGZs
ZXhpYmxlIG1hbm5lci5ccGFyDQpccGFyDQpJIGhhdmUgYSBnb29kIEZpbm5pc2ggZnJpZW5kIHdo
byBpcyBhZGFtZW50IGFib3V0IGdvb2Qgd3JpdGluZy4gIEhlIFxwYXINCmluc2lzdHMgdGhhdCBj
b21wdXRlciB0ZWNobm9sb2d5IHNob3VsZCBub3Qgb2JzY3VyZSBvciBvYmZ1c2NhdGUgY29uY2Vw
dHMuXHBhcg0KXHBhcg0KTGV0J3Mgbm90IGxldCBjb21wdXRlcml6ZSBnZXQgaW4gdGhlIHdheSBv
ZiBkZXNjcmlwdGl2ZSBhbmQgd2VsbCBccGFyDQpvcmdhbml6ZWQgcHJvc2UuXHBhcg0KXHBhcg0K
LURvdWdccGFyDQpccGFyDQotLS0gQmxhY2tCb3hccGFyDQotLS0gc2VuZCBzdWJqZWN0IEhFTFAg
b3IgVU5TVUJTQ1JJQkUgdG8gYmxhY2tib3hAb2Jlcm9uLmNofX0AAACIwFIAHgAAAA==


----boundary-LibPST-iamunique-1099044961_-_---
Received on Thu Mar 24 2005 - 21:59:57 UTC