- Tutorial or Documentation?

From: [at]} <Bob>
Date: Fri, 25 Mar 2005 10:07:12 +0000

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

Hi,

>>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 like this. I do agree with you.

> What I am worried about is continuity where a single author remembers
> what he said in chapter 2 and can refer to it in chapter 7 (say).

This really has to be a matter of agreement and understanding about
how hypertext works. But, numbered chapters or topics imply a fixed
sequence in a single trail, which is something I think we should
definitely avoid.

Traditional chapters are too large to be the smallest unit of writing.
Topics are much smaller, and more formally defined. Each topic is a
discrete, meaningful, single piece of information. It is usually short
and gives the reader just the information needed, and no more.

The topic type dictates the kinds of information the topic should
contain. Careful consideration of what you are trying to say should
sort the information to the correct place, which reduces or eliminates
unstructured cross-referencing.

> With
> multiple authors (and no Editor) this continuity is lost. The words
> "fragmented", "jumbled", "disorganized", come to mind.

It is possible to get lost in hyperspace, but these words can apply
equally well to any document. A few simple guidelines for authors
should help to avoid this, as well as the type of spaghetti-style
cross-references you mentioned.

Using topics rather than more traditional methods of organization is
similar to structured programming with small self-contained and self-sufficient
subroutines or procedures, with the least possible amount of global
data.

> I find reading Microsoft documentation dry as sand and hope we can avoid
> that style. We need "why" something is done in addition to "how" it is
> done.

I think the Microsoft documentation often misses out on essential context
information.

Today's programmers seem to find it quite accessible though. I've been
around software development for 25 years, and was always used to
having shelves full of printed manuals and books. Recently I acquired
a team of young .Net developers. When I asked them if they had a full
set of manuals, or needed me to get some books for them, they looked
at me as if I was mad, and said they just used the Microsoft online
manuals.

> Now, how do we move forward?

I would like to try and write an example of what I mean. I am trying
to think of something manageable as an example. But despite the long
weekend I have an awful lot of work to do, so I can't promise anything.

