Exporting individual topics for review?

[ccardimon]

I need to send a revised topic to an SME and I'm looking for a dead simple method (if there is one) of exporting individual topics for review.

[MattyQ]

Do you want to avoid using the Send for Review feature because of the Contributor requirement?

[ccardimon]

Do you want to avoid using the Send for Review feature because of the Contributor requirement?

Correct. The Contributor requirement is a deal-breaker here.

[Nita Beck]

The simplest option is to preview the topic in Flare and then print it to a PDF and send that to your reviewer, who can then comment on the PDF. An advantage of this method is that the PDF will look more or less as you intend it to look when you produce your real target. A disadvantage is that you will need to incorporate changes by hand in Flare.

Alternatively, you can create a Word review target and a review TOC to associate with that target. You can then put as many topics as you want on the review TOC and generate the Word target. (I'm assuming, BTW, that you've got page layouts in your project.) An advantage of this method is that your reviewer can use Word's Track Changes to make changes. A disadvantage of this method is that the formatting in the Word doc is highly likely not to faithfully resemble the real target, so you will need to educate your reviewer NOT to fret about formatting. Another disadvantage is that you will need to incorporate changes by hand in Flare. (FWIW, I typically use this method for my reviews.)

[I had already written the following while you other fellows were nixing Contributor, but I'll leave it anyway for other forum users' benefit...]

Another alternative is to have your reviewer use the free version of MadCap Contributor, which would allow your reviewer to add annotations (akin to comments in Word) but not to change content. From within Flare, you would prepare a review package with one or more topics to send for review. Your reviewer would then open the review package in Contributor and add annotations where needed. When finished, the reviewer would return the review package to you, which you'd process right within the originating Flare project.

If you wanted your reviewer to actually edit the Flare topics, the reviewer would need the paid version of Contributor. An advantage of this method is that, once you get the reviewed topics back into the originating Flare project, you can step through the reviewer's changes and accept or reject them. A disadvantage of this method (in my experience) is that the reviewer may have difficulty using Contributor, as its editor is a scaled back version of Flare's XML Editor, and we all know that that editor takes a little getting used to. But Contributor is definitely the way to go if your workflow requires reviewers to be able to edit the files directly.

[ccardimon]

Thanks, Nita!

[keuler]

Thanks for this timely thread. I've been wondering about non-Contributor methods of review. I'm glad to see that it's easy to print commentable PDFs.

For us, it's not so much the cost of Contributor, but that there's a lot of non-Windows reviewers in my company.

Feature request for Madcap: Update the docs to suggest the non-Contributor review method (using PDF or Word) as an alternative. Also, updating the workflow to further develop the PDFs/Word review option.

Kurt
trial copy newbie

[keuler]

Nita- Do you know of an efficient way to include multiple topics into a PDF for review? The method you describe above appears to only work for the one topic at a time (the "active file"). Perhaps the Review TOC method you describe for Word also works for PDF?

Thx.

-kt

[Nita Beck]

Where above I describe using a Word target for review, substitute a PDF target. You'll need the PDF target, a review TOC to associate with that target, and page layouts to associate with either the target or specific TOC items.

[dorcutt]

Like many people, I send a Word version, and tell the reviewer to disregard formatting issues there. However, I also send along the latest PDF version so that my particularly vigilant/paranoid SMEs or coworkers can check the PDF version to see how the document will actually look in production as things currently stand. This has actually helped my reviewers catch some formatting errors that the "disregard formatting in Word" method alone would have missed.

Edit:
Like Nita, I also have a Word and PDF review target set up that I dump topics into for review. It also comes with a topic for instructions ("disregard Word formatting, check formatting in PDF if you're curious, blah blah blah").

[keuler]

Thanks Nita and Dan.

