Collaboration (without MadCap Contribute) revisited.

[sdcinvan]

Hello all,

Allow me to revisit this issue. Sorry.

I am wondering how many other Flare writers need a way to collaborate but cannot use MadCap Contribute (mainly b/c of our non-Windows environment)? Am I alone?

Anyhow, I had mentioned earlier that I was using Crocodoc as my temporary solution. Now, management is pushing me hard to find a way to bridge Google docs (our primary company-wide tool set) with MadCap Flare. The reason is to provide the Engineers with a way to review and edit documents on a OS agnostic (and commonly used) platform.

I must find a solution, even if it is one-way (meaning Flare to Google Doc - but changes manually back into Flare). Ideally bi-directional collaboration is preferred.

Anyone have any ideas? Or am I on my own?

[sdcinvan]

This is what I have tried, thus far:
Flare to PDF -> Google docs converted to gdocs
> severe limitations: PDF to gdocs conversion is limited to the first 10 pages (or 2MB) - Enterprise tool - yeah, right!
> The results (on what is converted) are mildly acceptable - Google's conversion provides an image based rendering of the actual page, following by a poorly formatted text version of the page.

But the conversion is very challenging and may be impossible to script (automate)... I must do the following:

Code: Select all

1. Open PDF in Acrobat 
2. Select Pages > Split Document
   > Select Split by File Size = 2MB (max)
     Error may occur - "An incorrect structure was found in the PDF file"
     > Then I must go to View > Show/Hide > Navigation Panels > Tags
     > Right click and remove some of the possibly 100's of bad tags
     > Save As new PDF
3. Repeat Split Document
4. Upload document parts (about 10 parts!)
   > Unfortunately, there doesn't seem to be a way to automatically convert each part to a Google Doc
5. Manually convert each part by selecting Open With... Google Docs
   >Wait....
6. Discover that the conversion STILL only converted part of each of the 10 segments!  :x  :x  :x  :x 

Currently, I am unsure how small the segments must be in order for a successful (full) conversion from PDF to Google Docs.

What else have I tried?

Flare to Word
> Forget it! Flare is completely inept with that sort of conversion.

Flare to PDF and then PDF to Word (docx) -> Google docs converted to gdocs
> Unfortunately, the end result is terrible/nearly unreadable.
> Waste of time to pursue any further.

Flare to HTML -> Google docs converted to gdocs
> Formatting is mostly a mess and no images are uploaded.

So far, the most acceptable conversion is the PDF to Google Docs method. But I am currently being challenged by a number of pages converted limitation. I have no idea how to solve this problem.

[sdcinvan]

If I cannot find a collaboration solution soon, I may be pressured into dropping MadCap Flare, in favor of something like Atlassian's Confluence. We also use Jira... so collaboration with Confluence is a natural extension.

I cannot express how frustrating this issue is for me right now. The problems are a mix of Flare's lack of OS agnostic collaboration and Google Doc's inept document conversion. I just can't catch a break!

[jjw]

I have been publishing a draft version of my documentation that incorporates 'Easy Page Comments' in the master page:

http://pomax.nihongoresources.com/pages ... eComments/

It's fairly kludgy - especially as I am not a developer and I had to muck around with the php script to make it do what I needed (which mostly involved disabling features that I didn't want). But it allows people to make comments (and reply to comments) on any page. The comments are stored in a sqlite database (one for each page) so they can be persisted. I get an email when anyone adds a comment with the comment text and a link to the page. I serve the pages from my laptop using XAMPP. I'm sure the whole tottering structure will fall over eventually.

I'd like to be using Annotator (http://annotatorjs.org) which several online course providers use for interactive exercises (see, for example, the poetry annotation exercises in "Poetry in America" on EdX - free to sign up). But there isn't any simple way for me to persist the annotations on a private site (with my limited skills). You can sign up to AnnotateIt and store annotations there, but that wouldn't work for us. If you have technical support to manage your own onsite storage of annotations, this would be a nice tool.

[sdcinvan]

Thanks for these... I will certainly check them out.

