When I first started at CM Labs, one thing was apparent: we needed MadCap Flare.

Having used Flare at previous jobs, I recognized it to be the premiere tool for authoring attractive documentation quickly and easily. Unfortunately, the help system I inherited was a DITA/Doxygen system predicated upon a dizzying array of scripts that called each other to build a CHM output.

It was the batch file equivalent of an M.C. Escher work.

20170511-vrej-madblog1

After making my case for Flare, I was off to the races, modernizing the system while making it easier to add and edit topics (not to mention producing output much quicker than before). I even used its handy CHM importing feature to quickly port over the old help into shiny new HTML5.

But the writing tool wasn’t the only thing that needed updating (I’m looking at you, reviews!).

Reviews

Company principles dictated that we have traceability in all things, including documentation reviews. We needed a clear way to follow changes from A to B, and B to C, so that we could always go back and follow the logic that brought us to the end point. This would be useful if ever a feature were to roll back, or perhaps if a new writer came on board and needed to understand the evolution of a chapter.

PDF

The system I found in place often used PDF files for reviews, which wasn’t ideal. The subject matter expert (SME) would review a specially generated PDF and write comments in the file and send it back to the writer (sometimes, even hand-annotated PDF printouts were also used). This was problematic in at least a couple ways:

  1. My work is entirely web-based, so generating a special PDF created extra overhead.
  2. It was hard to follow review iterations, and that back and forth was not reliably recorded anywhere.

Confluence

We use Atlassian Confluence at work as a collaborative information platform, and I’ve heard of some tech writers elsewhere who use this system for their reviews. An SME would write an initial outline, the tech writer would use that information as the basis of a topic, then use the commenting system in Confluence to communicate back and forth with the SME concerning any changes.

This system has some perks in that you can tag coworkers so they’re notified about any pertinent comments or even wholesale changes to the page itself. The page history functionality also gives you the ability to see the content’s progression over time, giving the traceability we desired.

However, in my experience, opening up comments on a Confluence page often leads to digressions, those lengthy conversations in the margins that can continue for some time without any clear resolution about the content, leaving the technical writer in limbo.

Also, it’s not great for reviews of modified, pre-existing content, as it would require the tech writer to copy text from Flare, paste it into Confluence, then paste it back in Flare once reviewed.

JIRA

After putting our heads together, my managers and I came up with a solution that better fit our workflow and company principles: JIRA.

If you’re not familiar with JIRA, it’s another project management product from Atlassian that provides bug and issue tracking, My documentation issues are created as “stories” in JIRA, laying out my tasks in a clear list or table view. Since everyone in the company is using this tool, why not integrate it with doc reviews?

The idea was that we’d create a review file and attach it to the relevant JIRA issue. I then add a comment, tagging the SME, asking him/her to please review the attached file. It’s easy, traceable and uses tools with which coworkers are already familiar.

The next question: what kind of file to attach? To continue using annotated PDFs was an inelegant solution to the problem.

MadCap Contributor

That’s where MadCap Contributor comes in. Contributor is a content review tool that specifically integrates with Flare, making SME reviews seamless.

To get the ball rolling, the tech writer:

  1. Right-clicks a topic (or a group of topics)
  2. Selects Send For Review….
  3. Saves the resulting FLTREV file
  4. Attaches the FLTREV file to the JIRA issue and tags the SME

20170511-vrej-madblog2

In fact, to help out my co-workers, I wrote a Documentation Review Process post in Confluence, the steps of which I’ve reproduced below:

  1. The technical writer attaches the review package (.fltrev file) to the JIRA issue in question, with the writer’s initials and revision number of the package added to the file name.
  2. The SME picks up the package from the JIRA issue.
  3. The SME opens the package in MadCap Contributor and adds comments where necessary. (Select “Use Free Review” if this is your first time installing Contributor.)
  4. The SME re-attaches the annotated package (the FLTREV file) to the JIRA issue, replacing the writer’s initials with his/her own, leaving the revision number as is.
  5. The technical writer re-imports the package into MadCap Flare and makes any necessary changes.
  6. If necessary, another iteration of this process occurs, with the revision number increased by one.

I always make sure to helpfully add a link to the Documentation Review Process when asking for a review, just in case the SME doesn’t remember the steps or it’s the SME’s first time reviewing.

Parting Thoughts

At first, you might come up against a little reluctance from your coworkers about having to install extra software on their machines. Don’t worry though, once you explain how simple it is to add comments directly to the Contributor file, they’ll be on board, making the review process much more streamlined than any of the alternatives used in the past.

If you’re already using these or similar tools at your office and are looking for a better review process, give this a shot. It’s definitely helped us out in implementing a unified, quick and traceable review process that’s easy to learn and follow.

About The Author

Vrej Hezaran

About Vrej Hezaran

