Documentation & Books

Graham Samuel graham.samuel at blueyonder.co.uk
Fri Jul 2 17:26:47 EDT 2004


On Thu, 01 Jul 2004 19:03:22 -0700, Richard Gaskin 
<ambassador at fourthworld.com> wrote:

>[snip]
>In a perfect world documentation could also have some form of multiple
>tracks, and we see at least a beginning effort in this direction on the
>front card of the Help stacks that invites you to select from choices
>that identify your background (the "Which describes you best?" options).
>
>But it could go a lot farther, given a little insight and a lot of sweat
>(pun intended, Monte <g>). You can lend a hand on the insight side of
>things:
>
>- What sort of software are you building, or would like to build, in Rev?
>
>- Have you built software before?  If so, with what tools/languages?
>
>- Which operating systems do you currently use regularly, and which ones
>do you plan to deploy to?
>
>- Aside from email and a browser, what are the three applications you
>use most often, or are most familiar with?
>
>- What was it about Rev that attracted you?
>
>- Do you find some portions of the documentation better suited for you
>than others?  If so, which ones are working for you?

One developer's take on all this, FWIW:

- I build visually-based interactive instructional software for children to 
use. Some of these are simple simulations and others are more abstract 
(like an introduction to spreadsheets). I don't include internet 
functionality yet, but I know that I will in the future.

- I've been building software for a long time, and doing xTalk for around 
10 years: I'm comfortable with the card-and-message metaphor.

- I use Macs (OS 9 and OSX) and PCs (Windows 98 and up, particularly XP) 
because my users do - I have no experience of Unix but then (so far) nor do 
my users - and I have no Unix development platform available anyway.

- personally the 3 key apps/app types I use are: photo-editing apps 
(Photoshop and Photoshop Elements, Graphic Converter etc); word processing 
(MS Word, though I dislike it, and sometimes AppleWorks); Excel. Of course 
I use a lot of utilities for compression, disk cutting etc.

- As to the RR docs, although I regard myself as an experienced xTalk 
developer, there are huge gaps in my knowledge not only of RR but of 
aspects of software technology itself (for example, networking is pretty 
much a closed book to me - my least favorite line in any documentation is 
"consult your network administrator" - and almost anything that has its 
origin in the world of Unix is a mystery to me). So I can't expect the RR 
documentation to clear up all the mystery in my technical life - 
nevertheless I do think things could be improved a bit.

I think the RR docs are excellent when it comes to the description of 
individual functions. The kind of difficulties I have with the docs are in 
getting the answers to fairly general questions like:

  "how do I do xxx?"
  "is there a way of doing xxx?"

(The difference between the two questions is that the first is asked when I 
have a pretty strong idea that RR can do the job **somehow** and in the 
second I don't even know if it has those features at all.)

For me, searching for an idea or a concept ("xxx") is the most difficult 
thing, and it's the reason that I come back to this ever-helpful list.

(This issue is not confined to RR's documentation - I have got lost in 
Photoshop or MS Word docs many and many a time, and have often just given 
up. For example: AFAIK there is no way of asking Photoshop "can I punch a 
transparent hole of arbitrary shape - drawn by me within the program - in 
an image and if so how?", or of asking MS Word "when I use a French copy of 
Word with an English dictionary, can I get left and right quotation marks 
automatically to replace apostrophes as in the English copy of the product, 
and if so how?" if there is, I've never found either answer.)

Clearly these problems are indeed very hard for the documenter to solve. My 
personal solution to this in the past was to read a complete manual for an 
app from cover to cover, and then hope that the concepts and terminology 
would stick in my brain sufficiently for me to have a good feel for the 
capabilities of the product and also to have a clue where to search when I 
needed detailed knowledge: the fashion for big, linear printed manuals 
(i.e. books) has receded, and I think that makes this approach less 
possible. I would really like to sit down and read the RR docs in this way 
but they are not IMHO structured to assist this.

I think this may be the origin of accusations of inadequacy, which are 
always countered by messages pointing out the huge volume of the existing 
RR docs - but all this says is that we have a very big haystack and 
admittedly some needle-searching tools, but not the kind that allow one to 
ask "is there a small pointed metal object in there, and where is it?". 
What we seem to need is more synonyms and ways of searching for concepts - 
a kind of thesaurus of the docs, if you like. I'm aware that this is only 
one aspect of possible improvement but for me it would be the most 
productive one.

Just a couple of Eurocents (or 1.34 British pence at the current rate of 
exchange).

Graham



---------------------------------------------------
Graham Samuel / The Living Fossil Co. / UK & France  




More information about the use-livecode mailing list