After nearly a week of research, I have 'matured' my thoughts on collaborating options.

First, my biggest pain is a result of basically building the draft of my documents in Flare and then doing daily builds with updates for reviewers in PDF... and no convenient way to review, edit and/or comment.
The obvious solution is that I must enforce my original workflow that requires that draft work stays in Google docs until completion and sign-off. Only then is Flare brought into the workflow to build the 'pretty' docs.

After this point, PDF reviewing becomes slightly less painful because reviewers are essentially reviewing a completed product with far fewer iterations.

So how do initiate PDF based reviews?

I am experimenting with the Acrobat Share collaborative feature, which works with a WebDAV server. So far, the results are rather encouraging. Once I lock down a successful workflow, I will be happy to share this workflow with this group.

Best regards,
Shawn

[sdcinvan]

FYI, taking with MadCap support... thought I would share my latest email. What are your thoughts?

Thanks for your reply.

>Currently, the ability to output directly to Google Docs from Flare is an enhancement request. A feature request has been submitted on your behalf to our Product Managers
>who work with our Research and Development team regarding future versions of our products.

Thanks but after a lot of research, I doubt this will ever happen because.... Google!

I think a two more likely enhancement requests would be:
1) Atlassian Confluence import/export... after all the XHTML source is already similar and the Atlassian people would likely be happy to assist with such a project.
2) The ability to import Adobe PDF collaboration/review comments... these are saved as xml files (per user). It would be awesome if Flare could connect to a WebDAV server (or shared folder) and read in these XML files.

Or... just help us by offering an OS agnostic collaborative solution.

Thank you,
Shawn

[ToddPh]

I think I'll head over to the feature request and ask for Atlassian collaboration myself, as that would be fantastic in our world too. I am not surprised by their response regarding Google. Ever since our company moved to Google apps I have been grousing about how they tend to make updates and "fixes" without warning so we can't really rely on things like Google Chat for our meetings to actually work. Imagine how maddening that would be for MadCap devs, and how expensive for their support.

I do think it should be very possible to develop a two-way bridge between Flare and Confluence, however. Both tools already have import capabilities, and both are based in XHTML. It would allow for all of the features you're looking for, and I think for what my own company is looking for. I'd really hate to give up on Flare because I think it is a superior tool, but the need to collaborate through a browser is becoming tantamount to the new way of working (platform agnostic, distributed teams, etc.).

[sdcinvan]

I think I'll head over to the feature request and ask for Atlassian collaboration myself, as that would be fantastic in our world too. I am not surprised by their response regarding Google. Ever since our company moved to Google apps I have been grousing about how they tend to make updates and "fixes" without warning so we can't really rely on things like Google Chat for our meetings to actually work. Imagine how maddening that would be for MadCap devs, and how expensive for their support.

I do think it should be very possible to develop a two-way bridge between Flare and Confluence, however. Both tools already have import capabilities, and both are based in XHTML. It would allow for all of the features you're looking for, and I think for what my own company is looking for. I'd really hate to give up on Flare because I think it is a superior tool, but the need to collaborate through a browser is becoming tantamount to the new way of working (platform agnostic, distributed teams, etc.).

Hello Todd, I am sorry to say that I am still focusing on a Google Docs solution so not much with Confluence yet (except for a few email exchanges).

But you are absolutely correct about Google... even if I were able to find a programmatic solution to bridge Google Docs with Flare, I am at the random mercy of Google. They change their stuff frequently, without warning, and sometimes for no apparent reason. So whatever solution I come up with, may very well be temporary. But at the same time, its ubiquitous use in our company still makes it a hard to resist target.

Allow me to share a bit of knowledge I picked up from my Atlassian conversations (they are pretty awesome people!)...
Their API is found here: https://docs.atlassian.com/confluence/REST/latest/

Some Confluence add-ons to test:
https://marketplace.atlassian.com/plugi ... de-replace

Sorry, that is all there is (AFAIK) for importing some Flare published format into Confluence. Given that, this is going to be a DIY project.