-- 
Regards,
 Bob
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy----boundary-LibPST-iamunique-257032043_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEhpLFxwYXINClxwYXINCj4+VGhlIHRyYWlscyBj
YW4gaW5jbHVkZSBhIHRyYWRpdGlvbmFsIHRhYmxlIG9mIGNvbnRlbnRzLCBvZiBjb3Vyc2UuXHBh
cg0KPj5PdGhlciB0eXBlcyBvZiB0cmFpbCBjb3VsZCBpbmNsdWRlOlxwYXINCj4+XHBhcg0KPj4g
ICAgICAgUHJlcmVxdWlzaXRlcyAtIGZvciBsZWFybmluZyBpbiBhIHBhcnRpY3VsYXIgb3JkZXJc
cGFyDQo+PiAgICAgICBDbGFzc2lmaWNhdGlvbnMgLSB0byBncm91cCBzaW1pbGFyIGNvbmNlcHRz
XHBhcg0KPj4gICAgICAgQ2hyb25vbG9neSAtIHRvIHNob3cgZXZlbnRzIGhhcHBlbmluZyBpbiB0
aW1lIG9yZGVyXHBhcg0KPj4gICAgICAgU3RydWN0dXJlcyAtIHRvIHNob3cgdGhlIHBhcnRzIG9m
IGEgc3RydWN0dXJlXHBhcg0KPj4gICAgICAgRGVmaW5pdGlvbiAtIHRvIGxpbmsgcmVsYXRlZCBv
ciBzaW1pbGFyIGRlZmluaXRpb25zIG9yIHRlcm1zXHBhcg0KPj4gICAgICAgRXhhbXBsZXMgLSB0
byBsaW5rIHRoZSBzZXBhcmF0ZSBwYXJ0cyBvZiBhIHJ1bm5pbmcgZXhhbXBsZVxwYXINClxwYXIN
Cj4gSSBsaWtlIHRoaXMuICBJIGRvIGFncmVlIHdpdGggeW91LlxwYXINClxwYXINCj4gV2hhdCBJ
IGFtIHdvcnJpZWQgYWJvdXQgaXMgY29udGludWl0eSB3aGVyZSBhIHNpbmdsZSBhdXRob3IgcmVt
ZW1iZXJzXHBhcg0KPiB3aGF0IGhlIHNhaWQgaW4gY2hhcHRlciAyIGFuZCBjYW4gcmVmZXIgdG8g
aXQgaW4gY2hhcHRlciA3IChzYXkpLlxwYXINClxwYXINClRoaXMgcmVhbGx5IGhhcyB0byBiZSBh
IG1hdHRlciBvZiBhZ3JlZW1lbnQgYW5kIHVuZGVyc3RhbmRpbmcgYWJvdXRccGFyDQpob3cgaHlw
ZXJ0ZXh0IHdvcmtzLiBCdXQsIG51bWJlcmVkIGNoYXB0ZXJzIG9yIHRvcGljcyBpbXBseSBhIGZp
eGVkXHBhcg0Kc2VxdWVuY2UgaW4gYSBzaW5nbGUgdHJhaWwsIHdoaWNoIGlzIHNvbWV0aGluZyBJ
IHRoaW5rIHdlIHNob3VsZFxwYXINCmRlZmluaXRlbHkgYXZvaWQuXHBhcg0KXHBhcg0KVHJhZGl0
aW9uYWwgY2hhcHRlcnMgYXJlIHRvbyBsYXJnZSB0byBiZSB0aGUgc21hbGxlc3QgdW5pdCBvZiB3
cml0aW5nLlxwYXINClRvcGljcyBhcmUgbXVjaCBzbWFsbGVyLCBhbmQgbW9yZSBmb3JtYWxseSBk
ZWZpbmVkLiBFYWNoIHRvcGljIGlzIGFccGFyDQpkaXNjcmV0ZSwgbWVhbmluZ2Z1bCwgc2luZ2xl
IHBpZWNlIG9mIGluZm9ybWF0aW9uLiBJdCBpcyB1c3VhbGx5IHNob3J0XHBhcg0KYW5kIGdpdmVz
IHRoZSByZWFkZXIganVzdCB0aGUgaW5mb3JtYXRpb24gbmVlZGVkLCBhbmQgbm8gbW9yZS5ccGFy
DQpccGFyDQpUaGUgdG9waWMgdHlwZSBkaWN0YXRlcyB0aGUga2luZHMgb2YgaW5mb3JtYXRpb24g
dGhlIHRvcGljIHNob3VsZFxwYXINCmNvbnRhaW4uIENhcmVmdWwgY29uc2lkZXJhdGlvbiBvZiB3
aGF0IHlvdSBhcmUgdHJ5aW5nIHRvIHNheSBzaG91bGRccGFyDQpzb3J0IHRoZSBpbmZvcm1hdGlv
biB0byB0aGUgY29ycmVjdCBwbGFjZSwgd2hpY2ggcmVkdWNlcyBvciBlbGltaW5hdGVzXHBhcg0K
dW5zdHJ1Y3R1cmVkIGNyb3NzLXJlZmVyZW5jaW5nLlxwYXINClxwYXINCj4gV2l0aFxwYXINCj4g
bXVsdGlwbGUgYXV0aG9ycyAoYW5kIG5vIEVkaXRvcikgdGhpcyBjb250aW51aXR5IGlzIGxvc3Qu
ICBUaGUgd29yZHNccGFyDQo+ICJmcmFnbWVudGVkIiwgImp1bWJsZWQiLCAiZGlzb3JnYW5pemVk
IiwgY29tZSB0byBtaW5kLlxwYXINClxwYXINCkl0IGlzIHBvc3NpYmxlIHRvIGdldCBsb3N0IGlu
IGh5cGVyc3BhY2UsIGJ1dCB0aGVzZSB3b3JkcyBjYW4gYXBwbHlccGFyDQplcXVhbGx5IHdlbGwg
dG8gYW55IGRvY3VtZW50LiBBIGZldyBzaW1wbGUgZ3VpZGVsaW5lcyBmb3IgYXV0aG9yc1xwYXIN
CnNob3VsZCBoZWxwIHRvIGF2b2lkIHRoaXMsIGFzIHdlbGwgYXMgdGhlIHR5cGUgb2Ygc3BhZ2hl
dHRpLXN0eWxlXHBhcg0KY3Jvc3MtcmVmZXJlbmNlcyB5b3UgbWVudGlvbmVkLlxwYXINClxwYXIN
ClVzaW5nIHRvcGljcyByYXRoZXIgdGhhbiBtb3JlIHRyYWRpdGlvbmFsIG1ldGhvZHMgb2Ygb3Jn
YW5pemF0aW9uIGlzXHBhcg0Kc2ltaWxhciB0byBzdHJ1Y3R1cmVkIHByb2dyYW1taW5nIHdpdGgg
c21hbGwgc2VsZi1jb250YWluZWQgYW5kIHNlbGYtc3VmZmljaWVudFxwYXINCnN1YnJvdXRpbmVz
IG9yIHByb2NlZHVyZXMsIHdpdGggdGhlIGxlYXN0IHBvc3NpYmxlIGFtb3VudCBvZiBnbG9iYWxc
cGFyDQpkYXRhLlxwYXINClxwYXINCj4gSSBmaW5kIHJlYWRpbmcgTWljcm9zb2Z0IGRvY3VtZW50
YXRpb24gZHJ5IGFzIHNhbmQgYW5kIGhvcGUgd2UgY2FuIGF2b2lkXHBhcg0KPiB0aGF0IHN0eWxl
LiAgV2UgbmVlZCAid2h5IiBzb21ldGhpbmcgaXMgZG9uZSBpbiBhZGRpdGlvbiB0byAiaG93IiBp
dCBpc1xwYXINCj4gZG9uZS5ccGFyDQpccGFyDQpJIHRoaW5rIHRoZSBNaWNyb3NvZnQgZG9jdW1l
bnRhdGlvbiBvZnRlbiBtaXNzZXMgb3V0IG9uIGVzc2VudGlhbCBjb250ZXh0XHBhcg0KaW5mb3Jt
YXRpb24uXHBhcg0KXHBhcg0KVG9kYXkncyBwcm9ncmFtbWVycyBzZWVtIHRvIGZpbmQgaXQgcXVp
dGUgYWNjZXNzaWJsZSB0aG91Z2guIEkndmUgYmVlblxwYXINCmFyb3VuZCBzb2Z0d2FyZSBkZXZl
bG9wbWVudCBmb3IgMjUgeWVhcnMsIGFuZCB3YXMgYWx3YXlzIHVzZWQgdG9ccGFyDQpoYXZpbmcg
c2hlbHZlcyBmdWxsIG9mIHByaW50ZWQgbWFudWFscyBhbmQgYm9va3MuIFJlY2VudGx5IEkgYWNx
dWlyZWRccGFyDQphIHRlYW0gb2YgeW91bmcgLk5ldCBkZXZlbG9wZXJzLiBXaGVuIEkgYXNrZWQg
dGhlbSBpZiB0aGV5IGhhZCBhIGZ1bGxccGFyDQpzZXQgb2YgbWFudWFscywgb3IgbmVlZGVkIG1l
IHRvIGdldCBzb21lIGJvb2tzIGZvciB0aGVtLCB0aGV5IGxvb2tlZFxwYXINCmF0IG1lIGFzIGlm
IEkgd2FzIG1hZCwgYW5kIHNhaWQgdGhleSBqdXN0IHVzZWQgdGhlIE1pY3Jvc29mdCBvbmxpbmVc
cGFyDQptYW51YWxzLlxwYXINClxwYXINCj4gTm93LCBob3cgZG8gd2UgbW92ZSBmb3J3YXJkP1xw
YXINClxwYXINCkkgd291bGQgbGlrZSB0byB0cnkgYW5kIHdyaXRlIGFuIGV4YW1wbGUgb2Ygd2hh
dCBJIG1lYW4uIEkgYW0gdHJ5aW5nXHBhcg0KdG8gdGhpbmsgb2Ygc29tZXRoaW5nIG1hbmFnZWFi
bGUgYXMgYW4gZXhhbXBsZS4gQnV0IGRlc3BpdGUgdGhlIGxvbmdccGFyDQp3ZWVrZW5kIEkgaGF2
ZSBhbiBhd2Z1bCBsb3Qgb2Ygd29yayB0byBkbywgc28gSSBjYW4ndCBwcm9taXNlIGFueXRoaW5n
LlxwYXINClxwYXINCi0tIFxwYXINClJlZ2FyZHMsXHBhcg0KIEJvYlxwYXINClxwYXINCi0tLSBC
bGFja0JveFxwYXINCi0tLSBzZW5kIHN1YmplY3QgSEVMUCBvciBVTlNVQlNDUklCRSB0byBibGFj
a2JveEBvYmVyb24uY2h9fQAjAECAIsEfUgCQ
----boundary-LibPST-iamunique-257032043_-_---

Received on Fri Mar 25 2005 - 11:07:12 UTC