Documentation and pointers

From: Douglas G. Danforth <"Douglas>
Date: Sat, 02 Aug 2003 13:18:35 -0400

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

Hello,

I am in the midst of reading the TextModels documentation since I wish
to understand how Coco/R uses it to produce output. As I read along I
find many references to concepts which are not defined within the
document but seem to hint that the concepts are defined elsewhere. The
author of the document obviously had a full understanding and knowledge
of all the parts of the Blackbox framework and hence either forgot or
purposefully did not define those concepts within the TextModels
documentation (for example "text setter").

Knowing of the "purposefully left unsaid" emphasis by Dr. Wirth I assume
that the Blackbox documentation is following this principle. I have a
few comments.

For program construction one wants to follow the principle of "one place
only" so that a change in only one place is propogated throughout the
whole program. This makes maintanence easier.

For human understanding and learning one wants many references to the
same concept in slightly differing forms. This helps disambiguate the
concept (which resides in a large multidimensional space). One wants to
point to the concept by "triangulation". This makes document maintanence
difficult since changes in a concept can not be easily propogated
throught the documentation.

The use of "one place only" and "multiple descriptions" are at variance
with each other and yet to have someone use what you have created it is
necessary to "teach" what you have done, to cast the creation in as
clear and as bright a light as possible, otherwise all of your efforts
may be lost to the casual reader who, just might be a large investor!

Thoughts on solutions
o Automation: create some bit of sotware that tracts all forward
pointers (document links) and creates hidden backpointers that can be
used to alert the document writer when changes are made. This allows
the writer to reexamine those forward pointers to determine if those
sections need to have their text changed also.

o User oriented statistics: Allow some subset of users to insert
question marks into documentation "[?]" that is then returned to the
document writers for clarification and embellishment.

o Time: Good documentation writing takes time ...

In general for the Blackbox documentation it is not possible to step
into the middle of it and extract what one needs. One must absorb the
whole in order to use a part. This is not an optimal use of one's time.

There must be some way that the Blackbox user community can help Ominc
improve its documentation.

-Doug


--------------------------------------------

To unsubscribe from this mailing list, send a message containing the word "unsubscribe" to:
   blackbox-request{([at]})nowhere.xy

To get a list of valid e-mail commands and instructions on their usage, send a message containing the word "help" to the above address.

Send any problem reports or questions related to this email list to the list owner at
   owner-blackbox{([at]})nowhere.xy

Current posting policy:

a) To post you should use the same address by which you are subscribed to the mailing list. That way, the list server will recognize you as subscriber and forward your posting immediately, without creating any overhead.

b) If, for some reason, you cannot post from the address, by which you are subscribed, your message will be moderated to avoid spam. Please understand that moderation will often cause some delay, in particular over weekends or holydays.



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