Oh wait, Confluence has a built-in Word import filter. Problem is, who among us is actually successfully using Flare's Word Target? IMHO, it is embarrassingly bad!

Jira Integration (important to me):
http://blogs.atlassian.com/2013/12/conf ... er-before/
http://blogs.atlassian.com/2013/12/5-wa ... onfluence/

Some Confluence instructions:
https://confluence.atlassian.com/displa ... the+Editor
https://confluence.atlassian.com/displa ... blog+posts
https://marketplace.atlassian.com/plugi ... geapproval
https://marketplace.atlassian.com/plugi ... h.workflow
https://confluence.atlassian.com/displa ... ison+Views
https://confluence.atlassian.com/displa ... Confluence
https://confluence.atlassian.com/displa ... uence+Wiki

I'll be happy to share everything I learn over the next few weeks. If I can't work out a reasonable/workable solution, I may have to shut down MadCap Flare. It is soooo friggn frustrating that I can't glean any insight from MadCap. I understand that I am just one person but it would have been nice to know that someone at MadCap cared about my plight.

[sdcinvan]

I did a bit more digging last night...

https://confluence.atlassian.com/displa ... Confluence (a perpetual thread on Importing into Confluence)

Other interesting links:
https://confluence.atlassian.com/displa ... Confluence
https://confluence.atlassian.com/displa ... er%20Guide
https://confluence.atlassian.com/displa ... Confluence

I'm going to test Jason Huntley's h2c tool over the weekend: http://forums.atlassian.com/message.jsp ... =257373654
Project page: http://sourceforge.net/projects/h2c/

Some interesting add-ons for Confluence: https://www.k15t.com/

[dorcutt]

Flare to Word
> Forget it! Flare is completely inept with that sort of conversion.

Hey scd,

I actually have been having good success with my Word output lately. I just checked, and I converted a document to a solid-looking Google Docs file with a minimum of fuss, so with some setup (less than you might think!), it is possible.

The first client I used Flare for, at the end of the project, said "Oh and drop the word files in this folder also, because the contract says we own them." After cleaning my pants, I got down to work, and after about a week of figuring stuff out, tweaking content, and writing some Word macros, i was able to give them about 700 pages of respectably clean Word output with a minimum of embarassment and manual cleanup.

Now, I have it set up so that I can generate any of my docs into a fairly solid looking Word output at any moment with a bare minimum of ongoing maintenance, and I've been using that for internal collaboration successfully.

