MadCap Software Forums

Hello all,

For various reasons (i.e. SMEs with incompatible OS, inconvenience for SMEs to install Contribute for a short-term review task), I cannot use MadCap Contribute for content reviewing.

Because of the challenges, I was forced to find an alternative solution. My current workflow is as follows:
Step 1) Build outline and draft in Google Docs
Since we subscribe to Google Apps, this allows for excellent draft collaboration.
Step 2) Manually transfer Google docs content into Flare
At this point, the Google Docs draft is locked and becomes obsolete.
Step 3) Publish a daily or weekly beta from Flare to PDF and uploaded to Crocodoc (free cloud-based collaboration)
Step 4) Manually take comments from Crocodoc and apply approved changes to the Flare document.
Repeat step 3 until document is finalized.

As our documentation library grows, this workflow will become much less palatable. There must be a better way! Is anyone in a similar situation where MadCap Contribute is not practical. What is your document review workflow?

Someday, if MadCap releases a cloud version, I think that will solve my SME contribution challenges.

I appreciate your advice.

Thank you.

Have you considered using a Word doc on SharePoint?

kwag_myers wrote:Have you considered using a Word doc on SharePoint?

Thanks for your reply.

SharePoint is not an option because we are primarily a Linux based company. I am one of the oddities using the Windows platform. :]

Besides, that won't work once the content is moved into Flare because that is when collaboration becomes more difficult.

Hi Shawn, it sounds like you want reviewers to be able to edit content directly and you will act as editor for those changes, is that right? I think Contributor is the only option for that, without an additional input/output platform compatible with Linux and that can hook up with Flare, or at least the XHTML is produces... I don't even know if that is a thing. A simple option would be to send out PDFs and request commented files by return (even for online content). You can work through the comments and assign status labels (which are also sortable), e.g. accepted, completed, rejected. You can also collate comments that you receive from multiple reviewers into one copy of that PDF, so you only have one file to work with. Each comment carries the user ID of the reviewer. This is the method I use. It is a bit more work for me (than letting reviewers update content), but at the same time, I have control over the content. And PDFs are easy for reviewers, which encourages more reviews, and better reviews.

We just started using WordPress, which allows you to import/export XML files. We use a single login for all contributors. So far, we haven't had any serious issues.

atomdocs wrote:Hi Shawn, it sounds like you want reviewers to be able to edit content directly and you will act as editor for those changes, is that right? I think Contributor is the only option for that, without an additional input/output platform compatible with Linux and that can hook up with Flare, or at least the XHTML is produces... I don't even know if that is a thing. A simple option would be to send out PDFs and request commented files by return (even for online content). You can work through the comments and assign status labels (which are also sortable), e.g. accepted, completed, rejected. You can also collate comments that you receive from multiple reviewers into one copy of that PDF, so you only have one file to work with. Each comment carries the user ID of the reviewer. This is the method I use. It is a bit more work for me (than letting reviewers update content), but at the same time, I have control over the content. And PDFs are easy for reviewers, which encourages more reviews, and better reviews.

Hello Tom,

Thanks for your reply.

atomdocs wrote:Hi Shawn, it sounds like you want reviewers to be able to edit content directly and you will act as editor for those changes, is that right?

No, I just want commenting (along the side of the doc). What I want is a true collaborative effort... meaning, I want all the reviewer's comments to be seen by others so that there is no duplication of effort and they review each other's efforts. For that reason, your suggestion of distributing a PDF isn't suitable.

For now, I will stick with Google Docs, for draft work and Crocodoc for beta reviews (as long as that lasts).

Thanks

kwag_myers wrote:We just started using WordPress, which allows you to import/export XML files. We use a single login for all contributors. So far, we haven't had any serious issues.

I am intrigued by this idea. Can you tell me (us) more, please?

sdcinvan wrote:...I just want commenting (along the side of the doc). What I want is a true collaborative effort... meaning, I want all the reviewer's comments to be seen by others so that there is no duplication of effort and they review each other's efforts. For that reason, your suggestion of distributing a PDF isn't suitable.