e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEhlbGxvLFxwYXINClxwYXINCkkgYW0gaW4gdGhl
IG1pZHN0IG9mIHJlYWRpbmcgdGhlIFRleHRNb2RlbHMgZG9jdW1lbnRhdGlvbiBzaW5jZSBJIHdp
c2ggXHBhcg0KdG8gdW5kZXJzdGFuZCBob3cgQ29jby9SIHVzZXMgaXQgdG8gcHJvZHVjZSBvdXRw
dXQuICBBcyBJIHJlYWQgYWxvbmcgSSBccGFyDQpmaW5kIG1hbnkgcmVmZXJlbmNlcyB0byBjb25j
ZXB0cyB3aGljaCBhcmUgbm90IGRlZmluZWQgd2l0aGluIHRoZSBccGFyDQpkb2N1bWVudCBidXQg
c2VlbSB0byBoaW50IHRoYXQgdGhlIGNvbmNlcHRzIGFyZSBkZWZpbmVkIGVsc2V3aGVyZS4gIFRo
ZSBccGFyDQphdXRob3Igb2YgdGhlIGRvY3VtZW50IG9idmlvdXNseSBoYWQgYSBmdWxsIHVuZGVy
c3RhbmRpbmcgYW5kIGtub3dsZWRnZSBccGFyDQpvZiBhbGwgdGhlIHBhcnRzIG9mIHRoZSBCbGFj
a2JveCBmcmFtZXdvcmsgYW5kIGhlbmNlIGVpdGhlciBmb3Jnb3Qgb3IgXHBhcg0KcHVycG9zZWZ1
bGx5IGRpZCBub3QgZGVmaW5lIHRob3NlIGNvbmNlcHRzIHdpdGhpbiB0aGUgVGV4dE1vZGVscyBc
cGFyDQpkb2N1bWVudGF0aW9uIChmb3IgZXhhbXBsZSAidGV4dCBzZXR0ZXIiKS5ccGFyDQpccGFy
DQpLbm93aW5nIG9mIHRoZSAicHVycG9zZWZ1bGx5IGxlZnQgdW5zYWlkIiBlbXBoYXNpcyBieSBE
ci4gV2lydGggSSBhc3N1bWUgXHBhcg0KdGhhdCB0aGUgQmxhY2tib3ggZG9jdW1lbnRhdGlvbiBp
cyBmb2xsb3dpbmcgdGhpcyBwcmluY2lwbGUuICBJIGhhdmUgYSBccGFyDQpmZXcgY29tbWVudHMu
XHBhcg0KXHBhcg0KRm9yIHByb2dyYW0gY29uc3RydWN0aW9uIG9uZSB3YW50cyB0byBmb2xsb3cg
dGhlIHByaW5jaXBsZSBvZiAib25lIHBsYWNlIFxwYXINCm9ubHkiIHNvIHRoYXQgYSBjaGFuZ2Ug
aW4gb25seSBvbmUgcGxhY2UgaXMgcHJvcG9nYXRlZCB0aHJvdWdob3V0IHRoZSBccGFyDQp3aG9s
ZSBwcm9ncmFtLiAgVGhpcyBtYWtlcyBtYWludGFuZW5jZSBlYXNpZXIuXHBhcg0KXHBhcg0KRm9y
IGh1bWFuIHVuZGVyc3RhbmRpbmcgYW5kIGxlYXJuaW5nIG9uZSB3YW50cyBtYW55IHJlZmVyZW5j
ZXMgdG8gdGhlIFxwYXINCnNhbWUgY29uY2VwdCBpbiBzbGlnaHRseSBkaWZmZXJpbmcgZm9ybXMu
ICBUaGlzIGhlbHBzIGRpc2FtYmlndWF0ZSB0aGUgXHBhcg0KY29uY2VwdCAod2hpY2ggcmVzaWRl
cyBpbiBhIGxhcmdlIG11bHRpZGltZW5zaW9uYWwgc3BhY2UpLiBPbmUgd2FudHMgdG8gXHBhcg0K
cG9pbnQgdG8gdGhlIGNvbmNlcHQgYnkgInRyaWFuZ3VsYXRpb24iLiBUaGlzIG1ha2VzIGRvY3Vt
ZW50IG1haW50YW5lbmNlIFxwYXINCmRpZmZpY3VsdCBzaW5jZSBjaGFuZ2VzIGluIGEgY29uY2Vw
dCBjYW4gbm90IGJlIGVhc2lseSBwcm9wb2dhdGVkIFxwYXINCnRocm91Z2h0IHRoZSBkb2N1bWVu
dGF0aW9uLlxwYXINClxwYXINClRoZSB1c2Ugb2YgIm9uZSBwbGFjZSBvbmx5IiBhbmQgIm11bHRp
cGxlIGRlc2NyaXB0aW9ucyIgYXJlIGF0IHZhcmlhbmNlIFxwYXINCndpdGggZWFjaCBvdGhlciBh
bmQgeWV0IHRvIGhhdmUgc29tZW9uZSB1c2Ugd2hhdCB5b3UgaGF2ZSBjcmVhdGVkIGl0IGlzIFxw
YXINCm5lY2Vzc2FyeSB0byAidGVhY2giIHdoYXQgeW91IGhhdmUgZG9uZSwgdG8gY2FzdCB0aGUg
Y3JlYXRpb24gaW4gYXMgXHBhcg0KY2xlYXIgYW5kIGFzIGJyaWdodCBhIGxpZ2h0IGFzIHBvc3Np
YmxlLCBvdGhlcndpc2UgYWxsIG9mIHlvdXIgZWZmb3J0cyBccGFyDQptYXkgYmUgbG9zdCB0byB0
aGUgY2FzdWFsIHJlYWRlciB3aG8sIGp1c3QgbWlnaHQgYmUgYSBsYXJnZSBpbnZlc3RvciFccGFy
DQpccGFyDQpUaG91Z2h0cyBvbiBzb2x1dGlvbnNccGFyDQpvIEF1dG9tYXRpb246IGNyZWF0ZSBz
b21lIGJpdCBvZiBzb3R3YXJlIHRoYXQgdHJhY3RzIGFsbCBmb3J3YXJkIFxwYXINCnBvaW50ZXJz
IChkb2N1bWVudCBsaW5rcykgYW5kIGNyZWF0ZXMgaGlkZGVuIGJhY2twb2ludGVycyB0aGF0IGNh
biBiZSBccGFyDQp1c2VkIHRvIGFsZXJ0IHRoZSBkb2N1bWVudCB3cml0ZXIgd2hlbiBjaGFuZ2Vz
IGFyZSBtYWRlLiAgVGhpcyBhbGxvd3MgXHBhcg0KdGhlIHdyaXRlciB0byByZWV4YW1pbmUgdGhv
c2UgZm9yd2FyZCBwb2ludGVycyB0byBkZXRlcm1pbmUgaWYgdGhvc2UgXHBhcg0Kc2VjdGlvbnMg
bmVlZCB0byBoYXZlIHRoZWlyIHRleHQgY2hhbmdlZCBhbHNvLlxwYXINClxwYXINCm8gVXNlciBv
cmllbnRlZCBzdGF0aXN0aWNzOiBBbGxvdyBzb21lIHN1YnNldCBvZiB1c2VycyB0byBpbnNlcnQg
XHBhcg0KcXVlc3Rpb24gbWFya3MgaW50byBkb2N1bWVudGF0aW9uICJbP10iIHRoYXQgaXMgdGhl
biByZXR1cm5lZCB0byB0aGUgXHBhcg0KZG9jdW1lbnQgd3JpdGVycyBmb3IgY2xhcmlmaWNhdGlv
biBhbmQgZW1iZWxsaXNobWVudC5ccGFyDQpccGFyDQpvIFRpbWU6IEdvb2QgZG9jdW1lbnRhdGlv
biB3cml0aW5nIHRha2VzIHRpbWUgLi4uXHBhcg0KXHBhcg0KSW4gZ2VuZXJhbCBmb3IgdGhlIEJs
YWNrYm94IGRvY3VtZW50YXRpb24gaXQgaXMgbm90IHBvc3NpYmxlIHRvIHN0ZXAgXHBhcg0KaW50
byB0aGUgbWlkZGxlIG9mIGl0IGFuZCBleHRyYWN0IHdoYXQgb25lIG5lZWRzLiAgT25lIG11c3Qg
YWJzb3JiIHRoZSBccGFyDQp3aG9sZSBpbiBvcmRlciB0byB1c2UgYSBwYXJ0LiAgVGhpcyBpcyBu
b3QgYW4gb3B0aW1hbCB1c2Ugb2Ygb25lJ3MgdGltZS5ccGFyDQpccGFyDQpUaGVyZSBtdXN0IGJl
IHNvbWUgd2F5IHRoYXQgdGhlIEJsYWNrYm94IHVzZXIgY29tbXVuaXR5IGNhbiBoZWxwIE9taW5j
IFxwYXINCmltcHJvdmUgaXRzIGRvY3VtZW50YXRpb24uXHBhcg0KXHBhcg0KLURvdWdccGFyDQpc
cGFyDQpccGFyDQotLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLVxw
YXINClxwYXINClRvIHVuc3Vic2NyaWJlIGZyb20gdGhpcyBtYWlsaW5nIGxpc3QsIHNlbmQgYSBt
ZXNzYWdlIGNvbnRhaW5pbmcgdGhlIHdvcmQgInVuc3Vic2NyaWJlIiB0bzpccGFyDQogICBibGFj
a2JveC1yZXF1ZXN0QG9iZXJvbi5jaFxwYXINClxwYXINClRvIGdldCBhIGxpc3Qgb2YgdmFsaWQg
ZS1tYWlsIGNvbW1hbmRzIGFuZCBpbnN0cnVjdGlvbnMgb24gdGhlaXIgdXNhZ2UsIHNlbmQgYSBt
ZXNzYWdlIGNvbnRhaW5pbmcgdGhlIHdvcmQgImhlbHAiIHRvIHRoZSBhYm92ZSBhZGRyZXNzLlxw
YXINClxwYXINClNlbmQgYW55IHByb2JsZW0gcmVwb3J0cyBvciBxdWVzdGlvbnMgcmVsYXRlZCB0
byB0aGlzIGVtYWlsIGxpc3QgdG8gdGhlIGxpc3Qgb3duZXIgYXRccGFyDQogICBvd25lci1ibGFj
a2JveEBvYmVyb24uY2hccGFyDQpccGFyDQpDdXJyZW50IHBvc3RpbmcgcG9saWN5OlxwYXINClxw
YXINCmEpIFRvIHBvc3QgeW91IHNob3VsZCB1c2UgdGhlIHNhbWUgYWRkcmVzcyBieSB3aGljaCB5
b3UgYXJlIHN1YnNjcmliZWQgdG8gdGhlIG1haWxpbmcgbGlzdC4gVGhhdCB3YXksIHRoZSBsaXN0
IHNlcnZlciB3aWxsIHJlY29nbml6ZSB5b3UgYXMgc3Vic2NyaWJlciBhbmQgZm9yd2FyZCB5b3Vy
IHBvc3RpbmcgaW1tZWRpYXRlbHksIHdpdGhvdXQgY3JlYXRpbmcgYW55IG92ZXJoZWFkLlxwYXIN
ClxwYXINCmIpIElmLCBmb3Igc29tZSByZWFzb24sIHlvdSBjYW5ub3QgcG9zdCBmcm9tIHRoZSBh
ZGRyZXNzLCBieSB3aGljaCB5b3UgYXJlIHN1YnNjcmliZWQsIHlvdXIgbWVzc2FnZSB3aWxsIGJl
IG1vZGVyYXRlZCB0byBhdm9pZCBzcGFtLiBQbGVhc2UgdW5kZXJzdGFuZCB0aGF0IG1vZGVyYXRp
b24gd2lsbCBvZnRlbiBjYXVzZSBzb21lIGRlbGF5LCBpbiBwYXJ0aWN1bGFyIG92ZXIgd2Vla2Vu
ZHMgb3IgaG9seWRheXMuXHBhcg0KXHBhcg0KfQ==


----boundary-LibPST-iamunique-1950624066_-_---
Received on Sat Aug 02 2003 - 19:18:35 UTC