My main issues with the word output is that occasionally the bullet list spacing gets a bit funky for really complicated bullet lists, and I haven't taken the time to set up my styles so that the autonumbers are actually working field codes and that multilevel lists are set up correctly, but I think i can do that if I needed to. Additionally, I've found that even in master pages, the [Level 2] and [Level 3] variables do not work in the Word output headers/footers (this seems to be a bug because [level 1] works fine, so my headers are slightly less advanced, but all of this is perfectly acceptable for internal reviews.

I am planning on doing a full "Tips and Tricks" post about this at some point, but for now, here is a quick brain dump about what I've learned about Word output to get you going:

1. Set up the TOC so that both section breaks and chapter/page layout breaks are used. Because Section breaks are only used by Framemaker and Word and ignored by all other outputs, I can generate word output from the same table of contents as my PDF output without any modifications whatsoever.
2. Create a word-friendly version of page layouts using either master pages or page layouts with only one body frame and no rotated frames. Using all master pages is easier, and they are actually super-simple.
3. Create a Word output condition so that a few things that do not play well with Word can be conditioned out (I've used this with MiniTocs that reference files with variables in their heading titles, for instance)
4. Create either a Word CSS medium, or what I did, create a new Word Styles.css stylesheet that just imports the main stylesheet. Because the declarations have precedent, I can overwrite only the needed aspects of Word without having a separate stylesheet to maintain for every change. Also, since it is a separate stylesheet, I can never accidentally screw up my main stylesheet on the behalf of word output (mediums can get confusing fast).

The Power of Word Macros
Finally, here is the kicker, create a Word macro to fix all the dumb after the output is created. I have some (limited) knowledge of VBA and the Word document model, so I was able to "get it in post" mostly. You can record macros in Word to get most of the code that you need, and the MSDN references for Word are truly excellent. I've provided some basic structures that you can modify for your needs below.

The two main "tricks" that I use is a find and replace (my cross reference spacing comes out just awful in Word output), and most crucially, I can loop through each style that is created and modify it as needed to make the output match that of the PDF.

Using this macro, I'm actually able to use AutoNumber formatting for word. In my PDF output, I use notes with the bold word "Note:" in them. In Word, this comes out as "N: {b}Note{/b}:". However, this means they are clearly and distinctly tagged, so I can use search and replace as follows:

Code: Select all

objDoc.Range.Select
    Selection.Find.ClearFormatting
    Selection.Find.Replacement.ClearFormatting
    Selection.Find.Replacement.Font.Bold = True
    
    With Selection.Find
        .Text = "N: {b}Note{/b}:"
        .Replacement.Text = "Note:"
        .Forward = True
        .Wrap = wdFindContinue
        .Format = True
        .MatchCase = False
        .MatchWholeWord = False
        .MatchWildcards = False
        .MatchSoundsLike = False
        .MatchAllWordForms = False
    End With
    Selection.Find.Execute Replace:=wdReplaceAll

After the macro is run, this makes it so that it is just as if Word actually did support autonumber formatting! A similar technique can be used to automate any search-and-replace that you need to do to clean up your word output.

The other main "trick" is that you can loop through the styles that are created by word, rename them, add them to the Quick Style Gallery, select all of one style, format it as another style and then delete it (I'm looking at you p.Note_1, P.Note_2, etc.!). This is the real magic and what makes my Word output doable.

First, I use this code to clear out the Quick Style Gallery:

Code: Select all

  For Each styl In objDoc.Styles
     If styl.Type = wdStyleTypeCharacter Or _
        styl.Type = wdStyleTypeParagraph Or _
        styl.Type = wdStyleTypeLinked Then
        styl.QuickStyle = False
     End If
  Next styl

Next, I use code like this to add my own styles to the gallery, rename them appropriately, and make necessary changes to de-stupidfy the output:

Code: Select all

'cycle through each style and make necessary changes
  For Each sty In objDoc.Styles
    
     'Fix indenting and add core note styles to QSG
     If sty.NameLocal = "p_note" Then
     
      sty.NameLocal = "Note"
      With sty.ParagraphFormat
       .LeftIndent = InchesToPoints(0.52)
      End With
      sty.QuickStyle = True
     
    End If

   If sty.NameLocal = "p_note2" Then
      sty.NameLocal = "Note2"
      sty.ParagraphFormat.LeftIndent = InchesToPoints(0.67)
      sty.QuickStyle = True
     End If
   
   'other styles, etc. etc.

Next sty

Oh, I also have code to loop through every image and add a border to it, if you need it. It must be the last code run due to the way I've crudely jury-rigged it (and I currently have to manually format the last image).

The full macro that I run is located here: http://pastebin.com/ZAB6kqzM. Clearly, it's set up to be specific for my individual needs and is not optimal coding in many places (I am not a programmer and I was just throwing something together that works for my own reference), but it should give you an idea of what I'm talking about and what is possible.

PS: Two last tricky items. Word output often generates this horrible red error saying there's a problem with the document and that it is opening the document in protected mode. That big, scary error is just because the doc isn't quite named properly! See this thread here for details: http://forums.madcapsoftware.com/viewto ... 10&t=16132. Also, Word doesn't normally save images inside the document with flare. The best way of fixing this that I've found is manually doing this process once the document is created:

1. Select the entire document (Ctrl + A).
2. Click File > Info.
3. Expand the Properties on the far right side of the Info page.
4. Click "Edit links to files".
5. Click "Save picture in document".

You can also tic the "embed images in output" option on the Word Target's advanced tab, but this is significantly slower than the above process. On the other hand, if that is checked, you can't forget and annoy your reviewer with broken images.

Good luck, and I'll keep an eye on this thread to try to provide you with some help if you want to go down this road.

[sdcinvan]

Flare to Word
> Forget it! Flare is completely inept with that sort of conversion.

Hey scd,

I actually have been having good success with my Word output lately. I just checked, and I converted a document to a solid-looking Google Docs file with a minimum of fuss, so with some setup (less than you might think!), it is possible.

Hello and thank you so much for sharing this fantastic instructional for those interested in Word output.

I have observed the issues that you mentioned in your post but unfortunately, I consider those minor inconveniences and I could live with my Word to gdocs formatting, IF those were the only issues.

Allow me to illustrate the real issues that I have encountered...

Starting with the worst...
1) MadCap Capture text bubbles become mangled, only when published as a Word document. Also images are often truncated.

WORD_output_Capture_text_bubbles_mangled.png

[UPDATE: I have since discovered that there is a bug(?) in Flare that causes this mangling. In the Word target under Advanced > Output Options > you must deselect Auto-size Capture objects to fit text]

2) Text (paragraph text primarily) is weirdly spaced and all tables are a mess.

WORD_output_spacing-truncated.png

These problems might be solvable if I spend more time customizing the Word output css Media type.

3) Entire pages of content that are blank. There doesn't seem to be anything particularly different about such pages (about four in a 90 page document).