I'm a little confused here. Adobe Reader offers Sticky Notes for this purpose (which are similar to a Comment in Google Docs) and you can share your PDFs on Google Docs. I'm not familiar with Crocodoc, so I don't see the advantage of using a service in addition to Google Docs, as I think you can accomplish the same thing. Or am I missing something?

With our WordPress setup, all contributors have access to the content and it doesn't sound like this is what you're after. You can set it up so contributors can leave comments below each topic, like Flare's Online Help, but I think you will be duplicating your project setup efforts between WordPress and Flare. Unless your projects are rather small, as is the case with our WordPress documents, you may want to look into how Flare's Online Help is setup.

kwag_myers wrote:

sdcinvan wrote:...I just want commenting (along the side of the doc). What I want is a true collaborative effort... meaning, I want all the reviewer's comments to be seen by others so that there is no duplication of effort and they review each other's efforts. For that reason, your suggestion of distributing a PDF isn't suitable.

I'm a little confused here. Adobe Reader offers Sticky Notes for this purpose (which are similar to a Comment in Google Docs) and you can share your PDFs on Google Docs. I'm not familiar with Crocodoc, so I don't see the advantage of using a service in addition to Google Docs, as I think you can accomplish the same thing. Or am I missing something?

Perhaps I should have written "real-time" collaboration. Posting an Adobe document for input via sticky notes, requires the reviewer to download the document and then upload it. Then there is the additional task of merging everyone's comments into one PDF. Or am I misunderstanding something? Because, I see no way this can be done directly inside Google Docs as they only offer a PDF view only tool.

The reason I use Crocodoc is that it allows commenting, like sticky notes, directly into the document, on-line and with real-time collaboration. If I can do the same with Google docs, that would be awesome.

kwag_myers wrote: With our WordPress setup, all contributors have access to the content and it doesn't sound like this is what you're after. You can set it up so contributors can leave comments below each topic, like Flare's Online Help, but I think you will be duplicating your project setup efforts between WordPress and Flare. Unless your projects are rather small, as is the case with our WordPress documents, you may want to look into how Flare's Online Help is setup.

Thanks for the clarification. My documents are upwards of 200 pages.

Shawn, I was intrigued by your description of Crocodocs awhile back and spent some time looking for something that would give me similar features integrated with Google Drive. I'm using Notable PDF, which is a Chrome plugin, to let my reviewers leave notes and annotations in a PDF. So now I can publish a PDF directly from Flare, save it to a shared folder on Drive, notify my reviewers (including a hyperlink to the file), and they can review and annotate the document at their leisure. I then integrate their suggestions into my Flare source and everyone is happier than we were before with other methods.

I'm not sure if this can be done real-time with multiple reviewers, but it is done directly on Drive without having to save a local copy. Notable comes in a free version and Premium (more bells & whistles for a price). The free version has been adequate so far.

ToddPh wrote:Shawn, I was intrigued by your description of Crocodocs awhile back and spent some time looking for something that would give me similar features integrated with Google Drive. I'm using Notable PDF, which is a Chrome plugin, to let my reviewers leave notes and annotations in a PDF. So now I can publish a PDF directly from Flare, save it to a shared folder on Drive, notify my reviewers (including a hyperlink to the file), and they can review and annotate the document at their leisure. I then integrate their suggestions into my Flare source and everyone is happier than we were before with other methods.

I'm not sure if this can be done real-time with multiple reviewers, but it is done directly on Drive without having to save a local copy. Notable comes in a free version and Premium (more bells & whistles for a price). The free version has been adequate so far.

Thanks Todd.

The problem with plug-ins or forcing my SMEs to install anything is that my list of SMEs changes all the time. Asking them...er forcing them to use a specific browser and spend time installing a plug-in is inconvenient, especially, if the SME only needs to look at one paragraph. That is one of the advantages of Crocodoc, the SME doesn't need to install anything and they don't even need to create an account.

Best regards,
Shawn