Vrej Hezaran is a computer engineer (B.Eng.'04, McGill University) with over a decade of experience in technical writing. After school, he started out as a programmer in the mobile games industry before gravitating towards the intersection of language arts and technology. Outside of work, Vrej enjoys writing fiction. His first book, the comedic science fiction story "The Predicates of Fate", was published in May 2014 by Champagne Books.

Last Modified: May 11, 2017

This entry was posted in MadCap Contributor, MadCap Flare, Tutorials. Bookmark the permalink.

Comments

  • Sanjay Srikonda May 11, 2017 at 2:07 PM

    What about costs associated with the reviewer package? The more reviewers you have, the more of the reviewer licenses you’re going to have to purchase. From the Madcap purchase site, I’m seeing that the cost of Contributor is $348/license. Does not say if that is per install, but having had conversations in the past about Contributor with madcap, I think this was the price per user. Contributor-exported files cannot be reviewed by anyone using a non-contributor review package.

    My suggestion and this is what I’ve done in the past is to generate the topic or even preview it in Flare and then copy the previewed HTML and post it in a Confluence page. Yes, conversations “can” go off the rails, but that’s your job as a TW to keep it on track and monitor the topic, IF your company already has Confluence, then they’ll more likely have the necessary licenses for all your reviewers. Adding a new software that your reviewers will have to install and use just adds another layer of complexity to your review process.

    • Vrej Hezaran May 12, 2017 at 6:37 AM

      That’s exactly why I instruct people to use the free version of Contributor.

      “The SME opens the package in MadCap Contributor and adds comments where necessary. (Select “Use Free Review” if this is your first time installing Contributor.)”

  • Una Cogavin una cogavin May 22, 2017 at 12:23 PM

    As a Tech Pubs Manager, I want to be confident that all the content my team is writing gets a full technical review before the content is published. The only way to ensure this is to have my team use the same review process that ensures traceability and transparency. If you are using MadCap Flare, then Contributor is a great way to go. Its interface is not all that dissimilar to MS Word, which most people can muddle through. Vref is correct that using Contributor to review and annotate is free. It’s only when you want SMEs to write (contribute) that you will need to purchase the software. Even then you can purchase a floating license to keep costs down. My only complaint, and it’s a big one, is that Contributor does not run on Mac OS. Most SMEs use Macs now so it’s a big hurdle. I have managed to overcome this by installing Contributor on a virtual machine running Windows. In fact, putting the review package on the VM allows multiple reviewers to add comments, which my writers have loved in the past…instead of having to combine review comments that contradict each other. I love the idea of using JIRA to track the review process. I’ve used it many times. It’s an excellent way to ensure your SME has time to review the content within the sprint because it is an assigned task on their story board.

    • Vrej Hezaran May 23, 2017 at 10:59 AM

      Great, I’m glad it’s working for you.

      Everywhere I’ve worked, Windows PCs are the norm so I’ve not encountered your particular Mac situation. I’m glad you found a way around it.

      • Paul Pehrson June 6, 2017 at 3:57 PM

        Where I work, the mac issue is a significant hurdle. Most of our developers are using macs, so it is an important consideration for us. I wish Contributor were a web-based tool integrated with MadCap Central, where you could assign reviews, have them completed, and tracked in your GIT repository for review. THAT would make Central more broadly interesting to people, in my opinion.

  • Charles Jeffrey June 6, 2017 at 10:13 AM

    I am struggling a bit with review of content authored in Flare. I am sole technical writer for several products, each of which has html5 help target. I have a single subject matter expert for each product. I am generating a PDF for one, and a Word file for the other. I then manually transfer edits and image updates to Flare. I have considered Contributor, but struggled with the reality of having to update large numbers of topics in what is an Agile design environment. It seems appropriate when smaller number of topics are being updated. I am also atuned to the need of my SMEs to not have to learn a new tool. They all know Reader and Word. Any suggestions? BTW, we have quarterly product releases that require document updates, and one that is released annually. We are a Windows environment. Only two authors, both have MadCap suite.

    • Vrej Hezaran June 15, 2017 at 11:59 AM

      I would still suggest trying to implement what worked for me. I know there’s always resistance to learning new tools but there’s hardly anything to learn at all in Contributor from their point of view. Once it’s installed, it’s literally highlight a word (or phrase) and type in the margins.
      Hopefully, if this scenario sounds like something that would work for you, you can get management to buy into the idea and help you convert stubborn SMEs to see it your way.
      I hope that helps!

  • Basil Pesin July 25, 2017 at 8:08 AM

    I believe the precondition of every process is to efficiently leverage the existing technology, services and practices of a company. Moreover, the process is ought to be compatible with the existing corporate culture and budget.

    The system proposed by Vrej addresses its two primary goals: traceability and a clearly-defined progression (and each link in the chain has a clear beginning and an end, which is crucial). It makes use of the services already in place (JIRA) and does not require any additional investments on the part of his employer. Consequently, this is an efficient and reliable solution.

    Having said that, I do think that it is important to look at the reasoning provided in this article rather than than merely attempt to implement the process itself. There are a number of prerequisites for this plan, including but not limited to operating in a predominantly Windows environment, access to a good database tool and the willingness of the SME to install and use a new application.

    The most important part, in my opinion, is to make sure that your company takes documentation seriously. Having a clearly defined process (such as the one Vrej presented) will definitely help!

Have Something to Say?

Your email address will not be published. Required fields are marked *