Mathias Bauer wrote:
Daniel Carrera wrote:
Mathias Bauer wrote:
[snip: deployment should be easy]
<snip>
Sometimes it's not easy to find the right balance in what you write into the documentation: what can I assume as known to my readers (or what can I leave to them for their own ideas), what should I mention?
<snip>
I am sick to death of MS' documentation, which barely tells us how to spell a function, much less give us an explanation, with examples of how to use it, or why we'd want to. This is not to suggest that the Linux community does this, far from it; this is just to explain my mindset. Back in the days when DOS was a separate package from Windows, there was a DOS manual (for v 6, IIRC) that I thought was a very good example of how a user's manual should look. It talked, in the front half, about how to use DOS and gave some examples of batch files, DOS commands in combination, why we'd want to do these, etc. And the second half of the manual was an enumeration of the commands available in DOS, with detailed explanations and examples for each--very much like a man page. This was a thick book, but this user found it useful.
Earlier in this thread there was a mention of a Developer's Guide that would fit very well the above bill, and there was a mention of maybe needing a macro book dedicated to developers. I think, though, that the average user is not going to buy/download, much less use, a Developer's Guide--the title says there's nothing in it for him/her--the user. I suggest, instead, that the DG, if it truly is quite detailed, be reorganized for the user (and retitled), but not at all dumbed-down--if it's organized along the lines of the DOS manual I talked about, the user can use it (and would probably obtain it for use) and s/he could get as deep into the system and s/he found useful. I'd also suggest that some detailed excerpts from the macro book be included--many (most?) users will, eventually, be needing to create macros in a more efficient manner than simply recording, and such an excerpt would give that power user a means to do so.
Basically, I'm saying that you can't include too much information. Don't make any assumptions about what your readers know. If you're writing for users, you're actually writing for two audiences: those who simply want to get into the package (OOo, for instance), and power users who ultimately will want to make the package sit up and sing. Information that's present won't be used by all users, but information that's absent can't be used by any user.
Eric Hines
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