sdcinvan wrote: Perhaps I should have written "real-time" collaboration. Posting an Adobe document for input via sticky notes, requires the reviewer to download the document and then upload it. Then there is the additional task of merging everyone's comments into one PDF. Or am I misunderstanding something? Because, I see no way this can be done directly inside Google Docs as they only offer a PDF view only tool.

The reason I use Crocodoc is that it allows commenting, like sticky notes, directly into the document, on-line and with real-time collaboration. If I can do the same with Google docs, that would be awesome.

How would it be to upload a Word doc output, setting your upload to convert to Google Docs format? This allows contributors to use GD's Comment feature, and it's real-time.

kwag_myers wrote:

sdcinvan wrote: Perhaps I should have written "real-time" collaboration. Posting an Adobe document for input via sticky notes, requires the reviewer to download the document and then upload it. Then there is the additional task of merging everyone's comments into one PDF. Or am I misunderstanding something? Because, I see no way this can be done directly inside Google Docs as they only offer a PDF view only tool.

The reason I use Crocodoc is that it allows commenting, like sticky notes, directly into the document, on-line and with real-time collaboration. If I can do the same with Google docs, that would be awesome.

How would it be to upload a Word doc output, setting your upload to convert to Google Docs format? This allows contributors to use GD's Comment feature, and it's real-time.

I thought I had tried this earlier on but it failed miserably. I'm going to try that again, now. But I think if I must make a whole lot of css tweaks to output a decent Word doc, it won't be worth the effort.

Tested the Word conversation... now I remember why converting to Word and uploaded to Google Doc (w/docs conversion enabled) didn't work for me.

I acknowledge that some style tweaking will be necessary but Word Target results are hilariously disappointing, and embarrassingly BAD!

Where do I begin? ...some of the conversions... I don't even know if there are style sheet corrections for many of these problems!

1) Fonts (family, sizes, attributes) are all incorrect!
2) In some places (see attached capture), the letter spacing is a mess (fixable through CSS).
3) Images are either strangely truncated and/or sized incorrectly.
4) Tables are a mess.
5) Div box/captions surrounding images are non-existent, actually none of the div boxes translated to Word.
6) Worst problem - text bubbles (made in MadCap Capture) are a mess! Why? I expected this to work! (see attached capture).

I feel so validated.

I have given up trying to produce a clean Word output directly from Flare, but I do seem to have moderately good results when I export from Acrobat to Word. I do my very best to discourage people from asking for Word versions, but every so often I take another stab at getting my Word targets to produce usable copy. Like when there isn't enough stress in my life and I miss the feeling.

ToddPh wrote:I feel so validated.

I have given up trying to produce a clean Word output directly from Flare, but I do seem to have moderately good results when I export from Acrobat to Word. I do my very best to discourage people from asking for Word versions, but every so often I take another stab at getting my Word targets to produce usable copy. Like when there isn't enough stress in my life and I miss the feeling.

Hmm, so it's not just me.

This is rather annoying because MadCap claim that their strong suite is their amazing selection of document output formats. ePub (especially mobi) fails and Word is the worst! Seriously? I do not recall any such problems when I was writing in FM! Sorry, but it must be said! Flare needs to do better! It is especially egregious IMHO that anything involving MadCap Capture and text bubbles is a crazy mess!

But I take solace in the fact that both PDF and Web output work quite well and they are really the only two formats I care about, at this time.

Agreed. Quite happy overall with my transition to flare, but the Word output is a complete trainwreck.

If the Word output was better, PR for Flare with Management would be SO much easier. They do love their Microsoft Office.

I ran some tests uploading PDFs with both Convert uploaded files to Google format and Convert text from uploaded PDF and image files settings selected. Some pages, especially tables, convert to images, and in general it's not pretty. However, it is a Google Doc and all the features are available, including Comments. It sounds like you have a usable PDF output, correct? You may want to give it a try and save yourself the step of going from PDF to Word.

