The Icon Bar: General: How do I wrote manual?
| |
How do I wrote manual? |
| |
swirlythingy (16:37 21/5/2011)
Col (11:44 22/5/2011)
arawnsley (13:05 22/5/2011)
swirlythingy (13:26 22/5/2011)
VincceH (14:10 22/5/2011)
swirlythingy (16:09 22/5/2011)
filecore (18:15 22/5/2011)
arawnsley (21:04 22/5/2011)
swirlythingy (23:32 22/5/2011)
filecore (23:40 22/5/2011)
swirlythingy (17:38 23/5/2011)
filecore (18:02 23/5/2011)
Acornut (19:15 23/5/2011)
trevj (21:48 23/5/2011)
swirlythingy (17:56 15/6/2011)
trevj (20:12 15/6/2011)
|
| |
|
Martin Bazley |
Message #117790, posted by swirlythingy at 16:37, 21/5/2011 |
Posts: 460
|
I'm at a loss.
I have this marvellous new, all-singing, all-dancing, bugfixed, feature-packed, and unreleased version of MBBack sitting on my hard drive. It's technically complete and stable, and has been for weeks.
Trouble is, the most major modifications have been to the source file interpreter. This has been completely refactored, orthagonised, rationalised, and in some places completely rewritten, and although old source files are still more or less compatible (with one major exception), the effect has been to render all of the current documentation almost completely obsolete.
This is a particular problem, because the source file syntax section of the manual was always the bit I was least happy with. It was an unstructured mass of contradictions, dating from when I'd just barely managed to get the thing working and wasn't 100% sure what certain combinations of commands would do to it myself.
However, with the refactor, the code is a lot saner than it used to be, and should be free of all undefined and unintuitive behaviours, and, in theory, this should make the manual easier both to write and to understand.
But I can't do it.
I'm useless at explaining things and always have been. If you asked me to explain General Relativity you'd probably come away twenty minutes later vaguely wondering why I seemed so into rubber sheets and huge masses. Ask me to describe a moderately complex tree structure in which all levels are optional and you only needed to list the things you didn't want, and you'll probably get something like the current MBBack help file. Except this time it'll be worse, because although the manual still won't make any sense, the code behind it will, so the disparity will be a lot more apparent.
So, I need to poll potential users, which is where you lot come in.
What method of learning would you find most helpful?
Should I abandon all pretence of user-friendliness and go into it expecting my audience to have a working knowledge of the concept of local variables, recursive procedures, and file structures?
Should I explain by example, giving as many situations as I can think of and the syntax which could be used to resolve them, each time introducing a new feature?
Should I simply treat all features as discrete entities, and trust users to be able to fit them together to produce logical, if not entirely obvious, combo-attacks?
A bit of background, for the benefit of those who don't read comp.sys.acorn.announce:
The interpreter works much like a compiler, in that it takes a set of instructions in a maintainable language and converts them into a machine-readable code. In this case, the aim is to produce a file full of filenames and file-specific options, from which a random line can then be selected as the new backdrop image, without having to know anything about the contents of other lines.
The features of the maintainable language now include: take a directory and scan its contents for valid images; take a directory and scan all its subdirectories as well; treat an image as a directory with sprite names as the files inside it; automatically recurse into said images. Each level of the tree optionally contains a list of pathnames relative to the pathname of the parent node, which denote exceptions to how files beneath the parent should be treated (centred instead of scaled, left out of the compiled list because it's the wrong shape, etc.). Depending on whether a certain flag is set in the parent, resolved pathnames which are earmarked for inclusion in this list may be the only files included, or after it's read the last of the level, the program will go off and automatically scan everything located beneath the parent on the hard disc, and include it with its settings set to the parent's. This of course may be restricted to only one level beneath, or all subdirectories, and may include sprites within the files themselves. In addition, various display and interpretation options local to this list and all levels beneath it can be set (including whether to search subdirectories, etc.). The relative pathnames specifically mentioned in the list itself can of course also include sprite names as well as filenames.
As you can see, there are rather a lot of possible combinations of a relatively small set of features, and I haven't a clue what people will find difficult to understand (but I know I'm not putting the above paragraph in the help file). The whole point of the manual is to make it easy - I don't want to turn off all but those who would probably find it easier just to open up the (reasonably well-commented) !RunImage instead.
Anyone have experience in writing this sort of thing? Anyone have experience in reading it? I really don't know where I should start... |
| |
 [ Log in to reply ] |