I suppose one could maintain one or more review TOCs and copy topics in and out as needed.I suppose the topics can be opened/edited with in the review TOC, and the same topics in the main working TOC(s) would be updated too (They'd need re-publishing, of course.)

KE

[Nita Beck]

I suppose one could maintain one or more review TOCs and copy topics in and out as needed.I suppose the topics can be opened/edited with in the review TOC, and the same topics in the main working TOC(s) would be updated too (They'd need re-publishing, of course.)

That's exactly what I do.

[ccardimon]

I suppose one could maintain one or more review TOCs and copy topics in and out as needed.I suppose the topics can be opened/edited with in the review TOC, and the same topics in the main working TOC(s) would be updated too (They'd need re-publishing, of course.)

That's exactly what I do.

Me, too.

[ChoccieMuffin]

I have a "Review" target and a "Review" TOC that I can happily change at will, without upsetting my real targets.

Edit the Review TOC to include the topics you want to review.
Edit the Review target to include conditions such as "Question" or "Comment" that may be questions to your reviewers for them to answer. (If you use a separate "Review" set, you can avoid having to change your real target and then perhaps forget to change them back again.)
I typically generate a PDF and get reviewers to add comments to the PDF which I then input manually, which means they have the formatting (more or less) correct, additional comments notwithstanding. I can also include all my online help only topics, so that it all gets checked.

[keuler]

Great ideas. Thx!

[sdcinvan]

Oh wow, I discussed this exact topic about a year ago.

I suggest you bombard MadCap with feature requests like make an OS agnostic version of Contribute (i.e. web based version) or integrate better with Google Docs or other online SAAS(?) editing solution.
Go here: https://www.madcapsoftware.com/feedback ... quest.aspx

I'm in the same boat because I have about 40 potential SMEs and not one of them using Windows. Even if they did use Windows, it isn't appropriate to instruct them to waste their time installing a Windows program for a one-time documentation review.

I have since worked out a workflow that is by no means ideal but it works for now....

1) I build all draft work in Google Docs. Two huge advantages with Google Docs is that it allows for real-time collaboration simultaneously by multiple editors.
2) Once the draft work is locked down, I print the draft to HTML (primarily to grab the pictures)
3) Build the final chapter in Flare by way of copy/pasting content from the Google Doc.
4) Final reviews are completed via PDF (I really dislike this method because I cannot control the doc, once it is in the wild and there is absolutely no collaboration).
a) I did experiment with Adobe Acrobat Collaboration via a WebDAV but this was very, very painful and problematic for contributors.
b) There is also the free online PDF collaboration tool called Crocodoc (see: https://personal.crocodoc.com/accounts/ ... s/profile/) but it has a number of issues, such as: lack of security and the
likelihood that it could vanish at any time (the new'ish owners, Box, have very little interest in its upkeep).
5) Once the document is published, I push back my Flare content to Google Docs by way of a custom conversion tool. That way, the Google Docs content is synchronized for the next update iteration.

Let us know what works for you.

[dorcutt]

5) Once the document is published, I push back my Flare content to Google Docs by way of a custom conversion tool. That way, the Google Docs content is synchronized for the next update iteration.

I remember that thread from a year or so ago and was wondering off and on how you worked it out. That custom conversion tool sounds like a pretty awesome solution.

Also, I think you're completely correct. A web-based collaboration version of Contributor definitely seems to be The Answer to this issue and would probably sell like hotcakes. "Here install this to review my document for me" just does not work for SMEs, as anyone with even the slightest bit of experience with SMEs can attest. Sending a link for them to click with a super-intuitive, Word-like Track Changes interface maybe would be amazing.

[sdcinvan]

I remember that thread from a year or so ago and was wondering off and on how you worked it out. That custom conversion tool sounds like a pretty awesome solution.

I should explain that it is still a very rough work in progress and the most limiting factor is that it isn't bi-directional. Ideally, I would love to sync Google Doc changes directly into Flare (similar to how MadCap Contributor works). But this is a very daunting challenge.
Here is a reference to the tool I modified: viewtopic.php?f=13&t=20257&p=105305&hil ... on#p105305

