Print

Print


Thanks to all who responded. I think Mark Singletary's response best hit
the mark for me. There's also some great reading suggestions within.

Pat M
[log in to unmask]

 +++

ORIGINAL POST

Sent: Friday, August 27, 2004 1:13 PM
To: [log in to unmask]
Subject: C&S: Need Quickly - Best Practices for Online Manuals

Hello: I've done some quick searching, including the CHI-WEB archives and
couldn't find anything.

We have a department that is moving some VERY large manuals online -- HTML
on our intranet. We have style guidelines in place (fonts, colors, writing-
for-the-web, etc.) But, can anyone point me to standards/best practices for
organization/navigation models for large manuals?

They need to be fairly simple tactics that part-time publishers (not HTML
gurus) can utilize.

Reply to me and I'll summarize.

Thanks! - Pat M.
[log in to unmask]

 +++

VERBATIM RESPONSES

Hi there,

The Oracle BLAF Guidelines are pretty extensive in scope and are easy
to dig through, especially considering the content scope.

- Clay Newton [[log in to unmask]]

 +++

Hi Pat,

I've found Standards for Online Communications (Hackos/Stevens) very
useful for online help/manual publishing--it uses a straight-forward
checklist style for presentation best practices. The User Manual
Manual (Bremer) helps in developing better content/style, and Human
Factors for Technical Communicators (Coe) provides the HF
underpinnings for the design/interaction. All address navigation at
some level.....

good luck!

judy [[log in to unmask]]

 +++

Pat,

My experience has been that large online manuals are anathema to user
experience design. I'm not sure exactly what you're manuals are or who is
using them, but if the manuals are user guides to web applications then my
opinion is that you should replace them with something more accessible to
the user.

What kind of manuals are these?

I have a client in the healthcare business that has online manuals that span
8-10 PDFs for web apps. The user needs to go off task to enter into the
long,detailed manual to find answers. I wouldn't be surprised if they forgot
what they were doing by the time they get back to the application.

What we're trying to do is bring the "manual" to the user by informing the
UI of the application with contextual help. It's a lot of work, but it will
create greater efficiencies by allowing site users to move quickly through
forms and workflows without the constant interruption of searching online
manuals.

We intend to have some online tutorials which are far less comprehensive but
which allow users to begin to interact with the system while they get an
introduction to the information architecture.

--Mike
[log in to unmask]

 +++

Pat  -

I'd be happy to repost your message to the STC Usability list - the members
there are often documentation specialists, and would have direct experience
with large manuals on the web.

Whitney

At 09:02 AM 8/30/2004 -0500, Malecek, Patrick wrote:
>Thanks Whitney - that would be great. In response to another individual's
>question back to me -- these aren't software manuals or the like. These
>are legalese, regulatory procedural documents. So it's not something that
>a user would need to reference while completing some technological task.
>
>Thanks!

Oh - In that case, you definitely want to visit PlainLanguage.gov.

And, you should take a look at the Washington State safety regulations.
Ginny Redish worked with the group there to rewrite the regulations into
material that was easy to use, easy to read and easy to understand. The
result is a model of excellent online regulatory documents.

See:

http://www.lni.wa.gov/wisha/corerules/

and

http://www.stcsig.org/usability/newsletter/0208-excellence-award.html

They did a presentation at STC in Chicago, so you might be able to find a
paper on it as well.

Whitney Quesenbery [[log in to unmask]]

 +++

Pat,

 The kiss principle is a good start.
In the past I've had good success with the following:

     1. Each page has a link to the cover page and TOC

     2. Each page has a link to the index

     3. If the documents have high rate of change >= twice annually,
        then minimize internal linking of the document.

     4. Imbed the pictures and charts, don't put them in hrefs for the users
to look at ( they won't).

     5. Electrons are nice but each doc must available in a print friendly
form.
        PDF or MS Word.  PDF is a little more portable. The document should
be
        available for download in total and in chapter form.

     6. Maintain the documents in their current form.
        Using Word, WordPerfect, MacWrite or whatever
        and converting the docs for display each time, is actually more
        efficient that trying to maintain the HTML.
        If you use MS Word, you can maintain the doc in HTML-WYSIWYG.

Mark Singletary
281.290.1644
[log in to unmask]

 +++

The best examples I have seen of large doc sets on the web are:
BEA, <http://e-docs.bea.com/wls/docs81/index.html>
Oracle, <http://www.oracle.com/technology/documentation/index.html>
IBM,
<http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pb
i.cgi?CTY=US&&FNC=ICL>&

The Cisco documentation is also online, but it is not publicly available.
Of the three you can view, I believe the BEA documentation is much more
usable.

It is likely that all sets of docs were produced using FrameMaker files
converted with WebWorks Publisher. The Oracle documentation is pretty close
to the output you'll get without much customization.

The following points will help make the docs more navigable and usable:
1. Offer the docs as PDF. People will want to print them. In my experience,
if you don't do this now, you'll just have to do it later, so plan for it
now when designing the docs.
2. List the file size of the PDFs and the page count. It helps people
determine which document may be more useful. For example, if they are
looking for an API reference, they can rule out the 5 page document.
3. Use a good internal search engine for the doc site, one that allows
users to restrict the search in multiple ways that relate to docs, such
as "only in release notes", "only in this document", "only in Product X
documentation." Note that I haven't seen that in use on any of these sites.
4. Use a breadcrumb trail, as shown on the BEA site.
5. Resize fonts for online viewing. All of these doc sets use a font for
headings that is too large.

Lynda Sereno [[log in to unmask]]