| |
|
Colin Cartmell-Browne |
Message #117794, posted by Col at 11:44, 22/5/2011, in reply to message #117790 |
Member
Posts: 89
|
Should I abandon all pretence of user-friendliness and go into it expecting my audience to have a working knowledge of the concept of local variables, recursive procedures, and file structures?
Personally I think it's always best to keep things as simple as possible. If you assume too much knowledge then you'll only put off any potential users who may not have your particular technical skills/experience whereas more experienced users can ignore any pieces of information they already know. You could possible include a glossary of relevant terms rather than include all of the information within the main part of the documentation.
Should I explain by example, giving as many situations as I can think of and the syntax which could be used to resolve them, each time introducing a new feature?
Should I simply treat all features as discrete entities, and trust users to be able to fit them together to produce logical, if not entirely obvious, combo-attacks?
The problem is that if you try to think of all possible scenarios someone is almost certainly going to come up with something you didn't think of. I'd make the features the key part of the documentation, explain what each one does and how it works in combination with other features of the software. Towards the end of the documentation you could include some examples of the types of scenarios you expect to come up and which of the features can be used to solve those scenarios. with possibly a link to a webpage/wiki where you can update scenarios which hadn't come up at time of publication.
Of course this is just my opinion and expect someone will suggest something entirely different! |
| |
[ Log in to reply ] |
| |
|
Andrew Rawnsley |
Message #117795, posted by arawnsley at 13:05, 22/5/2011, in reply to message #117790 |
R-Comp chap
Posts: 594
|
Whilst a list of commands etc is useful, assuming that users can put them together without at least *some* worked examples is dangerous. I know that with DataPower, the sheer volume of programming commands doesn't really provide the user with much of a clue as to how to achieve things.
The best way to do it (I'd suggest) is to show (short) examples of use with each command, and include an introduction which gives some sample scripts and an explanation of what they do and why.
This methodology allows beginners to try the sample scripts (which hopefully do things they want anyway) and use the command glossary to see examples of things they could add to the sample apps.
However, as with all programming, the user ultimately has to have the kind of mind that can put it all together - if they don't, then I suspect no amount of documentation will get them there. |
| |
[ Log in to reply ] |
| |
|
Martin Bazley |
Message #117796, posted by swirlythingy at 13:26, 22/5/2011, in reply to message #117795 |
Posts: 460
|
The main problem with giving useful, as well as illustrative, examples in the context of a backdrop chooser is that it relies on one's users having exactly the same hard disc layout as oneself - otherwise nothing works without at least some modification.
I mean, I could theoretically quote something like this:
fADFS::4.$.Images
-
+00-49
++
--key00-24
--key25-49
+50-99
++
--key50-74
--key75-99
...but while it should hopefully be fairly obvious what that does (generate a list of everything called sa##), I don't even think everyone has a computer with that directory on it. After that, the only thing you can really think about are things like Resources:$.Resources.Wimp, which has little practical use.
So, is the consensus something like: treat all features individually, with examples to illustrate common usage? The main problem with that, as I said, is that several features can be combined, and it may be asking a bit much to expect users to draw logical conclusions. Coming up with such combo-examples is difficult as well, not least because most of them have no common practical use, but they may well fit someone's particular circumstances.
[Edited by swirlythingy at 23:17, 22/5/2011] |
| |
[ Log in to reply ] |
| |
|
VinceH |
Message #117797, posted by VincceH at 14:10, 22/5/2011, in reply to message #117796 |
 Lowering the tone since the dawn of time
Posts: 1600
|
The main problem with giving useful, as well as illustrative, examples in the context of a backdrop chooser is that it relies on one's users having exactly the same hard disc layout as oneself - otherwise nothing works without at least some modification. That's the same with anything in which the user can specify an actual path in some way - for example WebChange's Script language. You simply explain that the given path is an example, and that the user needs to change it as appropriate; that's all you can ever do.
I mean, I could theoretically quote something like this:
ADFS::4.$.Images
-
+00-49
++
--key00-24
--key25-49
+50-99
++
--key50-74
--key75-99
...but while it should hopefully be fairly obvious what that does Keep hoping! 
(generate a list of everything called sa##), I'll take your word for it.
Perhaps I'm just in the wrong frame of mind this morning (I haven't been able to turn my mind to anything constructive today*), or perhaps it's because I've never used your backdrop changer, but I wouldn't have guessed that's what it does from looking at the script - and even now you've said that's what it does, I really can't see how.
* I can't even concentrate on reading, so I might just write the day off and spend the rest of it watching DVDs or something |
| |
[ Log in to reply ] |
| |
|
Martin Bazley |
Message #117798, posted by swirlythingy at 16:09, 22/5/2011, in reply to message #117797 |
Posts: 460
|
More precisely, it means:
In the directory "Images", examine only the directories called "00-49" and "50-99", and take every valid file beneath those two, except, in the former case, "key00-24" and "key25-49", and, in the latter case, "key50-74" and "key75-99".
Problem is, that just scratches the surface of the feature list, and I can't think of any other even semi-universal examples. |
| |
[ Log in to reply ] |
| |
|
Jason Togneri |
Message #117799, posted by filecore at 18:15, 22/5/2011, in reply to message #117798 |
Posts: 3867
|
More precisely, it means: Perhaps if you gave the example some posts up, but then commented it in the verbose fashion given in the previous post, you could use a non-existent file structure (that not all users would have) but the comments alongside each line would put the example into a practical context that they could then modify to suit their own file structure. Thus, it would still be approachable by anyone with the ability to relate an example to their own situation - which still isn't everyone, but it's more people than if you went with a more technical example. |
| |
[ Log in to reply ] |
| |
|
Andrew Rawnsley |
Message #117800, posted by arawnsley at 21:04, 22/5/2011, in reply to message #117798 |
R-Comp chap
Posts: 594
|
I think if you include that explanation (possibly as comments in the code, of your language supports that), you've pretty much cracked it. You could also include a screenshot or two of the folders in question, so that users can see what is going on, even if they don't have exactly those folders. |
| |
[ Log in to reply ] |
| |
|
Martin Bazley |
Message #117801, posted by swirlythingy at 23:32, 22/5/2011, in reply to message #117800 |
Posts: 460
|
I've just realised my example above had a mistake in it and would have errored! There was supposed to have been an 'f' in front of the 'ADFS', which is a display pseudo-setting trapped by MBBack and interpreted as 'scale picture to fill whole Pinboard, then centre the result'.
So, was that explanation clear enough, then? I'm still not sure just how deep I should go into the minutiae, and how much I can trust intuition. I've tried to make the language orthagonal and intuitive (and, as of the new version, it's much more so than previously!), but I'm the worst possible judge of what's obvious.
I still don't know how I'm going to raise the subject of file-specific configuration, which is local to each level of the tree (and below). Take the following:
# This means from now on preserve all mask data
#PlotMask
# The 'S' means 'Stretched'
SADFS::4.$.Pics
# + means additionally include everything not in the list with the parent settings
+
+A pic1
+F pic2
-SubDir3.foo14
# This turns off 'PlotMask', locally in and beneath this level and until the end of the list (at which point parent settings are restored)
##WhiteBack
+pic546
Which means:- Scale Pics.pic1 until it touches either dimension of the Pinboard, taking account of the mask, if any.
- Scale Pics.pic2 until it is at least as big as the Pinboard - distinct from 'A' in that some of the picture may be cropped. Also take account of mask.
- Stretch Pics.pic546, removing its mask and replacing it with a white background.
- For all other files beneath Pics (except Pics.SubDir3.foo14, which is ignored), apply the parent settings - in this case, stretched with the mask preserved.
Did you follow that? I bet you didn't. I still don't have a clue what I'm doing. |
| |
[ Log in to reply ] |
| |
|
Jason Togneri |
Message #117802, posted by filecore at 23:40, 22/5/2011, in reply to message #117801 |
Posts: 3867
|
Thinking in particular of file-specific config, which as you say is local, but I suppose this also applies to a broader context: you don't have to distinguish between minutiae and intuition.
Basically, IMHO you're taking the wrong tack on this. You should imply that all commands are repeated verbatim except where explicitly stated by an explanatory comment. Thus, you're essentially commenting on sections which are variables, and which the end-user would therefore have to be aware of.
You had it right with yout first couple of comments, but then you get a little esoteric. How much do you expect your user to know? ##WhiteBack is probably fairly self-explanatory once the user mentally expands it, but it does require a little thought. It is indeed a careful balance between mollycoddling an idiot beginner and arrogant assumption that every user is a pro coder, but if you distinguish between what is common and what is context-specific, that should be enough for a moderately intelligent end-user to work out and extrapolate into their own environment, based on a couple of contextual examples. |
| |
[ Log in to reply ] |
| |
|
Martin Bazley |
Message #117803, posted by swirlythingy at 17:38, 23/5/2011, in reply to message #117802 |
Posts: 460
|
OK... now I'm the one who has absolutely no idea what has just been said.
What do you mean by "all commands are repeated verbatim", and what's the definition of "common" and "context-specific"? |
| |
[ Log in to reply ] |
| |
|
Jason Togneri |
Message #117804, posted by filecore at 18:02, 23/5/2011, in reply to message #117803 |
Posts: 3867
|
I have no idea, I just make this crap up as I go along. |
| |
[ Log in to reply ] |
| |
|
Blind Moose |
Message #117805, posted by Acornut at 19:15, 23/5/2011, in reply to message #117804 |
 No-eye-deer (No Idea)
Posts: 487
|
I have no idea, I just make this crap up as I go along. Ah Ha! The infamous author of all those "Information for Dummies" books, unmasked!  |
| |
[ Log in to reply ] |
| |
|
Trevor Johnson |
Message #117806, posted by trevj at 21:48, 23/5/2011, in reply to message #117803 |
Member
Posts: 660
|
There are a couple of potentially useful links at Wikipedia. |
| |
[ Log in to reply ] |
| |
|
Martin Bazley |
Message #118030, posted by swirlythingy at 17:56, 15/6/2011, in reply to message #117795 |
Posts: 460
|
Well, I finally finished it!
The approach I went with in the end was something like this:
The best way to do it (I'd suggest) is to show (short) examples of use with each command, and include an introduction which gives some sample scripts and an explanation of what they do and why.
This methodology allows beginners to try the sample scripts (which hopefully do things they want anyway) and use the command glossary to see examples of things they could add to the sample apps. Thanks for your help, everyone. Let me know if I made any stupid mistakes or didn't adequately explain a certain point. |
| |
[ Log in to reply ] |
| |
|
Trevor Johnson |
Message #118031, posted by trevj at 20:12, 15/6/2011, in reply to message #118030 |
Member
Posts: 660
|
Congratulations, Martin! I'm looking forward to trying this out some time. |
| |
[ Log in to reply ] |
| |
|
The Icon Bar: General: How do I wrote manual? |
