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.
I am hoping that my question will bring about a LOT of discussion. I am
looking for thoughts about documentation deliverables and usability for
a very specific scenario. Any and all thoughts and input about how
things COULD be handled, out of the box thinking, etc. would be greatly
appreciated.
The ISSUE
My client has a very complex Internet based software (SW) that is used
by organizations to manage a major aspect of their business processes.
To date, the only documentation provided to clients was marketing
literature and the online Help. The online Help was poorly written, and
more "how to" oriented - however, it did little to help users navigate
the complexities of the SW which has modules that feed each other, and a
variety of other issues.
The client is preparing a major upgrade of their SW which is essentially
rewriting a portion of the SW that will impact 95% of the functionality
(more user-friendly, more customizable to specific organization needs,
etc.). The GUI, however, will only be impacted partially. Half of the SW
will have the current GUI, half the old GUI. (The extent of the SW is
such that there is no way everything can be rewritten all at once - this
is a business decision that cannot be changed, so let's not discuss that
its a bad idea, we all know it is....).
To date, clients have never received a lot of information about the
theory of the SW they use, and what the SW does behind the scenes.
However, this information is critical if the users are to make the
correct decisions when using the SW to meet their organization's needs.
Given that CD or printed documentation is NOT an option, and given that
SOME of the theory is important all of the time, but most of it
important only in the first 6 months of use of the SW, after that, they
will know the important stuff and only need HOW to do something (not the
why behind it), HERE ARE MY QUESTIONS:
1. How would you recommend handling the documentation?
a. One large help file, users would have to use the Contents, and
wade through info in the Index or in a search to find the info they need
b. Separate help systems that connect one way (Say a theoretical
help that links to the HOW to, but not the other way around).
c. PDFs of the theory that users can access and print, and have
available whenever they want
d. Something else I've not thought of?
2. How would you refer to this new "upgrade" and how would you suggest
relating to the two GUIs in a positive manner?
For example, if the real name of the software is Business Manager,
and the upgrade portion is XY System, how do you feel about the
following text? " The XY System, or XYS, manages business statuses, the
rules for achieving those statuses, and processes business activities
against these rules. XYS is not a module within Business Manager, there
no XYS page or section of Business Manager that is labeled XYS. Rather,
XYS is the technology that enables business processing..."
I am extremely concerned about designing the documentation in a manner
that is a user-friendly as possible. So any and all thoughts on this
would be greatly appreciated. As you can see, there are a lot of
limitations. Since I work by myself, I don't have the advantage of being
able to discuss the pluses and minuses of different options with others.
I hope that a lively discussion on this will be beneficially to myself
and others out there.
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-
