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.
Subject:Re: Printing an incomplete manual From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Wed, 2 Apr 1997 09:04:27 -0600
>Howdy, Yall:
>
>In the past, this company provided manuals long after completing the
>software; they really want to change this by providing a manual with the
>software. I agree with this. I plan on providing an updated version of the
>manual (in help format) regularly as we continue to adjust and enhance the
>software.
>
>Has anyone tried this? What were the results? How did users react? Is this
>likely to discourage further use of the manual? Is this just part of
>developing software (my first run at version 1 of a software)?
>
>Melonie Holliman
>
You were lucky for a while. I've never produced a software manual after
the software was complete. A couple of times I've produced one before
the software was finished. The following are some of the methods I've
used in producing on-line documentation either concurrently or slightly
ahead of the product.
-- The developer must document changes to the software that occur after
the document is finished in a README file.
-- I put an on-line disclaimer in the help. I did this by registering
the windows MsgBox function to the help and assigning the function a new
menu item (such as About Help). The message box says something to the
effect of, "Help may not reflect recent changes made to software. See
the Readme file for later changes". For one alpha release, I had the
message box pop-up whenever the user invoked a topic that stood on shaky
ground.
-- I develop the topics in modules and avoid 'hard-coded' (text or JI
macros) cross referencing. Instead, I use ALinks. If the target is
removed from the help, its links are not made (as opposed to broken JI
links or text referencing non-existent topics).
-- The help can be recompiled with blocks of information included or
excluded (build tags perform wonders here). Therefore, if a section of
functionality is yanked from the product near the document deadline,
just exclude the topics for that informational block. The 'hard-coded'
no cross-referencing rule saves me from hunting for text (outside of the
informational block) that is no longer pertinent to the software.
-- Visual C, Visual Basic, PowerBuilder, or whatever is used to build
the interfaces can be used to display GUIs without running the
application. Therefore, screenshots can be made without worrying about
the SW crashing before the desired GUI appears. These applications can
also be used to simulate what the GUI looks like during run time under
desired conditions. You can even simulate the processing of a data
without ever connecting to a database.
Mike Wing
INTERGRAPH
| Michael Wing
| & Principal Technical Writer
| Infrastructure Technical Information Development
| Intergraph Corporation; Huntsville, Alabama
| : http://www.ingr.com/iss/products/mapping/
| ( (205) 730-7250
| . mjwing -at- ingr -dot- com
>
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