Also, I think you're completely correct. A web-based collaboration version of Contributor definitely seems to be The Answer to this issue and would probably sell like hotcakes. "Here install this to review my document for me" just does not work for SMEs, as anyone with even the slightest bit of experience with SMEs can attest. Sending a link for them to click with a super-intuitive, Word-like Track Changes interface maybe would be amazing.

Careful there.
I'm not so certain that it would sell like hotcakes. If anything, it might make Flare more attractive to a new customer. If such a tool existed, I would suggest a free basic version and a paid enterprise version, similar to the current Contributor model.

If there is anything happening in regards to an online collaboration tool, MadCap is certainly quiet about this.

[sdcinvan]

If an online collaboration tool is important to you, please consider spending a few minutes to send MadCap a feature request: https://www.madcapsoftware.com/feedback ... quest.aspx

[KEMPer]

This discussion is interesting to me. We are currently looking to move to Flare and are very happy with most aspects of the Flare product with the notable exception of the reviewing model in Flare. We cannot use Contributor and we have yet to come up with a suitable workflow model.

The suggestion for some type of online collaboration tool sounds great. I wonder has Madcap considered it at all?

[ChoccieMuffin]

This discussion is interesting to me. We are currently looking to move to Flare and are very happy with most aspects of the Flare product with the notable exception of the reviewing model in Flare. We cannot use Contributor and we have yet to come up with a suitable workflow model.

The suggestion for some type of online collaboration tool sounds great. I wonder has Madcap considered it at all?

If you're looking to purchase Flare, I'm sure the sales team will be very happy to help you. Do contact them, and they will bring in any techies to the discussion as needed. They may be able to discuss your requirements and come up with a suitable solution. (But yes, I find the review cycle is always problematic, whatever tool is used...)

[cayennep]

