Re: CD-ROM and Internet Documentation (long)

[Marguerite Krupp <Marguerite_Krupp -at- BAYNETWORKS -dot- COM>]

I'm replying to the list, since I got several replies to my earlier post,
and I'll try to address your questions. And I invite anyone in the New
England area to the STC regional Interchange Conference on October 19-22,
where I'll be chairing a panel on "Paperless Publishing" on the 21st. For
info, see www.interchangeconference.com.

Bob Johnson asked:
>What resources are devoted to maintaining the documentation portion of
>the website?  (Both time and personnel)

We do our docs in FrameMaker 5.5.2. Each writer is responsible for applying
a department-defined "blue" template, which is how we make the
cross-reference links blue. Two people, who also write, are responsible for
the web conversion and maintaining the site. I'd say that the total time
(which, of course, get heavier as the release date approaches) is about
1-1.5 persons in this effort. We use Quadralay WebWorks Publisher 4.0 for
the conversion. Individual writers have been experimenting with other
tools, but so far, we've tried to standardize. FrameMaker's own HTML
converter is OK, but it inserts a lot of extra code.

>
>How has the user response been?  Have they generally found the the labor
>involved in finding the appropriate documentation acceptable?  I notice
>you say tech support likes it, but do users?

User response has been more positive than anticipated. I don't have
specific numbers yet, but our usability studies show that as long as
there's an adequate search capability, the accessibility of the documents
makes up for the inconvenience of having to print pages if they want to
read stuff offline. Some of our users, particularly those who make it a
point to read through the entire 50+ doc set, do prefer the hard-copy
version. One large customer said that he will not read more than a page or
two online. The pdf format makes a "book" that the user prints more like
one we would print, but the format is optimized for the html side. Users
will have to put up with "return to..." links that don't make much sense in
hard copy. We are trying to use a single FrameMaker source document for
both pdf and HTML formats, so this introduces some, uh, infelicities (like
weird page breaks).

Part of this question involves who our users are. We have very few, if any,
end users in our audience. Mostly we write heavy techie stuff for network
managers and system administrators. We assume they know what a router does,
what a network is all about, and what the characteristics of the various
protocols are, for the most part, although we do have a couple of "Getting
Started" books. We tell them how to configure, manage, and troubleshoot a
network and its components using our routers, switches, and software. They
are very much reference oriented. This might not work as well with a
different audience.

>
>Have you found any problems with access, readability, or usability?
>With consistency or navigation?

Well, you have several questions here, so let me tackle them separately.

-- Access - Users have access to the documentation as long as they have the
CD-ROM (and a working CD-ROM drive) or an Internet connection, because they
have the same access that you did. Field reps much prefer carrying a CD-ROM
to lugging a paper doc set! And if there's only one printed set at a site,
it often gets locked up in a "safe place" so it won't grow legs and walk
away. Not exactly accessible.

-- Readability - Same as our hard-copy documents, actually a pretty high
grade level, if you run it through a Fog Index calculator. Words like
"telecommunications" and "protocol" tend to skew the readability scores. If
you mean "legibility," that becomes an issue for the online format. Screen
resolution is not (and probably won't be for a few years) as good as print.
That's why people who need to read more than a few lines are likely to
print the pdf version. The HTML version is printable, but it's subject to
the vagaries of the browser the person is using.

-- Usability - We have our own usability lab, and we do test our documents,
both before and after release. We've learned a lot about how people use the
documentation. That's one basis for my comment that people seem to use it
primarily for reference. Of course, that's the way the usability test is
set up: "How would you do task X?"

-- Consistency and navigation - Both are essentially usability issues. In
addition to having in-house editorial and structural guidelines, which at
least offer the user some consistency within and across documents, we are
making a real effort to use the power of the online medium. Our legacy
documents have all been converted, and those are a straight 1-for-1
book-to-pdf conversion. Our newer stuff is specifically designed to allow
good use of hyperlinks, for example, and the web's navigation capabilities.
We're still learning, and we know we're not perfect. This is the first
online-only documentation set we've done, so we're excited about the
possibilities. Of course, one of the drawbacks of using HTML is that a user
might wander off into some thread and forget where s/he came from, but
since the purpose here is primarily reference, that is (I think) not so
much of an issue as it would be in a narrative. Our users tend to go to the
docs for a specific piece of information. As long as they can find what
they want and get back to the application, that's OK.

Garret else asked why we GIVE AWAY something we might sell. I think it
comes down to corporate philosophy (Bay Networks) and experience. We used
to sell our books. The last complete printed doc set we did cost us
$805/set. We printed 100 and sold 50, mostly to in-house users. Go figure.
The fact is, our users can get the information a variety of ways. We
provide extensive online help for both our GUI and our command line. Since
the software is at Version 13.10, users can usually find someone who can
figure out the answer, even without the book. Then why do we bother doing
manuals? Good question. For one thing, if we make the user info more
accessible, it cuts our support costs. For another, interviews with users
indicate that they DO use the manuals, and that they like the searchability
of the online medium.

How has all this affected me as a writer? Designing for the online world
HAS changed the way I write the documents. They're a lot leaner, for one
thing. I choose my words very carefully and tighten, tighten. The fact that
the user generally has the application on the screen as well as the
documentation has almost eliminated screen captures from the document,
although I do still include diagrams, when appropriate, sometimes as popups
or secondary windows. It depends on the user and the subject. In this case,
the documents have become more reference- and task-oriented, with a lot of
decision tables. Within the tables, I have hotlinks to more extensive
information, such as full parameter descriptions.

Well, this has been a lot longer than I'd intended, but I hope this answers
your questions about what we do. I'd like to hear more about what YOUR
company is doing.

Marguerite


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=