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: Documentation - The Way To Go? From:Justin Soles <jsoles -at- TYPHOON -dot- CO -dot- JP> Date:Thu, 12 Nov 1998 22:35:05 +0900
Hi Alan,
Your description sounds more like a business school case study - a very
interesting but potentially thorny situation... There are some VERY
interesting issues here: streamlining your documenation, cross-cultural
issues, true HTML Help vs. MS's HTML Help, and the list goes on...
One question I'll throw out to you: in what form do your CUSTOMERS want to
see the documentation? Whatever path you choose needs to be as close to the
ideal your customers want, or they just won't use it. Canvass a few
customers at random to find out where they are going with regards to having
the Internet at work (many companies in developed countries either don't
allow it or limit it, and many in the developing world don't have any
access) and if so, which browser they are using. Find out if they have an
Intranet and if so, how do they use it? I've found that most customers will
be happy to give you their time if you ask.
Given that your product is software, I'm a bit surprised that you don't have
some form of online help (readme.txt?) but if you are going to need to start
from scratch I think I would go straight to HTML - not MS's HTML Help
implementation but HTML pages. Why? It would be a big project but:
- you get true cross-platform support
- you can continue writing & producting in Word (granted, you WILL need
something to tranform Word into HTML since MS's converter does a pretty bad
job from what I've seen...)
- when the dust settles around what HTML-based Help system is going to be
used, you can probably retro-fit your existing pages without any downtime
for your current system
I think PDFs would also be a good short-term option: they are small,
portable, require no changes to your present documentation or workflow and
they can be viewed either locally or over the Internet. PDFs also bypass a
potential pitfall: converting Word docs of different languages into HTML.
This gets tricky because of the double-byte character set used for Japanese,
Chinese, Korean and other Asian languages. You didn't mention whether your
documentation was in any other languages besides English - if they are, I
would seek professionals that can help you convert the documents so they
work in the other languages.
Good luck mate! Let us (the Borg-like collective "us") know what happens...