Lack of internal review + windoze requirement are the main reasons I've just researched and tried every single other option. I'm likely returning to Flare, which I like a lot apart from these two things, because the alternatives are frankly much worse.
That said, the Mac feature has been in front of them for quite some time. Apparently they're still considering it, but no insight into whether it's actually being pursued.
For review, I just spoke with support and made two suggestions, which they entered as feature requests:
1. implement disqus integration, and ideally, some way to host the output in the cloud. Disqus is pretty easy, but a plugin/config option from Flare would be helpful. The hosting would be very useful, as more and more orgs are SaaS/Cloud, throwing up a web server is no longer trivial.
2. Ability to round-trip Word - maybe like the link to an imported Word doc, make a way to bring a reviewed/addressed (I'd have to use Track Changes in Word and resolve all the feedback) Word doc back into Flare and replace/update the original content.

Any other ideas? I recently used a wiki - asked reviewers to post the topic title, then their notes, for each topic reviewed. They can even copy/paste content and provide the suggested rewrites, if they're heavy-handed editors. This at least allowed everyone to see the comments from everyone else. I actually doubt they do this, but it is sometimes a requirement.

Another trend is more collaborative work, so reviewing is more and more important.

Tips on how others have managed appreciated!

[sdcinvan]

Lack of internal review + windoze requirement are the main reasons I've just researched and tried every single other option. I'm likely returning to Flare, which I like a lot apart from these two things, because the alternatives are frankly much worse.
That said, the Mac feature has been in front of them for quite some time. Apparently they're still considering it, but no insight into whether it's actually being pursued.

But a recent Mac can run Windows quite well... the only real annoyance is the Windows license requirement.

For review, I just spoke with support and made two suggestions, which they entered as feature requests:
1. implement disqus integration, and ideally, some way to host the output in the cloud. Disqus is pretty easy, but a plugin/config option from Flare would be helpful. The hosting would be very useful, as more and more orgs are SaaS/Cloud, throwing up a web server is no longer trivial.
2. Ability to round-trip Word - maybe like the link to an imported Word doc, make a way to bring a reviewed/addressed (I'd have to use Track Changes in Word and resolve all the feedback) Word doc back into Flare and replace/update the original content.

Round-tripping with Word is very messy! I am disappointed that MadCap recommended this. You are better off copy/pasting text.

I really wish MadCap would look into supporting round-tripping with the most ubiquitous online-editor in the world, Google Docs. If they supported round-trip editing with Google Docs, I'd be the happiest technical writer in the world!

Any other ideas? I recently used a wiki - asked reviewers to post the topic title, then their notes, for each topic reviewed. They can even copy/paste content and provide the suggested rewrites, if they're heavy-handed editors. This at least allowed everyone to see the comments from everyone else. I actually doubt they do this, but it is sometimes a requirement.

This method only works well if your documentation is fairly plain and doesn't rely on formatting and images.

[sdcinvan]

Hello all,

As many of you know, I've been advocating for some type of OS agnostic version of MadCap Contributor. Because MadCap Contributor is a Windows only product and all my SMEs are Linux based, I was forced to find an alternative for real-time content collaboration.

For the past three years, my 'solution' for document collaboration is to use Google Docs. It works reasonably well by solving some of my main issues, in particular, all my SMEs can access and edit draft content without any hindrances. The only significant drawback to using Google Docs is that lack of round-tripping content to/from MadCap Flare. The content synchronization becomes especially tedious and time consuming when you have over 50 docs / 1000 pages that are constantly being updated. Because of that, I am always seeking a better solution... even if that means dropping MadCap Flare for another platform that fits my requirements.

Another Solution ?
I recently found a new on-line collaborative tool called Annotate from www.annotate.co. It allows for online and real-time content collaboration from a variety of document sources (my choice is PDF) and integrates with both Google Docs and Dropbox. What I like about the product is that they allow free use for one admin and five contributors (great for getting a reasonable test) and it does a perfect HTML5 conversion of PDF documents. Collaborative edits can be exported but there is still no round-trip editing available. You can't have it all, I suppose.

I am currently experimenting with this tool and will report back later.

[cayennep]

But a recent Mac can run Windows quite well... the only real annoyance is the Windows license requirement.

But I don't want to run windoze, I want to use Mac. It's not about how it runs, at all...

Round-tripping with Word is very messy! I am disappointed that MadCap recommended this. You are better off copy/pasting text.

They didn't recommend it, I suggested it.Yes, it's messy, but round-tripping would = not messy. Else it's not round-tripping.

I really wish MadCap would look into supporting round-tripping with the most ubiquitous online-editor in the world, Google Docs. If they supported round-trip editing with Google Docs, I'd be the happiest technical writer in the world!

ubiquitous, yes - but it's terrible. trying to do anything more than basics is really bad, can't see how round-tripping googledocs would ever work.

Any other ideas? I recently used a wiki - asked reviewers to post the topic title, then their notes, for each topic reviewed. They can even copy/paste content and provide the suggested rewrites, if they're heavy-handed editors. This at least allowed everyone to see the comments from everyone else. I actually doubt they do this, but it is sometimes a requirement.

This method only works well if your documentation is fairly plain and doesn't rely on formatting and images.

[/quote]

Reviewers should not be commenting on formatting. This is just a way for more extensive feedback, where needed, and a way for reviewers to see each other's comments.

[cayennep]

Hello all,

Another Solution ?
I recently found a new on-line collaborative tool called Annotate from http://www.annotate.co. It allows for online and real-time content collaboration from a variety of document sources (my choice is PDF) and integrates with both Google Docs and Dropbox. What I like about the product is that they allow free use for one admin and five contributors (great for getting a reasonable test) and it does a perfect HTML5 conversion of PDF documents. Collaborative edits can be exported but there is still no round-trip editing available. You can't have it all, I suppose.

I am currently experimenting with this tool and will report back later.

Sorry, what does this give you that googledocs doesn't? Just reviewing pdfs instead of googledocs?

I've looked at shared pdf reviews, but more and more companies are cloud/saas and don't have a server to just throw stuff up on.
Review is a big challenge, esp with more collaboration needed.