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.
Kimberly McClintock wonders: <<We've got install procedures for a
product that runs on Windows and on Linux. Radically different
procedures are broken out in OS specific sections, but a good deal of
the procedures overlap with the exception of the path. I'm looking
for a graceful way to avoid this (exaggerated for effect):
Edit the databaseContext.xml file located in the /opt/oleopenlogic-
enterprise-4.2/storemanager/config directory on Linux and the c:\ole
\openlogic-enterprise-4.2\storemanager\config directory on Windows as
follows:
Alternatives thus far include 1) defining a convention like BASEDIR
in the introductory material or 2) Picking one OS as standard, and
doc the necessary changes that will need to be made for other OS
users in the introductory material.>>
I remember with considerable amusement the anecdote of a friend who
barely made it through French class because he could never remember
whether to use the accent aigu (é, for example) or the accent grave
(è). His survival strategy? He wrote a vertical line for both
accents, and hoped the teacher would assume that if he had any idea
that an accent was required, he'd know the correct accent.
This worked about as well as you'd expect, <g> and it suggests you
should avoid the temptation to use the vertical "pipe" character (|)
as a solution for directory paths. If you expect people to actually
type any of these paths, I guarantee that some readers will type the
pipe instead of the correct delimiter (/ or \). A much safer
alternative might be to use the same kind of approach we sometimes
use for menu paths: "Save the file in the Level 1 --> Level 2 -->
Final level directory." That's semi-elegant, more space-efficient,
and for anyone using a command-line interface, probably clear.
If you're willing to think outside the box, you could also use a
screenshot showing the expandable directory structure that must be
navigated to reach the desired directory. Not the best solution if
you need to translate and localize your documentation, but a very
clear depiction of the location that may be more efficient than other
solutions.
I'm not sanguine about simply defining "BASEDIR" because then you're
forcing readers to remember that definition, and if they don't
remember it or never read that part of the manual, they may have a
tough time finding the definition. (If you do this, index it VERY
WELL so readers can't possibly miss it.) If Linux permits the
creation of aliases or shortcuts to directories (like those on the
Mac and in Windows), using such a shortcut would work very well if
you create those aliases during the software installation process. In
that approach, when someone actually types BASEDIR, that takes them
to the alias, which in turn takes them in a single simple step to the
correct directory. Much kinder than asking them to type the long
addresses you listed above, not so?
Failing that, the safe if inelegant solution is to repeat the path
name for both operating systems. That's particularly useful if you
will be providing these paths in online help or a PDF file; readers
can then avoid error-prone typing by copying the appropriate pathname
directly from the file, pasting it into the command line, and away
they go.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
