Review Process for documents in HTML?

Subject: Review Process for documents in HTML?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: Technical Writing <techwr-l -at- lists -dot- techwr-l -dot- com>, "Beierle, Cecily" <cbeierle -at- tcfbank -dot- com>
Date: Thu, 09 Apr 2009 08:13:15 -0400

Cecily Beierle wondered: <<Our company uses FrameMaker to create
documentation. Originally, we generated PDFs of the FM files, which we
used for SME reviews and published on our intranet.>>

I assume that you mean the SMEs don't use Frame? If they do, my
understanding is that Frame has offered credible revision tracking
since at least version 8, and that means you should simply conduct
your reviews in Frame. (If not, it might be possible to install a
single additional copy on the network so anyone can use it, perhaps
only one user simultaneously.) As Occam notes, don't make things more
complicated than necessary. If not:

<< Now we generate HTML from the FM files, using WebWorks. As part of
the transition to HTML, we've changed our styles to be more web-
friendly. Unfortunately, the files are much more difficult for SMEs to
review in PDF format.>>

It's not clear to me why it's difficult: a page is a page, no matter
its format. But more importantly, if the files start their life in
Frame, you should eliminate PDF entirely from your process. Speaking
as a professional editor, PDF is a pain in the ass to work with if you
have to do significant amounts of editing (it used to be almost
proudly inefficient and cumbersome, and though it's much, much better
now, it's still less efficient than a word processor). Here's a scary
statistic to explain why I consider PDF unusable for editing: Back
when I used to edit on paper, with experienced, dedicated typists who
were experts at transcribing scrawled edits into wordpro files, even
the best routinely missed or misinterpreted up to 5% of my
corrections. (Writers, even the pros, were generally much worse.) This
meant that a second pass was always required to ensure that no
comments that got missed.

Unless you're using Acrobat's ability to round-trip edited files
between PDF and Word (a kickass feature they added a couple years
ago), it's logistically difficult and highly error-prone to manually
copy all the edits and comments back into Frame. Avoid this approach
if at all possible. Speaking of Word:

<<Our question is what have others done to allow SMEs to efficiently
review HTML documentation?>>

The most efficient approach that I've found is to use Word and its
revision tracking feature to do the reviews. Odds are excellent that
all of your colleagues have copy of Word somewhere on their
computers, but if they don't, download and install OpenOffice Writer
and use that instead; the basic steps are identical, mutatis mutandis.
Here are the basics of the process:
- Produce HTML files, which will be in "text" (ASCII) format.
- Open them in Word. Set Word's preferences (General tab) to "Confirm
conversion at open" so it will ask you whether to open these files as
text or as a Web page. Just say no to conversions. <g> You'll now see
all the text plus HTML tags; if you don't, Word converted the file, so
close it and try again.
- Save the file in .doc format so that you can use revision tracking
to edit, review, and implement all edits. For multiple simultaneous
edits of the same documents, you can try using the "Compare documents"
feature, but it works poorly for overlapping and contradictory edits;
you'll have to address these manually. That's not Word's fault: it's
inherent to the process, which is difficult even for humans.
- Resave the file in "text" format. (***Never*** use Word's export or
"save for web" features; they'll mess up the HTML.)
- Reimport the file into Frame and do any necessary cleanup, which
should be relatively minor. The reimport step is crucial: do this so
that all your Frame documents will be the final ones containing all
the edits. You'd be amazed (check the archives) at the number of
people who seem to believe that the PDF file (or here, the HTML file)
is all they need to retain in their backups.

For more specific details on this process, including a Word macro that
will color all the HTML tags to make them less visible (so you can
focus on the text without the risk of inadvertently damaging the
tags), see Chapter 12 of my book (details below).

------------------------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
------------------------------------------------------------------------
Effective Onscreen Editing:
http://www.geoff-hart.com/books/eoe/onscreen-book.htm
------------------------------------------------------------------------

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals.
http://www.doctohelp.com

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

Previous by Author: Is 'one or more' correct, or should it be 'one or many'?
Next by Author: Review Process for documents in HTML? (Take II)
Previous by Thread: RE: Is 'one or more' correct, or should it be 'one or many'
Next by Thread: Re: Review Process for documents in HTML?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads