Re: Marking and Tracking Changes in Frame

[Dan Emory <danemory@xxxxxxxxxxxx>]

Jean:
Your paper, "Marking and Tracking Changes in Adobe Framemaker", is an
interesting compilation, but it is incomplete.

FIRST, there are two types of change tracking, and your paper only addresses
changes made during the review process. The other type involves the tracking
of changes throughout the lifetime of a document, which may be many years.
The latter requires a management system capable of recording and tracking
changes down to the individual paragraph level, and saving all versions in a
database so that any version of any paragraph, as well as any version of the
entire document, can be retrieved.

SECOND, you discuss using other word processors for preliminary writing work
prior to review/edit, and then converting to FrameMaker afterwards, or
converting Frame documents to RTF for review in Word, and then converting
back to Frame for post-review incorporation of changes. Given the many
problems in round-trip (or even one-way) conversions between FrameMaker and
other word processors, as voluminously recorded on the two Framers lists, I
think most enterprises would reject both of these alternatives. In
particular, the problems with preservation of formats, graphics, tables,
colors, variables, equations, markers, cross-references, autonumbering, and
conditional text, as well as mis-translation of high-ASCII characters during
such conversions makes that approach untenable.

There is only one exception I know of, and that's a product called S-Tagger
from TRADOS (price is about $2500 per license, but one license would usually
suffice). S-Tagger takes MIF as input, and produces RTF as output for
editing in MS-Word. The RTF preserves all of the MIF formatting constructs,
and they are retained when it is imported into Word, but those MIF
constructs cannot be altered or deleted in Word. After editing in Word is
completed, the document is saved as RTF and run back through S-Tagger to
restore it to MIF. If any discrepancies are found between the original MIF
and the RTF version of the MIF during the conversion back to MIF, the
document is rejected. Although S-Tagger is intended for language
translations, it could, in principle, be used also for conducting reviews
using MS-Word.

THIRD, you overlook several useful capabilities available in FrameMaker for
marking and tracking changes to facilitate the review process. For example:

1. Prior to commencement of any review process, illegal format overrides and
ad-hoc formatting can be identified and fixed, and the template can be
re-enforced by importing its formats back into the document with Remove
Format overrides turned on. This is a vital quality assurance step that
should precede the review process. I have a paper on this subject entitled
"FrameMaker Template Design and Enforcement", which is available as a PDF
document.

2. Create three FrameMaker character formats, "Was", "ShouldBe" , and "Add"
that are to be used exclusively by reviewers.
        a. The "Was" character format has Change Bar and Strikeout
           turned on.
        b. The "ShouldBe" character format has Change Bar and a color
           (e.g., Red) turned on.
        c. The "Add" character format has Change Bar and another color
           (e.g., Green) turned on.

To change existing text, the "Was" format is applied to it, and the changed
text has the "ShouldBe" format applied to it.

Text that is added which does not change existing text has the "Add" format
applied to it.

Change bars appear in each line of the document where any of these three
character formats are applied.

3. Each change described in step 2 above could have attached to it a comment
marker or comment conditional text that identifies the reviewer, and
contains any relevant explanations for the change. Comment markers or
comment conditional text (including the reviewer's name) can also be
inserted at places where no change or addition was made, but a comment is
required.

The approach described in steps 2 and 3 is certainly superior to the use of
Frame's Document Compare utility, which remains problematic even in V5.5.6.

4. At the completion of the review phase, step 1 is repeated to remove any
illegal formatting introduced during steps 2 and 3.

5. In the post-review phase, the presence of a change bar signals to the
person(s) responsible for evaluating and incorporating the changes that a
change has been made, and the three character formats described in step 2
visually indicate what was done. Any associated comment markers or comment
conditional text provides additional information that may be needed to
evaluate each change. The process is as follows:

        a. If a change to existing text is accepted, the text having the
"Was" character format is deleted, and the text having the "ShouldBe"
character format is converted to the default paragraph format.

        b. If a change to existing text is rejected, the text having the
"Was" character format is converted to the default paragraph format, and the
text having the "ShouldBe" character format is deleted.

        c. If text having the "Add" character format is accepted, the "Add"
character format is converted to the default paragraph format.

        d. If text having the "Add" character format is rejected, it is deleted.

At the completion of these steps, all change bars should have disappeared.

A global search on comment markers or comment conditional text should also
be conducted to assure that all comments have been addressed. Then, the
comment markers or comment conditional text is deleted.

FOURTH, you omit any mention of the even more powerful revision tracking and
change processing capabilities of FrameMaker+SGML (FM+SGML). FM+SGML could
enforce and greatly facilitate the methodology described in steps 1-5 above,
and information about the changes that were actually made to each paragraph
could be permanently recorded in an element attribute. Another element
attribute could be used to record changes that are not the result of the
review process, but which may be vital to a comprehensive review (e.g.,
changes made as a result of Engineering Change Orders (ECO's) and similar
change directives). This attribute would allow reviewers to determine
whether the document reflects the most current configuration of the system
being documented.
=======================================================================
At 12:40 PM 7/9/99 +1000, Jean Weber wrote:
>Some weeks ago (May 26, to be precise) I asked the list, among other
>questions, "What's the usual process for recording insertions and deletions
>made by reviewers of a FrameMaker document?"
>
>I received some very helpful replies, from which I eventually compiled a
>short article. I published the article two weeks ago in my technical
>editors' newsletter, but neglected to let this list know about it. My
>apologies.
>
>If you are interested, here's the URL:
>
>"Marking and Tracking Changes in Adobe Framemaker"
>http://www.wrevenge.com.au/eyrie/tenews13.htm
     ====================
     | Nullius in Verba |
     ====================
Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: danemory@primenet.com
10044 Adams Ave. #208, Huntington Beach, CA 92646
---Subscribe to the "Free Framers" list by sending a message to
   majordomo@omsys.com with "subscribe framers" (no quotes) in the body.


** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **