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.
First, some context: Clearly, there are many possible situations for
modular software, and some of them may make my approach impractical or
even impossible. But you don't know that until you analyze the specific
situation. I've used a simple example of "user" vs. "administrative"
roles, but other situations may be far more complex.
David Castro reports: <<Wow! I think this is my first time in 10+ years
on the list that I disagree with the esteemed Geoff Hart! :-)>>
Guess you haven't been reading all my posts, then. <g> I'm not shy
about loudly proclaiming solutions, some of which are 100% wrong or
inapplicable. I imagine a search of the archives using my e-mail
address and "oops!" as keywords would prove very enlightening. <g>
<<This [active server pages or similar technology] would only work if
the clients will always be Internet-connected, and if your company is
willing to host the documentation on your web site.>>
I didn't describe that well. The "ASP or similar" approach would
clearly have to run locally. I have no patience with Internet-based
help; I'm not always internet connected. I'd speculate that Exchange
Server lets you serve ASP over an intranet, but there must be other
platform-agnostic solutions.
<<When you do a full-text search or look in the index, what are you
doing? You're looking for the fastest way to get to the information you
need. If your index or FTS matches is so full of modules that you don't
have, then you're hindering your users' ability to get the information
they need quickly.>>
This is a design issue, not a serious problem. If the modules are at
all different, there will be relatively few overlaps in their help
contents. Where there are overlaps, intelligent use of keywords and
topic titles solves the problem: an index entry would be
"Configuration, User options, Slobs like Geoff" (not just
"Configuration"), and the corresponding help topic would be
"Configuring slobs like Geoff". It's all about choosing precise, useful
keywords and titles. If they aren't clear, it doesn't matter whether
the modules overlap--they're still unusable.
I also noted that "if I inadvertently stumble across such a module, and
it seems interesting to me, I'll possibly buy that module so I can take
advantage of its features." Dave noted: <<This was the theory put out
by marketers in past employment, and it drove me crazy.>>
My unspoken assumption here is that the help is designed to be helpful,
rather than being specifically designed to sell products by making it
impossible to accomplish a task without buying more modules. And let me
emphasize that most users will be focused on doing their own jobs, so
they will never follow links for topics that don't specifically address
those jobs. Me and thee are part of the 0.001% of the population who
actually read help files for fun. (For everyone else, there's
Mastercard. <g>)
<<First of all, the people who use a product are frequently not in a
position to decide (or sometimes even to influence) what modules are
purchased.>>
I've always worked in places where I could go to the MIS guy or my
manager and say "I'm wasting 15 hours per week indexing documents, but
discovered a module that could save me 10 hours per week and let me do
that much more useful work". That approach often influences the buying
decisions. I can't make the purchase, but I can influence someone who
can.
<<Second, users may not *know* that they don't have a module. If they
look for how to do something, and then find an answer, and try to
follow the steps but the menu items/buttons/dialogs that the help
*says* are there *aren't* there, then you've really confused the
user.>>
That's a more serious issue, but again, it's a simple one in a
module-based approach. First, the software: "Sorry, Geoff, you only
have slob rights. You need to get a haircut and get a real job--and buy
the admin module--before you can do that." Second, the docs: "If you
have the administrator module installed... [procedure]." Those who
don't (or who don't know whether they do) won't be trying that trick
anyway, since it's not part of their work.
<<... creating a cross-file link may (depending on the system) cause
broken links if the target file doesn't exist. And if it does exist (as
you suggest shipping all of them) then what have you accomplished by
modularizing? It might as well be one big help file if all of the
content is accessible regardless of the modules installed.>>
Broken links are solved by shipping all the modular help. That way, the
target always exists. If the modules are 100% discrete and 100%
non-overlapping, there will be no cross-file links. Where a cross-file
link is necessary, add the necessary warnings: "Remember that if you're
a humble slob, you can't use this function. But there's no reason why
you can't read abot it and tell your admin that it exists and that they
can use it to make your life easier."
A careful task analysis before you get started will reveal where
modules overlap and work together, and you can develop specific
solutions for each such situation. Sometimes the solution is as simple
as adding a standard note at the top of each help topic: "To perform
this task, you must have the Admin and Slob modules installed. Here's
where to find out if you do. If you don't, here's what to do..."
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
Doc-To-Help 7.5 Professional: New version with new features, improved performance and reliability, plus much more! Download your free trial today at www.componentone.com/techwrlfeb.
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
