Band In A Box Manual - 12/04/21 01:36 PM
I thought I'd start a thread here with what I hope are constructive thoughts on the manuals, and ideas on how to make them easier to read and understand.
I'd earlier said in a thread started by malevans that I thought the manual was "cluttered", so I thought I should expand on that. Someone also mentioned the Reaper manual as quite a good example, though there are several others. Reaper, BTW, have a footnote on each page with a link to LULU.com who are one of several organisations that offer printed manuals on demand.
Some of that "clutter" is due to probable documentation conventions, which could be made more concise by declaring those conventions somewhere, possibly right near the start of the manual. For example the convention used for buttons: [Style] if explicitly defined in the conventions as a button, would negate the need within the body text to say "using the [Style] button". Icons are good, though can be confusing when there are multiple GUI styles available, e.g., the monochrome or coloured icons styles.
Similarly predefine font meanings. Generally, the fewer fonts the better, though in manuals for software, "fewer" is usually quite hard to achieve.
Similarly sequences of actions. I personally tend to use, e.g., File->Load_Style_Special->"filename"->[OK] to describe a sequence. I note that the | symbol is used in some places, which is OK (though for me | means "or"). This would reduce the desire/need to use verbal descriptions.
A common problem in the manuals for many applications is that a section describing something, e.g., perhaps the MIDI Settings, without telling the user, right at that point, how to get to that something. Incidentally, I picked that from the index, expecting to see the instructions for setting up a MIDI device.
During a main explanation, focus upon a "preferred" way to do something, offering "other ways to do this" as a separate item. Then each of the sequences can be described completely in and of itself.
Hierarchically numbering every header helps navigation, and also helps suggestions or error-reports to focus closely to the correct location. In my specifications, where I need to incorporate similar changes, I usually number every paragraph, though most word-processors seem appallingly bad at doing that properly. A fall-back I've used is to number every line on every page, which is something with which most word-processors seem more adept. "Changed" indicators are often useful if the tools support them. You almost certainly already do that internally; it can be less useful in a published document, as it add clutter.
White-space, including indenting, helps quick navigation by eye and usually makes the document look nicer. On a .pdf document, white-space costs nothing. Printed it can, but better clarity can often reduce the number of pages needed.
It's worth looking at the keyboard shortcuts section and considering how an additional line before each sub-header and indenting the keys from that header would make it easier to use. At present, it isn't easy to pick out the subheadings from the keys. It's worth noting that many publishers consider the white-space to be the most important part of a document, yet we ordinary folk tend to forget it, particularly when close to a particular text. It can pay sometimes, just to hold a page at arms-length and look at it.
It's surprising how much the choice of font affects the appearance of a document. Some publishers are quite obsessive about fonts. I can see why. I take some care with them, but I'm neither obsessive, nor really a publisher.
Good indices are a Godsend, but are also darned hard work to do well. The best indices are defined manually by the authors, based upon good keywords by which people will want to look for things, but that's a huge task which most of us baulk at. Sometimes what's important is to exclude things that are not so helpful. BiaB's index is not actually bad, though it could be better.
I think a separate sub-section just for the chord-entry shortcuts might be worthwhile.
In quite a few documents, I despair at the standard of grammar and punctuation. I have to say that I haven't noticed any real howlers, no "xxx was charged with murder in the court today".
The following may well not be feasible with BiaB now, and is much more software design than manual. Some software has a philosophy: "Everything that you can do with any object will be found in a right-click menu on that object".
I think I've written more than enough for now.
I'd earlier said in a thread started by malevans that I thought the manual was "cluttered", so I thought I should expand on that. Someone also mentioned the Reaper manual as quite a good example, though there are several others. Reaper, BTW, have a footnote on each page with a link to LULU.com who are one of several organisations that offer printed manuals on demand.
Some of that "clutter" is due to probable documentation conventions, which could be made more concise by declaring those conventions somewhere, possibly right near the start of the manual. For example the convention used for buttons: [Style] if explicitly defined in the conventions as a button, would negate the need within the body text to say "using the [Style] button". Icons are good, though can be confusing when there are multiple GUI styles available, e.g., the monochrome or coloured icons styles.
Similarly predefine font meanings. Generally, the fewer fonts the better, though in manuals for software, "fewer" is usually quite hard to achieve.
Similarly sequences of actions. I personally tend to use, e.g., File->Load_Style_Special->"filename"->[OK] to describe a sequence. I note that the | symbol is used in some places, which is OK (though for me | means "or"). This would reduce the desire/need to use verbal descriptions.
A common problem in the manuals for many applications is that a section describing something, e.g., perhaps the MIDI Settings, without telling the user, right at that point, how to get to that something. Incidentally, I picked that from the index, expecting to see the instructions for setting up a MIDI device.
During a main explanation, focus upon a "preferred" way to do something, offering "other ways to do this" as a separate item. Then each of the sequences can be described completely in and of itself.
Hierarchically numbering every header helps navigation, and also helps suggestions or error-reports to focus closely to the correct location. In my specifications, where I need to incorporate similar changes, I usually number every paragraph, though most word-processors seem appallingly bad at doing that properly. A fall-back I've used is to number every line on every page, which is something with which most word-processors seem more adept. "Changed" indicators are often useful if the tools support them. You almost certainly already do that internally; it can be less useful in a published document, as it add clutter.
White-space, including indenting, helps quick navigation by eye and usually makes the document look nicer. On a .pdf document, white-space costs nothing. Printed it can, but better clarity can often reduce the number of pages needed.
It's worth looking at the keyboard shortcuts section and considering how an additional line before each sub-header and indenting the keys from that header would make it easier to use. At present, it isn't easy to pick out the subheadings from the keys. It's worth noting that many publishers consider the white-space to be the most important part of a document, yet we ordinary folk tend to forget it, particularly when close to a particular text. It can pay sometimes, just to hold a page at arms-length and look at it.
It's surprising how much the choice of font affects the appearance of a document. Some publishers are quite obsessive about fonts. I can see why. I take some care with them, but I'm neither obsessive, nor really a publisher.
Good indices are a Godsend, but are also darned hard work to do well. The best indices are defined manually by the authors, based upon good keywords by which people will want to look for things, but that's a huge task which most of us baulk at. Sometimes what's important is to exclude things that are not so helpful. BiaB's index is not actually bad, though it could be better.
I think a separate sub-section just for the chord-entry shortcuts might be worthwhile.
In quite a few documents, I despair at the standard of grammar and punctuation. I have to say that I haven't noticed any real howlers, no "xxx was charged with murder in the court today".
The following may well not be feasible with BiaB now, and is much more software design than manual. Some software has a philosophy: "Everything that you can do with any object will be found in a right-click menu on that object".
I think I've written more than enough for now.