kwag_myers wrote:I ran some tests uploading PDFs with both Convert uploaded files to Google format and Convert text from uploaded PDF and image files settings selected. Some pages, especially tables, convert to images, and in general it's not pretty. However, it is a Google Doc and all the features are available, including Comments. It sounds like you have a usable PDF output, correct? You may want to give it a try and save yourself the step of going from PDF to Word.

Brilliant thought but I hate to cut you down....

For some inexplicable reason, Google docs will not allow this for docs larger than 10MB. "Sorry, this file is too big. We can only convert files up to 10 MB in size."

But then... what about using Acrobat to convert the PDF to Word. Surely, it will do a better job than Flare? (YES, OH YES!! SUCK IT MADCAP! ) Next, upload the newly converted Word doc to Google Docs (conversion turned on)...
NO! Google Docs conversion absolutely butchers the document. Images cut or misplaced, table text scattered and mostly outside of the tables, text with spaces between each letter. It's bad!

Final thought
When I have some more time, I will try splitting a PDF into parts (each, less than 10MB) and upload (with conversion) to Google docs.

UPDATE

I went into my User Guide and turned off a few chapters from the TOC, republished a < 10MB PDF, uploaded it to Google Docs.

Unfortunately, PDF to Google Docs conversion is not a solution.

It fails because:
- Each page is doubled as a screen capture of what the page should look like, and a very poorly converted text version of the page. In other words, it is as messy as the Word conversion.
- It only seems to convert the first 20 pages or so. The rest is truncated without an error message.

Leeds me to the question, if a significantly smaller company like Crocodoc can manage to perfect PDF to HTML5 conversion, why can't the billion dollar Google get even close to a decent conversion? Seriously, try Crocodoc, its conversion is near perfect. They do not allow direct editing but it is the annotation and markups ability that makes it so valuable to me. Why do I want to leave it? Because its parent company, Box has made it end of life and it could disappear any time. Additionally, there is zero security! All documents may be accessed by anyone in the public.

Thanks everyone.

Another voice to those who think the Flare Word outputs are so spectacularly bad that they must be a joke. Like Todd, I try occasionally when I really can't find anything better to do. And like Todd, I dissuade folks from asking for them.

The only thing I can think of doing is creating special seriously-dumbed down stylesheets for the Word outputs (no auto-numbers, no lists, no anything). But why should I?

And no matter how many times I warn people that the Word output is broken and please ignore the formatting issues (especially the auto numbers) they insist on "fixing" the problems when they return their review copies. I'm beginning to adopt a Southern accent while I say 'Bless their hearts" and ignore their fixes. Sigh.

I did succeed in getting one reviewer/contributor to use Contribute. What a difference that makes!

ToddPh wrote:And no matter how many times I warn people that the Word output is broken and please ignore the formatting issues (especially the auto numbers) they insist on "fixing" the problems when they return their review copies. I'm beginning to adopt a Southern accent while I say 'Bless their hearts" and ignore their fixes. Sigh.

I did succeed in getting one reviewer/contributor to use Contribute. What a difference that makes!

Hi Todd, fortunately, I don't require Word output. But if you read my previous experiment, I did discover that Flare > PDF > Word (via Acrobat Save AS) works quite well. I think it was almost perfect. If you own Acrobat (or perhaps an equivalent clone), you could probably script and automate the conversion.

I really, really hope that MadCap focuses on a more portable and OS agnostic Flare contribution tool. Contribute is only useful if you are always working with the same SMEs and everyone is using Windows. How many of you actually fall into that scope? I cannot make use of Contribute.

Yep, that was my experience as well with Acrobat. That is how I handle my Word review copies, after much complaining and muttering things like "Pay no attention to the man behind the curtain". It does come out looking pretty good. I think the only problem I find in the resulting copy is unusual hyphenation (actually breaking the word rather than keeping a true hyphenation). It's almost as if Word has inserted a space between the hyphen and the following word chunk. I haven't found a lot of consistency yet, I just add it to my list of irritations in Word.

That is a spectacular fail. I avoid creating Word documents from Flare like the plague. Wish I had some advice for you.