4

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.

  • Does it need to be with a Flare build or could your reviewers also use a different tool like Compare Suite (if you scroll down to "Use Compare Suite to compare various Word, PDF, HTML documents" you see a screenshot; I haven't used the software but it looks like that's basically what you want). – Secespitus Mar 17 at 21:05
  • 1
    And about your older question: I didn't see the suggestion to use the cloud-based services from MadCap I found here under "Contribute and Edit Content with the Lightweight Editor". If your company is open to a new and cloud based tool that might be helpful to you. Or was there a reason not to use something like that? – Secespitus Mar 17 at 21:05
  • 1
    @Secespitus oh interesting; I hadn't seen Flare Central. Moving our content outside our private network probably isn't going to fly for this project, but we have something else that this might be a useful tool for. On Compare Suite, I can't quite tell how it works, but any diff tool would need to be able to handle an HTML doc set with ~10,000 individual topics. (Hmm, WinDiff on HTML output? Haven't tried that.) We've already rejected PDF as a viable review format. – Monica Cellio Mar 17 at 21:12
  • If you've got multiple files that are getting compiled into one html this probably isn't helpful; but, a possible way forward would be to export those Git diffs as summaries (most diffing tools have a way to show just the changes). Then with that on one monitor and the html on another your reviewer could CTRL+F through all of the changes listed in the summary to view them in context. But XML diffs can be atrocious to manage if one side has been reformatted. You'd be looking for something like "export patch" those are usually human readable to an extent. – Kirk Mar 27 at 20:38
  • @Kirk it's many XML files to many HTML files (with a common table of contents). Topic pages are 1:1, aside from the effects of xincludes. – Monica Cellio Mar 28 at 1:04
3

I think you can use diff2html which actually publishes diff versions of git as html with colored and presentable font. This is a reliable library. Even Jenkins use it. So you can directly integrate in Jenkins's build process pipeline, that publishes your diff's html automatically during build. Here's a good get started tutorial from Jenkins' official wiki page. Here's a demo diff from diff2html.

  • 2
    Oh, that looks useful! It's not embedded directly in the doc (HTML) output, but a diff like this alongside that output is better than just a list of changed topics! It looks like it can do the diff from whatever point I specify (not just the previous build), too, which means we can accumulate all the diffs for a branch over multiple commits. Looking into this tool. – Monica Cellio Mar 29 at 17:43
2
+500

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

  • Our doc set is too large for Word. In addition, most of our reviewers use Linux. I'm looking for a solution that fits with our existing tools. Thanks. – Monica Cellio Mar 31 at 2:13
0

MadCap's pre-Central answer is still in the Flare toolset - "Flare Contributor" which sets up a reviewing doc - but it requires the SME to learn a new tool that's basically Flare lite. I think if your org has the resources and isn't adverse to external cloud solutions, Central will be so close to what you're looking for as to be a legitimate answer.

  • 1
    Can you explain how to use that to show the diffs (which can be gotten from git)? Does this tool use git integration and do that for you? – Monica Cellio Mar 18 at 17:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.