TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Make the content task-oriented (as opposed to UI-oriented or abstract).
Spend a lot of time up front getting the outline right. Usually this
means organizing the contents following a process workflow or
lifecycle. Look for user categories (e.g. end user, supervisor,
adminstrator) and iterative subprocesses (loops) that imply logical
TOC sections or levels.
Within the workflow outline, break the the content down into logical
modules. Start a logical group of modules with an overview that puts
them into the context of the workflow.
Put reference material at the back and cross-reference it from task topics.
Be comprehensive but concise.
Don't document the self-explanatory. To put it another way, don't
write uninformative "help" that simply narrates what the user is
looking at. When a programmer defines an unneeded context ID for a
self-explanatory UI element (such as a self-documenting wizard), link
it to a generally relvant topic, or the default topic.
Avoid redundancy by using cross-references.
Ensure accuracy by testing everything yourself.
Use graphics only when absolutely necessary. Compose screenshots
carefully to make a point.
Break the above rules as necessary, which shouldn't be too often.
On Thu, Jul 2, 2009 at 8:36 AM, LML<lleduc -at- designnettech -dot- com> wrote:
> Hi All,
>
> I've been researching around and looking at different types of user manuals
> and I'm wondering what you all think is the best approach for a useable
> manual. Can anyone point me toward any examples of great manuals, although
> such greatness may not be out there freely on the internet. I have found
> many bad examples and they are generally bad because even though the
> information is there, they are difficult to maneuver through.
>
> I'm working with Word right now and want to learn how to use Frame Maker,
> but I am not sure how quick of a learning process that will be (any input on
> that would also be appreciated).
>
> The manuals are distributed as PDFs or Flash documents and I know they are
> often printed out by the users, so that definitely has to be factored in.o
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
