Hi I hope this is the correct forum for my question.
I am a technical writer for a software company .We need a comprehensive document review cycle to efficiently process our documentation.
I need to be able to send my documents to a group of SMEs for review, comments and if possible suggested track changes.
The process should be iterative until the required content is achieved.
Is Collaborate the only solution and if so I am correct in assuming that each SME would need a copy of Collaborate to open my created documents and review as mentioned.
Is this the case or are there other alternatives with RoboHelp to achieve the same result?
You could also do it via Review PDFs and Conditional Build Tags – that’s what I do with one of my RH projects. Topics are tagged with a WIP CBT first, Review PDFs are created & circulated, comments added & then the topics are edited based on the comments. When approved, the topic’s CBT changes & is ready for help generation in the SSL.
Can you explain WIP CBT?
My apologies if the question is a bit basic I am new to RoboHelp
“WIP” = “Work in Progress” – you can call your “not ready” tag anything you want
“CBT” = “Conditional Build Tag”
I suspect you may be confusing Harvey with your mention of using the Conditional Build Tag (CBT).
I'm going to crawl out on a shaky little limb here and hopefully elaborate on this.
I suspect you create and apply the CBT so that the topic under scrutiny is left out of any generating you would do. You don't want it in the output until the review cycle has been completed, right?
So Harvey, assuming I'm understanding correctly, that would be the reason for using the CBT. The review process and creating a PDF used for review does not in any way have a dependency on applying a CBT. Jeff is simply doing that for his own purposes.
Cheers all... Rick
Exactly right – new topics currently being authored (or sections of already approved topics) are tagged with the WIP tag to keep them out of the help until they’ve gone through all their review cycles. When they’ve been blessed, the WIP tag comes off and the topic makes it into the next help build.
Yes one priority is that the documents in the review cycle should not be
included in the generation process.
Actually Rick perhaps I can elaborate on my (and the company I work for)
and their requirements:
They are a relatively new company who up till now only required PPTs and
basic User Guides(in Word) for their product range.
Now they are looking for an appropriate authoring tool to handle the
- Single sourcing
- Multiple format creation
- Web based on-line help publishing
- Document synchronization
- SME document review cycle
- Reliability (stability)
The senior product manager who has asked me to create a comparison of the
available authoring tools and their suitability has emphasized the need for
a review cycle feature so that the SMEs can review the docs and make
comments and perhaps track changes. Is the Collaborate tool an overkill for
this purpose? I think she really wants to set up a sort of semi automatic
flow where each SME can get an internal notification of a document for
review in their domain, access the document make changes comments then
return it to the document repository
Each SME in the project would follow suit and then I would receive
notification of the completed review make changes and resend the document
for further reviews in an iterative process.
So really my main question is whether Robohelp combined with Collaborate
would be suitable tools to carry out this process in a semi automatic
Hello again Harvey
I'm going to first ask that we clarify exactly what you are meaning when you say "the Collaborate tool".
This would suggest (at least to me) that you have either discovered a different tool from RoboHelp that is called "Collaborate" and you want to use it in conjunction with RoboHelp somehow. or possibly you are using RoboHelp (2015 Release) (I don't think I've seen any mention of the version of RoboHelp you are considering or using) and you are referring to the tab named "Collaborate".
Can we clarify that a wee bit please?
My knowledge of RoboHelp covers only the basics of RH9,
I know that RH ticks many of my requirement boxes listed in my last email,
except perhaps a comprehensive Review cycle
To my knowledge RH on its own can only produce PDFs for review and if I'm
not mistaken this does not allow for track changes.My company's
requirements seemed way beyond this so I researched some other
applications of Adobe and the only other application I found that seemed to
cover this sort of feature was a tool for authoring named Collaborate
which perhaps is not suitable at all.
So if you are not aware of this tool perhaps I am looking for a solution
that does not exist. I did see something in Madcap Flare that could achieve
this and I hoped that due to the similarity in authoring features I could
achieve this with RH.
kind regards and thanks again for trying to help,
Okay, I think we are now all on the same page.
RoboHelp does have a "Review" process. As you have indicated and seem to understand, you create a PDF for review that contains the content to be reviewed. You then provide that PDF to end users. The only tool your end users need for this will be the totally free Adobe PDF reader. (and the knowledge to use it to mark things up).
So you tell RoboHelp to spit out a PDF for review, then you make that PDF available to the end user. They mark it up with comments and whatnot, then they advise you they are finished and inside RoboHelp you import the PDF comments and it all shows up inside RoboHelp.
That part seems to work fairly well, but I suspect that where things will fall short in your own eyes (and possibly management's) is the "track changes" aspect. With RoboHelp, although there is the possibility of using this workflow to note changes, I suspect you are asking about something along the lines of a permanent database of when a document was changed, what was changed and by who. And nothing inside RoboHelp would actually do that for you. I'd be surprised to hear that even Flare manages that. But I've never been a Flare user, so I can't speak to that. I know my buddy johndaigle plays with Flare, so maybe he knows and will chime in here.
Now if you are using the RoboSource Control product that ships with RoboHelp, I believe you have an ability to "roll back" a topic to an earlier version. But even then, I'm not sure if any sort of report or whatever exists to easily list what was changed and suchlike.
I know this was a bit of a thorny issue for me back in 2003/2004 for tracking changes in documents. What I ended up doing was creating a DHTML drop-down at the top of each topic. Inside the drop-down I had a table listing dates and changes to track them on a document by document basis. I simply edited the table and added information as needed.
And perhaps I'm totally misunderstanding the requirement entirely!
Your explanation is right on, Rick.
Perhaps it will help Harvey to watch a video I created a long time ago that shows the PDF Review process in action. It was done for Adobe RoboHelp 9, but the workflow is essentially the same today. It's on Adobe.TV (around the 3:20 min marker) - Using RoboHelp 9's Collaborative Feature
Further, there are few semantic points which may cause confusion. I'll try to sort those out.
#1 - PDF Review solution for SMEs
The PDF Review works extremely well and is free for the SMEs to use because they are using the free PDF reader.
Flare has a separate product called "MadCap Contributor" which costs an additional $348 for a perpetual license (depending on various options.)
MadCap Contributor does have a rather limited "annotation" feature which is free but you have to install a trial version of Contributor for it to work, then run it in annotation mode.
That's why the familiar and free Adobe PDF Reader is a much easier solution.
#2 - Tracked Changes for Authoring Team
As Rick explained, RoboHelp has a "tracked changes" feature that works very similar to Word. It's great for authors to add/make changes, etc. By turning the feature on, authors on a team can then view those changes/comments. So "tracked changes" can be thought of as a feature for authors, while "PDF Review" is more of an SME review solution.
#3 - Source or Version Control (either RoboSource Control, or third-party solution)
This would be a solution in order to archive each version of a topic, file or entire project. It also provides a way to compare different versions of a topic side by side and allow for "rolling back" to a previous version if desired. And yes, it does provide the ability to create reports on various changes.
Hopefully this will address the understandable confusion.
Adobe Certified RoboHelp and Captivate Instructor