[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
_______________________________________________ use-revolution mailing list [EMAIL PROTECTED] http://lists.runrev.com/mailman/listinfo/use-revolution
