Re: What type of document is this?

Subject: Re: What type of document is this?
From: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
To: "Sean McKean" <Sean -dot- McKean -at- FINEOS -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- techwr-l -dot- com>
Date: Tue, 28 Feb 2012 08:00:59 -0800

It's a 50-page document that explains what the software does. It lists the features and briefly describes what users can do on each screen. There are no procedures in it though - we have a much longer user's guide for that. It's a post-release document, and it'll be used as a definitive list of what the product contains. We're producing two versions: a 'product' version containing the UI features, and a 'technical' version.

-------------------

I'd suggest taking a look at the Microsoft Manual of Style's "Titles of Publications" section. I'm looking at the 3rd edition (the 4th ed. just came out but I haven't bought it yet), and the following three suggestions look particularly applicable:

* Companion - for end users, "Overview of product features, often describing projects the user can accomplish with the product, such as publishing a newsletter. Often highly visual and informal."

And this fosters a use-case presentation, which is likely more helpful to readers than a screen-by-screen description. After all, users don't approach a software app with the intention of using its screens; the users instead want to accomplish some particular task. (I'm not suggesting a big rewrite -- but I am assuming that there is a rough correspondence between "each screen" and "broad user task".)

* Feature Guide - for end users, "Overview of product features."

I've adapted this several times, and called the doc a "Feature Reference", which typically corresponds well to a screen-by-screen doc organization.

* Idea Book - for end users, "Task-oriented. Highlights certain features of the product. Often includes sample files."

I really like this because it provides a good launch point for users. That is, they don't get quite so caught up in the application's screens, but *what* the app can do, even beyond what the user already knows that they need.

HTH,
(And do let us know what you decide on :-),
-Monique


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.

Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.

http://bit.ly/doc-to-help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
What type of document is this?: From: Sean McKean

Previous by Author: Re: Freelance opportunity
Next by Author: suggest - change email subjects when appropriate...
Previous by Thread: Re: What type of document is this?
Next by Thread: RE: What type of document is this?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads