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.
Re: They say there is no such thing as a dumb question
Subject:Re: They say there is no such thing as a dumb question From:Keith Hood <klhra -at- yahoo -dot- com> To:tech writer tech writer <techwr-l -at- lists -dot- techwr-l -dot- com>, Roberta Hennessey <rahennessey -at- gmail -dot- com> Date:Mon, 10 Jan 2011 21:16:03 -0800 (PST)
Some stuff off the top of my head, from experience with help systems from long ago:
The very first thing you should do is find out if the product you have to document is stable or if there are upgrades or revisions coming in the near future. Try to pin down exactly when they are going to incorporate all visual changes to the interface. You don't want to start writing help pages and then find out they're going to change everything next week. And you don't want to find out too late that they will be still changing the images on the controls right up to the morning of the day when the new version is supposed to be released.
After that, decide/ask what level(s) of help should be included in the final product. Will you have context-sensitive help that is actually mapped to screen features? (I would strongly recommend you try to avoid doing that, if you can.) Will you have to produce both window-level feature help and how-to procedures, or only one of those? Should the help be indexed? If the answer to that question is yes, how extensively? If you do window-level help, how many windows will you have to document? To what level of complexity should the help pages be cross-referenced?
For doing window-level help, I think a good planning figure is 8 hours per window documented. That's just hours to write the help page; that doesn't include proofing/editing, and function testing. That figure will be lower for less-complex windows.
If you're going to do how-to procedures, you will have to experiment hands-on with the software to find out what it really does. There WILL be differences between the specs and reality. Allow half a day to make an outline of the procedures that need to be covered. Give each procedure in the outline a complexity rating from 1 to 4 (4 being worst - longest and takes the most explaining). Then multiply each rating by 2 hours. That gives a rough idea how long it would take to experiment with the actions, note the results, and write numbered steps that accurately show your findings.
If you're going to use Webworks to boil down Word or Frame source files, allow at least 12 hours for troubleshooting and tuning style transitions.
When you get to the point of testing the help functionality (checking links from the TOC, the cross-references, etc.), figure 2 minutes per link. You can count the number of links by doing a text search in the source files and finding the number of instances of the code that starts a hyperlink.
Include a couple of days for technical review.
And remember to always Scottify your time estimate - always add 10% to allow for unexpected sickness or other problems.
--- On Mon, 1/10/11, Roberta Hennessey <rahennessey -at- gmail -dot- com> wrote:
From: Roberta Hennessey <rahennessey -at- gmail -dot- com>
Subject: They say there is no such thing as a dumb question
To: "tech writer tech writer" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Monday, January 10, 2011, 3:20 PM
I hope this is not the first dumb question. Snide comments not taken
personally.
I am being asked to scope out a project - documenting an online help for a
GUI application. I have used
Webworks to create online help from an existing document (Frame or Word),
but I have never created help
for a GUI that is already in place. The GUI application is done in Java but
no one here uses the Doxygen method,
etc. and there are no plans to do so.
I think the documentation will be relatively simple - but I'm not sure what
type of tool would work best for this
group, and which one would be one they could upkeep. I imagine it will be
process of mapping the context
sensitive help to locations in the GUI.
Any books, blogs, websites, ideas from anyone on how to begin to scope this
effort? Any and all advice
appreciated.
Thank you.
Bobbi
--
Roberta Hennessey
Technical Writer
(978) 835-4282
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as klhra -at- yahoo -dot- com -dot-
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://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
