----boundary-LibPST-iamunique-732013956_-_-
Content-type: text/plain
Bob,
Looks reasonable but the example lacks the 'coherence' that is needed to
tie parts together. There needs to be a running dialog that relates a
specific topic to the bigger picture of BlackBox else the topic is just
a fragment that floats isolated from other parts.
What I want is a quick lookup of how to do something but also the why it
is done that way within the context of BlackBox.
-Doug
Bob Walkden wrote:
> Hi,
>
>
>>>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.
>
>
> I have not had enough time so far to try and write an example of the
> type of documentation that I've been suggesting.
>
> However, today I found a good example which illustrates exactly the
> topic-based style, and shows how to program for a framework:
> http://developer.apple.com/documentation/Cocoa/index.html
>
> This is precisely the type of documentation that I believe Blackbox
> needs.
>
> I think it is feasible for a small group of people to produce
> documentation like this because the individual topics are small. The
> format is consistent and easy to follow. The indexing, searching and
> retrieval is efficient.
>
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy
----boundary-LibPST-iamunique-732013956_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEJvYixccGFyDQpMb29rcyByZWFzb25hYmxlIGJ1
dCB0aGUgZXhhbXBsZSBsYWNrcyB0aGUgJ2NvaGVyZW5jZScgdGhhdCBpcyBuZWVkZWQgdG8gXHBh
cg0KdGllIHBhcnRzIHRvZ2V0aGVyLiAgVGhlcmUgbmVlZHMgdG8gYmUgYSBydW5uaW5nIGRpYWxv
ZyB0aGF0IHJlbGF0ZXMgYSBccGFyDQpzcGVjaWZpYyB0b3BpYyB0byB0aGUgYmlnZ2VyIHBpY3R1
cmUgb2YgQmxhY2tCb3ggZWxzZSB0aGUgdG9waWMgaXMganVzdCBccGFyDQphIGZyYWdtZW50IHRo
YXQgZmxvYXRzIGlzb2xhdGVkIGZyb20gb3RoZXIgcGFydHMuXHBhcg0KXHBhcg0KV2hhdCBJIHdh
bnQgaXMgYSBxdWljayBsb29rdXAgb2YgaG93IHRvIGRvIHNvbWV0aGluZyBidXQgYWxzbyB0aGUg
d2h5IGl0IFxwYXINCmlzIGRvbmUgdGhhdCB3YXkgd2l0aGluIHRoZSBjb250ZXh0IG9mIEJsYWNr
Qm94LlxwYXINClxwYXINCi1Eb3VnXHBhcg0KXHBhcg0KQm9iIFdhbGtkZW4gd3JvdGU6XHBhcg0K
PiBIaSxccGFyDQo+IFxwYXINCj4gXHBhcg0KPj4+Tm93LCBob3cgZG8gd2UgbW92ZSBmb3J3YXJk
P1xwYXINCj4gXHBhcg0KPiBccGFyDQo+Pkkgd291bGQgbGlrZSB0byB0cnkgYW5kIHdyaXRlIGFu
IGV4YW1wbGUgb2Ygd2hhdCBJIG1lYW4uIEkgYW0gdHJ5aW5nXHBhcg0KPj50byB0aGluayBvZiBz
b21ldGhpbmcgbWFuYWdlYWJsZSBhcyBhbiBleGFtcGxlLiBCdXQgZGVzcGl0ZSB0aGUgbG9uZ1xw
YXINCj4+d2Vla2VuZCBJIGhhdmUgYW4gYXdmdWwgbG90IG9mIHdvcmsgdG8gZG8sIHNvIEkgY2Fu
J3QgcHJvbWlzZSBhbnl0aGluZy5ccGFyDQo+IFxwYXINCj4gXHBhcg0KPiBJIGhhdmUgbm90IGhh
ZCBlbm91Z2ggdGltZSBzbyBmYXIgdG8gdHJ5IGFuZCB3cml0ZSBhbiBleGFtcGxlIG9mIHRoZVxw
YXINCj4gdHlwZSBvZiBkb2N1bWVudGF0aW9uIHRoYXQgSSd2ZSBiZWVuIHN1Z2dlc3RpbmcuXHBh
cg0KPiBccGFyDQo+IEhvd2V2ZXIsIHRvZGF5IEkgZm91bmQgYSBnb29kIGV4YW1wbGUgd2hpY2gg
aWxsdXN0cmF0ZXMgZXhhY3RseSB0aGVccGFyDQo+IHRvcGljLWJhc2VkIHN0eWxlLCBhbmQgc2hv
d3MgaG93IHRvIHByb2dyYW0gZm9yIGEgZnJhbWV3b3JrOlxwYXINCj4gaHR0cDovL2RldmVsb3Bl
ci5hcHBsZS5jb20vZG9jdW1lbnRhdGlvbi9Db2NvYS9pbmRleC5odG1sXHBhcg0KPiBccGFyDQo+
IFRoaXMgaXMgcHJlY2lzZWx5IHRoZSB0eXBlIG9mIGRvY3VtZW50YXRpb24gdGhhdCBJIGJlbGll
dmUgQmxhY2tib3hccGFyDQo+IG5lZWRzLlxwYXINCj4gXHBhcg0KPiBJIHRoaW5rIGl0IGlzIGZl
YXNpYmxlIGZvciBhIHNtYWxsIGdyb3VwIG9mIHBlb3BsZSB0byBwcm9kdWNlXHBhcg0KPiBkb2N1
bWVudGF0aW9uIGxpa2UgdGhpcyBiZWNhdXNlIHRoZSBpbmRpdmlkdWFsIHRvcGljcyBhcmUgc21h
bGwuIFRoZVxwYXINCj4gZm9ybWF0IGlzIGNvbnNpc3RlbnQgYW5kIGVhc3kgdG8gZm9sbG93LiBU
aGUgaW5kZXhpbmcsIHNlYXJjaGluZyBhbmRccGFyDQo+IHJldHJpZXZhbCBpcyBlZmZpY2llbnQu
XHBhcg0KPiBccGFyDQpccGFyDQotLS0gQmxhY2tCb3hccGFyDQotLS0gc2VuZCBzdWJqZWN0IEhF
TFAgb3IgVU5TVUJTQ1JJQkUgdG8gYmxhY2tib3hAb2Jlcm9uLmNofX0AEBmdbgDdAQ9UAg==
----boundary-LibPST-iamunique-732013956_-_---
Received on Wed Apr 06 2005 - 02:31:57 UTC