bell notificationshomepageloginNewPostedit profile

Topic : Technical review process when using FrameMaker I'm an engineer. At my company, engineers seem to spend a lot of time reviewing technical documentation written by people who work in different - selfpublishingguru.com

10.02% popularity

I'm an engineer. At my company, engineers seem to spend a lot of time reviewing technical documentation written by people who work in different offices and time zones. Part of the reason we spend so much time is that we're presented with lots of small questions, one e-mail at a time, rather than being given larger blocks of review tasks overlaid on a view of the complete documentation.

The writers are using FrameMaker. Engineers don't have FrameMaker licenses but know how to use code review tools. My questions are:

Is there a standard way to use FrameMaker where the documentation artifacts are checked in as text files (for example, XML) in a source control system, such that they can be reviewed using standard code review tools?
If not, is there another good mechanism/process that allows tech writers and reviewing engineers to collaborate on shared FrameMaker documents?

Load Full (1)

Login to follow topic

More posts by @Ann1701686

Login to post a comment!

1 Comments

Sorted by latest first Latest Oldest Best

10% popularity

Using code review tools on FM XML has a few drawbacks:

You run the risk that programmers will want to change the XML code, rather than just the text. You'd have to use tooling to make the XML structure read-only and allow changes to the text elements only.
The text becomes less readable due to the inline tags for xrefs, text insets, character styles etc.

PDF avoids all this, and has some additional advantages:

It prevents the reviewers from changing the source text. Engineers aren't writers, as a writer I want final authority over the text in my document.
if you use PDF, you can use the change tracking mechanism in FrameMaker to mark the new text, allowing the reviewer to concentrate on that instead of having to read the entire document.
PDF allows you to have multiple reviewers check a document simultaneously, and you can collect the comments afterward. Or they can review sequentially and react to the comments made by earlier reviewers.
PDF comments allow the reviewer to indicate why a change needs to be made. This gives the writer a better insight into what he's writing about.

Load Full (0)

Back to top