How can I highlight changes in HTML output from Flare, based on branch diff?
We use Madcap Flare for a large documentation set, with HTML output. (Flare source is a very HTML-y XML with some Flare-specific additions.) We use git for source control and new work is done on branches. This means that at the end we have a git pull request (PR) that can show a diff between the branch and the main (master) branch. This diff is very helpful for reviewing a PR, if you're comfortable reviewing by reading the raw XML.
Some of our reviewers would prefer to look at the changes in the HTML output. That's fine in one sense -- we can do a build from the branch, so reviewers can see what the documentation looks like. But that just gets you a build; reviewers still have to dig around to see what parts changed. We can give them a list of changed topics, but if a topic is long and the small-but-important change is those two paragraphs most of the way down, then either the writer has to construct detailed instructions for reviewers or reviewers have to scan everything looking for the change. I'm looking for a way to make the specific changes more visible in the HTML output.
We use Jenkins to manage our builds. Jenkins checks out the branch from git in order to do the build. Git knows where the diffs are on the branch. Is there a way to feed those git diffs into a Flare build (this probably involves preprocessing the source) so that in the output, diffs are highlighted? If showing deletions is hard, is there a way to at least mark, at the paragraph level, where there were changes? "Mark" can mean changebars, a font color change, an icon at the beginning of the paragraph -- I don't much care what the marker is, as it'll only ever be seen in these review builds.
This question is different from How can we make reviewing HTML documentation easier?. That question asks about ways to help reviewers attach their comments to specific changes; this question is about identifying those changes in the output.
The ideal answer to this question would describe an automated path (no human intervention after setting it up) from the git diffs to highlighted changes in the output HTML. A preprocessing step that locally modifies the XML source to, say, wrap font tags to change the color around changed parts before running the build would be fine. (This build never checks anything in, so it doesn't matter if it alters the Flare source after checking it out.) If that's hard, then we could work with a solution that shows, for each changed topic, the diff and a link to the right place in the output. Perhaps, based on comments, we might be able to use Flare index tags or bookmarks and git "export patch" to do that. It still has to be automatic, generated from the git diff, though; asking writers to manually mark changes isn't going to work.
2 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
Even if you could find a way to format dif output in HTML, that in itself would not give you the dif navigation tools that you get from a dif tool (next change, last change, etc.). One way to very quickly get a navigable WYSIWYG dif of two HTML documents (old and new) would be to open them both in Word and use the compare documents function.
This is likely to give you a more readable display, since traditional dif displays are optimized for comparing code, Word's compare documents is optimized for comparing documents.)
Oxygen XML Editor also has a XML dif utility, but your reviewers probably don't have a copy of Oxygen or any similar XML editor, but they probably do have Word.
Word would also give reviewers a simple way to add comments to the dif they are reviewing.
Apparently it is also possible to open word in compare documents mode from the command line with a little bit of code, so you might be able to automate the whole thing: https://social.technet.microsoft.com/Forums/office/en-US/fc2d1374-1542-420e-bd36-875113217bd6/can-you-initiate-word-2010-by-passing-2-documents-to-it-for-comparison-command-line-string?forum=word
0 comment threads
We did not find an off-the-shelf solution to this and built our own. I'm not the author and can't release the code, but here is an overview of the approach.
Flare versions from 2016 onward support adding pre- and post-build steps to a build target. We modified our "branch build" target to call our "get-diffs" Python script as a pre-build step. This script modifies the locally-checked-out XML source for our doc, which Flare then builds in the main build phase.
The script uses the git package to identify files that have been added, deleted, or changed. For changed files that exist on master and on the branch, the script does its own diff and inserts formatting to show it into a new XML file. (We use the pink and green highlighting familiar to git users.) This is a file that shows the full diff and in the output is named original-title-diff.html. The script modifies the original file (original-title.xml, in this example) to insert a prominent link to the diff page. This allows reviewers to read the topic "as it is" while also being able to inspect a diff; we found this less invasive and more likely to produce useful review feedback than just giving people the doc with inline diffs.
The script also generates a list of links to pages with changes, each with links to the git commits that made them, and inserts it into the build. This gives us a place to record new topics, which have nothing to diff against.
This approach is not bulletproof; changes to structure, like moving things around in the table of contents, do not show up, and diffs in snippets don't seem to work right. Our script doesn't report deleted files, though I don't see why it couldn't (it hasn't come up). But a 90% solution is still a big improvement for us, and people who want that last 10% and don't mind reading XML source can follow the links to the git diff directly.
0 comment threads
0 comment threads