- Tutorial or Documentation?

From: [at]} <Bob>
Date: Tue, 22 Feb 2005 20:38:01 +0000

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

Hi,

>> A good tutorial will help, so let's try to put one together.

>> I have spent some time today looking around for the documentation ...

> So, what is wanted, a Documentation or a Tutorial? And then, at what level?

> To me the Documentation of the BB Library seems fairly good (anything
> might of course be improved).

Good user documentation these days is supposed to include, among other
things:

1. A graduated set of 'How to...' examples based around the tasks that
the reader wants to do

2. Concept information, describing the concepts used, and how they
relate to each other

3. Reference information, such as syntax.

Each of these can be further subdivided. It is considered important to
keep these things separate, but easy to find, e.g. by hyperlinking in
a 'See also' section of the topic.

One of the big problems with the BB documentation is that these things
are not kept separate. You can easily find yourself wading through 'stuff'
without finding what you want.

> As for a Tutorial or similar stuff there are the books by Stan Warford and
> Karlheinz Hug and there is a Tutorial (in german) I wrote (and still am
> writing). But I suppose all this is too basic as it more or less aims at
> beginners. Therefore I should like to know some details of what you have
> in mind.

I have Stan's book. It is intended for a course in software
engineering, and BB/CP is the vehicle for that course. To quote from
the preface "Its goal is to move the student through successively
higher levels of abstraction, starting with procedural programming and
concluding with OO programming".

I believe the we need something else besides. When I needed to learn a
bit of Java in a hurry I found the book 'Java Precisely' by Peter
Sestoft very useful. Its audience is people who already know how to
program, know what they want to do, and need to find out how to do it
in Java.

It's not exactly what I'm thinking about for our purposes. Still, the book
does some good things that we could do for BB/CP.

The book's layout works rather well for printing, but doesn't
work so well for the web. The left-hand page usually deals with
concept and syntax information, the right-hand page shows you
task-centered examples.

There is a PDF version of the book here:
http://www.dina.kvl.dk/~sestoft/javaprecisely/javaprecisely-online.pdf
The PDF doesn't include the last couple of chapters. This is unfortunate
because they show quite well what I mean. The chapters cover Collections &
Maps, and Input & Output.

I&O are pertinent to what we've been talking about here.

The chapter sections are task-based, with titles such as

21.7 Reading primitive data from a character stream: StreamTokenizer
21.8 Sequential Byte Input: InputStream
...

This is good because people don't come to their computer thinking 'I
want to use StreamTokenizer', they come to it thinking 'I want to read
data from an ascii text file', and the heading is a pretty good
indicator that this is where to find out how to do it.

In BB, starting from the Help menu, I have to open 3 documents before
I get to something with the title
"1 Creating, opening, closing, saving, and printing text documents
(Windows only)"
...and then it doesn't tell me what I wanted to know!

-- 
Regards,
 Bob