WORD_output_wholepagesmissing.png

It becomes a little worse (and a little better) after uploading and converting to a Google document...

4) Random odd images (that are no where in the source) replacing some images.

WORD_output_TO_GOOGLE_unknow image.png

I have no idea where this 'arrow' image came from but it really should be a different icon, which is present in the source document.

5) Many page gaps (mostly 2-3 pages per chapter)

On a positive note, the character spacing noted in issue (2) is perfectly normal after importing into gdocs format.

Finally, the last problem is that I need to fully automate this... transferring content into the Google Docs sync will not automatically convert the document. Anyhow, that is an issue only worth dealing with once I figure out getting a working Word document out of Flare.

Thanks again, I am certain your post will help out others.

Best regards,
Shawn

[dorcutt]

Hrm, I don't really have any of these other issues that you mentioned, so I'm afraid I'm not much help there. I have had some semi-related experiences:

• I have noticed a few images that were truncated because they were either too high or too low in the word output, but it was very slightly and mostly just lost a pixel or two, so it was liveable.
• I did notice that bizarre spacing issue, but only when I went from PDF to word. When directly exporting from Flare to Word, the spacing was fine for me.
• I don't have many complicated Capture images, so I hadn't noticed any issues with those either. Maybe I just have gotten lucky.
• Tables seem to be immaculate, but I don't have any complicated table styles.
• I did notice the blank pages in the GoogleDocs version, but not directly in the Word output. Those are very irritating and I'm not really sure why those are happening.

As far as google drive conversion goes, I don't have much experience with getting that fully automated.

Anyway, maybe I've just gotten lucky with these issues so far.If you do decide to give the Word route a shot and want to see what's possible to fix using macros, just let me know.

-Dan

[sdcinvan]

Hrm, I don't really have any of these other issues that you mentioned, so I'm afraid I'm not much help there. I have had some semi-related experiences:

Hi Dan, your post may not help me (at least, not now) but it will very likely help others.

My documentation has a lot of 'complex' stuff like lots of divs, over 100 styles, custom table styles, custom OTF fonts, Text bubble add-ons via Capture, image DPI changes in Capture, etc... I think all of these features combined resulted in a relatively messy Word output.

My next steps...
- Build an HTML5 to gdocs parser
This may not be possible b/c I am getting no cooperation from Google... for writing to gdoc
OR
- Build an HTML5 to Docx parser
Basically simplify all the styles, fonts, tables, etc. to a very basic (emphasis on readability rather than design) format.
OR
- Build a [different published format] to Docx parser
OR
- Build a HTML5 to Confluence parser
I think I will be able to write directly to Confluence's native XHTML format.
OR
Run away and join the circus.

Any insight is welcome.