--- BlackBox
--- send subject HELP or UNSUBSCRIBE to blackbox{([at]})nowhere.xy----boundary-LibPST-iamunique-366619811_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzc1xmY2hhcnNldDAgQXJpYWw7fQ0Ke1xmMVxmbW9kZXJuIENvdXJpZXIgTmV3O30NCntcZjJc
Zm5pbFxmY2hhcnNldDIgU3ltYm9sO30NCntcZjNcZm1vZGVyblxmY2hhcnNldDAgQ291cmllciBO
ZXc7fX0NCntcY29sb3J0YmxccmVkMFxncmVlbjBcYmx1ZTA7XHJlZDBcZ3JlZW4wXGJsdWUyNTU7
fQ0KXHVjMVxwYXJkXHBsYWluXGRlZnRhYjM2MCBcZjBcZnMyMCBIaSxccGFyDQpccGFyDQo+PiAg
QSBnb29kIHR1dG9yaWFsIHdpbGwgaGVscCwgc28gbGV0J3MgdHJ5IHRvIHB1dCBvbmUgdG9nZXRo
ZXIuXHBhcg0KXHBhcg0KPj4gIEkgaGF2ZSBzcGVudCBzb21lIHRpbWUgdG9kYXkgbG9va2luZyBh
cm91bmQgZm9yIHRoZSBkb2N1bWVudGF0aW9uIC4uLlxwYXINClxwYXINCj4gU28sIHdoYXQgaXMg
d2FudGVkLCBhIERvY3VtZW50YXRpb24gb3IgYSBUdXRvcmlhbD8gQW5kIHRoZW4sIGF0IHdoYXQg
bGV2ZWw/XHBhcg0KXHBhcg0KPiBUbyBtZSB0aGUgRG9jdW1lbnRhdGlvbiBvZiB0aGUgQkIgTGli
cmFyeSBzZWVtcyBmYWlybHkgZ29vZCAoYW55dGhpbmdccGFyDQo+IG1pZ2h0IG9mIGNvdXJzZSBi
ZSBpbXByb3ZlZCkuXHBhcg0KXHBhcg0KR29vZCB1c2VyIGRvY3VtZW50YXRpb24gdGhlc2UgZGF5
cyBpcyBzdXBwb3NlZCB0byBpbmNsdWRlLCBhbW9uZyBvdGhlclxwYXINCnRoaW5nczpccGFyDQpc
cGFyDQoxLiBBIGdyYWR1YXRlZCBzZXQgb2YgJ0hvdyB0by4uLicgZXhhbXBsZXMgYmFzZWQgYXJv
dW5kIHRoZSB0YXNrcyB0aGF0XHBhcg0KdGhlIHJlYWRlciB3YW50cyB0byBkb1xwYXINClxwYXIN
CjIuIENvbmNlcHQgaW5mb3JtYXRpb24sIGRlc2NyaWJpbmcgdGhlIGNvbmNlcHRzIHVzZWQsIGFu
ZCBob3cgdGhleVxwYXINCnJlbGF0ZSB0byBlYWNoIG90aGVyXHBhcg0KXHBhcg0KMy4gUmVmZXJl
bmNlIGluZm9ybWF0aW9uLCBzdWNoIGFzIHN5bnRheC5ccGFyDQpccGFyDQpFYWNoIG9mIHRoZXNl
IGNhbiBiZSBmdXJ0aGVyIHN1YmRpdmlkZWQuIEl0IGlzIGNvbnNpZGVyZWQgaW1wb3J0YW50IHRv
XHBhcg0Ka2VlcCB0aGVzZSB0aGluZ3Mgc2VwYXJhdGUsIGJ1dCBlYXN5IHRvIGZpbmQsIGUuZy4g
YnkgaHlwZXJsaW5raW5nIGluXHBhcg0KYSAnU2VlIGFsc28nIHNlY3Rpb24gb2YgdGhlIHRvcGlj
LlxwYXINClxwYXINCk9uZSBvZiB0aGUgYmlnIHByb2JsZW1zIHdpdGggdGhlIEJCIGRvY3VtZW50
YXRpb24gaXMgdGhhdCB0aGVzZSB0aGluZ3NccGFyDQphcmUgbm90IGtlcHQgc2VwYXJhdGUuIFlv
dSBjYW4gZWFzaWx5IGZpbmQgeW91cnNlbGYgd2FkaW5nIHRocm91Z2ggJ3N0dWZmJ1xwYXINCndp
dGhvdXQgZmluZGluZyB3aGF0IHlvdSB3YW50LlxwYXINClxwYXINCj4gQXMgZm9yIGEgVHV0b3Jp
YWwgb3Igc2ltaWxhciBzdHVmZiB0aGVyZSBhcmUgdGhlIGJvb2tzIGJ5IFN0YW4gV2FyZm9yZCBh
bmRccGFyDQo+IEthcmxoZWlueiBIdWcgYW5kIHRoZXJlIGlzIGEgVHV0b3JpYWwgKGluIGdlcm1h
bikgSSB3cm90ZSAoYW5kIHN0aWxsIGFtXHBhcg0KPiB3cml0aW5nKS4gQnV0IEkgc3VwcG9zZSBh
bGwgdGhpcyBpcyB0b28gYmFzaWMgYXMgaXQgbW9yZSBvciBsZXNzIGFpbXMgYXRccGFyDQo+IGJl
Z2lubmVycy4gVGhlcmVmb3JlIEkgc2hvdWxkIGxpa2UgdG8ga25vdyBzb21lIGRldGFpbHMgb2Yg
d2hhdCB5b3UgaGF2ZVxwYXINCj4gaW4gbWluZC5ccGFyDQpccGFyDQpJIGhhdmUgU3RhbidzIGJv
b2suIEl0IGlzIGludGVuZGVkIGZvciBhIGNvdXJzZSBpbiBzb2Z0d2FyZVxwYXINCmVuZ2luZWVy
aW5nLCBhbmQgQkIvQ1AgaXMgdGhlIHZlaGljbGUgZm9yIHRoYXQgY291cnNlLiBUbyBxdW90ZSBm
cm9tXHBhcg0KdGhlIHByZWZhY2UgIkl0cyBnb2FsIGlzIHRvIG1vdmUgdGhlIHN0dWRlbnQgdGhy
b3VnaCBzdWNjZXNzaXZlbHlccGFyDQpoaWdoZXIgbGV2ZWxzIG9mIGFic3RyYWN0aW9uLCBzdGFy
dGluZyB3aXRoIHByb2NlZHVyYWwgcHJvZ3JhbW1pbmcgYW5kXHBhcg0KY29uY2x1ZGluZyB3aXRo
IE9PIHByb2dyYW1taW5nIi5ccGFyDQpccGFyDQpJIGJlbGlldmUgdGhlIHdlIG5lZWQgc29tZXRo
aW5nIGVsc2UgYmVzaWRlcy4gV2hlbiBJIG5lZWRlZCB0byBsZWFybiBhXHBhcg0KYml0IG9mIEph
dmEgaW4gYSBodXJyeSBJIGZvdW5kIHRoZSBib29rICdKYXZhIFByZWNpc2VseScgYnkgUGV0ZXJc
cGFyDQpTZXN0b2Z0IHZlcnkgdXNlZnVsLiBJdHMgYXVkaWVuY2UgaXMgcGVvcGxlIHdobyBhbHJl
YWR5IGtub3cgaG93IHRvXHBhcg0KcHJvZ3JhbSwga25vdyB3aGF0IHRoZXkgd2FudCB0byBkbywg
YW5kIG5lZWQgdG8gZmluZCBvdXQgaG93IHRvIGRvIGl0XHBhcg0KaW4gSmF2YS5ccGFyDQpccGFy
DQpJdCdzIG5vdCBleGFjdGx5IHdoYXQgSSdtIHRoaW5raW5nIGFib3V0IGZvciBvdXIgcHVycG9z
ZXMuIFN0aWxsLCB0aGUgYm9va1xwYXINCmRvZXMgc29tZSBnb29kIHRoaW5ncyB0aGF0IHdlIGNv
dWxkIGRvIGZvciBCQi9DUC5ccGFyDQpccGFyDQpUaGUgYm9vaydzIGxheW91dCB3b3JrcyByYXRo
ZXIgd2VsbCBmb3IgcHJpbnRpbmcsIGJ1dCBkb2Vzbid0XHBhcg0Kd29yayBzbyB3ZWxsIGZvciB0
aGUgd2ViLiBUaGUgbGVmdC1oYW5kIHBhZ2UgdXN1YWxseSBkZWFscyB3aXRoXHBhcg0KY29uY2Vw
dCBhbmQgc3ludGF4IGluZm9ybWF0aW9uLCB0aGUgcmlnaHQtaGFuZCBwYWdlIHNob3dzIHlvdVxw
YXINCnRhc2stY2VudGVyZWQgZXhhbXBsZXMuXHBhcg0KXHBhcg0KVGhlcmUgaXMgYSBQREYgdmVy
c2lvbiBvZiB0aGUgYm9vayBoZXJlOlxwYXINCmh0dHA6Ly93d3cuZGluYS5rdmwuZGsvfnNlc3Rv
ZnQvamF2YXByZWNpc2VseS9qYXZhcHJlY2lzZWx5LW9ubGluZS5wZGZccGFyDQpUaGUgUERGIGRv
ZXNuJ3QgaW5jbHVkZSB0aGUgbGFzdCBjb3VwbGUgb2YgY2hhcHRlcnMuIFRoaXMgaXMgdW5mb3J0
dW5hdGVccGFyDQpiZWNhdXNlIHRoZXkgc2hvdyBxdWl0ZSB3ZWxsIHdoYXQgSSBtZWFuLiBUaGUg
Y2hhcHRlcnMgY292ZXIgQ29sbGVjdGlvbnMgJlxwYXINCk1hcHMsIGFuZCBJbnB1dCAmIE91dHB1
dC5ccGFyDQpccGFyDQpJJk8gYXJlIHBlcnRpbmVudCB0byB3aGF0IHdlJ3ZlIGJlZW4gdGFsa2lu
ZyBhYm91dCBoZXJlLlxwYXINClxwYXINClRoZSBjaGFwdGVyIHNlY3Rpb25zIGFyZSB0YXNrLWJh
c2VkLCB3aXRoIHRpdGxlcyBzdWNoIGFzXHBhcg0KXHBhcg0KMjEuNyBSZWFkaW5nIHByaW1pdGl2
ZSBkYXRhIGZyb20gYSBjaGFyYWN0ZXIgc3RyZWFtOiBTdHJlYW1Ub2tlbml6ZXJccGFyDQoyMS44
IFNlcXVlbnRpYWwgQnl0ZSBJbnB1dDogSW5wdXRTdHJlYW1ccGFyDQouLi5ccGFyDQpccGFyDQpU
aGlzIGlzIGdvb2QgYmVjYXVzZSBwZW9wbGUgZG9uJ3QgY29tZSB0byB0aGVpciBjb21wdXRlciB0
aGlua2luZyAnSVxwYXINCndhbnQgdG8gdXNlIFN0cmVhbVRva2VuaXplcicsIHRoZXkgY29tZSB0
byBpdCB0aGlua2luZyAnSSB3YW50IHRvIHJlYWRccGFyDQpkYXRhIGZyb20gYW4gYXNjaWkgdGV4
dCBmaWxlJywgYW5kIHRoZSBoZWFkaW5nIGlzIGEgcHJldHR5IGdvb2RccGFyDQppbmRpY2F0b3Ig
dGhhdCB0aGlzIGlzIHdoZXJlIHRvIGZpbmQgb3V0IGhvdyB0byBkbyBpdC5ccGFyDQpccGFyDQpJ
biBCQiwgc3RhcnRpbmcgZnJvbSB0aGUgSGVscCBtZW51LCBJIGhhdmUgdG8gb3BlbiAzIGRvY3Vt
ZW50cyBiZWZvcmVccGFyDQpJIGdldCB0byBzb21ldGhpbmcgd2l0aCB0aGUgdGl0bGVccGFyDQoi
MVwnYTBDcmVhdGluZyxcJ2Ewb3BlbmluZyxcJ2EwY2xvc2luZyxcJ2Ewc2F2aW5nLFwnYTBhbmRc
J2EwcHJpbnRpbmdcJ2EwdGV4dFwnYTBkb2N1bWVudHNccGFyDQooV2luZG93c1wnYTBvbmx5KSJc
cGFyDQouLi5hbmQgdGhlbiBpdCBkb2Vzbid0IHRlbGwgbWUgd2hhdCBJIHdhbnRlZCB0byBrbm93
IVxwYXINClxwYXINCi0tIFxwYXINClJlZ2FyZHMsXHBhcg0KIEJvYlxwYXINClxwYXINCi0tLSBC
bGFja0JveFxwYXINCi0tLSBzZW5kIHN1YmplY3QgSEVMUCBvciBVTlNVQlNDUklCRSB0byBibGFj
a2JveEBvYmVyb24uY2h9fQBoDQpYLVByaW9y
----boundary-LibPST-iamunique-366619811_-_---

Received on Tue Feb 22 2005 - 21:38:01 UTC