Flare output access on Confluence wiki?

[Diana_BB]

Hi, everyone,
The new company I work for has purchased Confluence and wants to make the documentation available to customers through the new company wiki that we'll be launching soon.

Of course, the developers working on this think it's really cool that Confluence can take a Word doc and suck it up into the site. *cringe*

I do not want to do anything with Word if I can help it. (One of my conditions for coming over to this amazing new company was that I got to choose my authoring tool--so I'm migrating everything from Word to Flare!)

I assume that I can use WebHelp to deliver the documentation--customers can click the link to launch the WH in their browser. I say this and think it makes perfect sense, but I get the Dora stare (you know, big eyes, blink, blink).

My question (read "plea for help"):
Is anyone else using Confluence to distribute their Flare-produced documents? If so, how are you doing it?

Thanks!
Diana

[helen]

I'm not - but I really want to! I am waiting to hear if my company will be purchasing Confluence (I wrote a proposal) as I want to use it as a documentation delivery platform both internally and externally as you do (as well as all the other benefits). Sorry that's not much help to you right now but I would be really interested to hear how you get on (by PM if you prefer).

[RamonS]

I am sure a link will always work, but that means that the help lives outside of the wiki and cannot be maintained through the wiki frontend (which may just be a good thing). So if the expectation is to manage and manipulate content in the help through the wiki you most likely have to generate a Word doc from Flare and have the devs suck it up.

[Diana_BB]

Ugh. I'd much rather manage the content through Flare and let it live outside the wiki. Using Confluence the way it's designed seems to put a damper on my using Flare for everything. The developer putting this together was worried that Flare would cause problems because "Confluence is an authoring tool." It may allow for authoring but it isn't a help authoring tool.

I know I will have to manage other content written by our developers and support team--I'll decide what gets moved into the product docs, what stays private to employees, and what is made available as tech notes.

I'd like to be able to publish the WebHelp directly to the server from Flare and let people access it through the link to it. I've been reading the Confluence site about this--it sounds like I need to really brush up my Web skills. I'll start playing with Confluence soon.

I'd love any advice about this still. In the meantime, I'll see if I can figure it out. I'll be happy to share my Flare-to-Confluence journey when I do.

Thanks!
Diana

[KevinDAmery]

My gut feeling is that combining Confluence and Flare is going to be... ahhh.... problematic. The idea behind a Wiki is that everyone authors content, and the idea behind Flare is that a technical writer owns the content.

<unhelpful political rant> To me, Wiki's are great as Wikis. They aren't help systems. I hate hearing about people trying to make a Wiki be the only and ultimate source of truth. </unhelpful political rant>

[Diana_BB]

Kevin,
I completely agree with you. My challenge now is to figure out a way to make it work. The decision was made before I joined the company, so I didn't get to plead my case. *sigh*

I will own the content--at least a majority of it. My CTO expects that I'll have to do about 15% of content management on the wiki--editing and releasing (or not) stuff the others write. I'm going to be stubborn about using Flare to do my authoring and help development.

Let me know if you think of anything clever I can do.

Diana

[RamonS]

Ranting a bit more....how come that the tech doc department does not make decisions on how manage and present documentation? Developers should stay at writing code and finally do the unit testing. Leave the wikis to the tech writers.

I don't see the big problem with linking to help created in Flare. What is more annoying is to deal with the dubious 15%. My understanding is that a wiki is unmanaged as much as possible. So any maintenance of content would be more like 1% if that and cover only unethical edits (flames, swears, links to sites that are clearly not work related). There is also not much point in having one person edit the content if 50 other persons can undo that work within a minute. Why do we tech writers always end up in messes like this?

[KevinDAmery]

Well, y'know, developers are geeks and geeks have a real weakness for wikiphilia. And once someone gets wikiphilia they are lost to the rest of us: forget about those other cults like the moonies and Jim Jones and American Idol, this one is serious. From this moment on a wiki is the solution to every problem, whether it's "how do we keep the roof from leaking" or "so what do you want for lunch?"

Tech writer's get stuck with these problems because we're more in tune with reality, which makes us incompatible with the others.

</sarcasm>

[helen]

Do you actually want to use Confluence as a platform to deliver webhelp (keeping the wiki side of things separate or controlled by permissions) - or actually maintain the documentation, or that 15% of the document (which seems bizzare)? I'm not too clear on how you intend to use it.

[Diana_BB]

Gosh, no. I don't have a choice in the matter though. I had visions of a traditional Web site with a link to the documentation, which would at some point in the near future use MadCap Feedback. ( One of these days I'll get there!!)

Instead, I'm tasked with delivering the documentation through a Confluence wiki (in whatever form I see fit--ha), where our dev team will supply information for internal use until I decide what to do with it (put it in the docs, release it as a tech note, or keep it for internal use)--that's the "15%" my CTO estimates for my time. That information will probably be more "fluid" than the docs I write. I hope it doesn't become a maintenance nightmare. I'll have to set up rules and possibly templates. *sigh*

I do not want to use Confluence as my authoring tool. Based on my limited knowledge of how it all works at this point, my plan is to use it only as a portal to the docs so no one else can contribute to it or make edits to it (*cringe*). I'll give them PDFs to download and WebHelp to search.

There hasn't been a technical writer here for half a year--I'm taking over a huge backlog and everyone is excited that I'm here now. We'll see how long that lasts! LOL. It'll be fun to see what they think when they realize how demanding and tyrannical I can be about my job.

This thread has been really helpful to me! Thanks for letting me vent and brainstorm with you. If you have any other comments, suggestions, questions, please share them with me.

Diana

[helen]

That's not so bad then - that's how I want to use it, as a portal and a webhelp platform. Downloads will be in PDF, no edits will be possible. The actual wiki side of things is just for internal use here. I can't see how or why they'd make you use Confluence as your authoring package, as you say - that's just daft! Good luck, Confluence really isn't that bad once you start getting to grips with it - Atlassian are also very responsive in their support in my experience.

[NorthEast]

Have you considered whether you could use Flare (for you) and X-Edit (for your developers)?

Just reading this, it sounds like your workflow is pretty much what X-Edit Contribute is intended for. Your developers could write bits of content in X-Edit Contribute (using your template), and then you manage everything in Flare.

To me, a wiki makes more sense when the readers of the wiki are also the contributors. From what it sounds though, your end-users don't need to edit the content, and you're just using the wiki internally to write the documentation. If this is the case, it doesn't make quite as much sense to use a wiki if you have more practical and suitable authoring tools like Flare available. Of course, there's the issue of cost too, buying a load of X-Edit licences may not be ideal, especially if you've just spent your budget on a wiki tool.

[livetoski]

So whatever happened? It is 3 years and some later. We have Confluence (recently acquired for engineering communication purposes) and MadCap Flare. I love Flare as a tech writing tool, we produce online help and some pdfs. I completely appreciate the power and features of Flare.

The reason I would like to move some of our documentation to Confluence is that the writers and major contributors are technical people and it makes more sense. We can't round trip at all through Flare (Contributor just doesn't cut it) and it's too cumbersome to get things quickly to users, some of whom would like to be contributors. I'd like my cake and be able to eat it too, I want a lovely tool for documentation creation and I want to selectively open it up to contributors to edit.

I'd like to use the same style sheets, if I can (this may just have demonstrated my ignorance) and I'd love an import feature or an import path. I am currently reading Confluence Tech Comm and Chocolate, and I don't see Flare listed as an import format which is giving me pause. My files are all html and my expectation is that if I have a style sheet, I should be able to import html, no? (again, demonstrating ignorance...)

Linda

[Diana_BB]

Linda,
I ended up returning to my other job shortly after that post--startups... So it hasn't been a critical issue for me to pursue.

I agree with you about finding a way to use Confluence as a source. I haven't had much time to look into it. We should both make product enhancement requests--the more requests, the higher on the list it goes (if it's possible).

Diana

[livetoski]

Thank you Diana! What tool are you using now?

[Diana_BB]

Flare 8, of course! (I can't imagine work without it.)

I've just gotten Contributor for my developers, but only a few have started to use it. I'm easing them into it. We use Confluence for internal information, so it would be nice to leverage it.

Diana

[livetoski]

Yes, I use Flare 8 as well and love it. However, I love the idea of a one stop location for all documentation, and being able to connect more contributors to the source documentation, such as the Sales Engineers, Technical support, product management and some marketing.

I'd love to hear more of your process of leveraging, if you go that route. I will post here what I find, or you can email me at struergrl (at) gmail (dot) com to continue the conversation.

Did you read Confluence, Tech Comm, Chocolate?
Linda

[BeckyDoyle]

This thread was extremely entertaining, and I HOPED I was going to get an answer to my issues, which are similar, but alas I did not...

Does anyone have a solution for this?

My dilemma:
- our engineers write their input in Confluence
- we (the Tech Pubs team) work in Flare
- we need the engineers to review our information, and getting the info to them in the most simple/manageable format is key
- we will be creating wiki help pages, AFTER the previous three steps are complete

We're thinking of trying to upload our Flare-created PDF into html pages within Confluence, but I can't find a macro within Confluence that will allow me to insert HTML code. It can convert an already published page, but none of our stuff is on a page (internal OR external) yet. It's all living in Flare and the final PDF we generated.

Short of copying/pasting the info back and forth, I don't know what to do. Any help/suggestions would be much appreciated.

-Becky

[Diana_BB]

Hi, Becky,
I feel your pain. My developers are putting more and more information on our wiki, but I haven't had the time to dig in to research how to pull in their information. I'm using MadCap Contributor to help with some of that. It has saved me a lot of time with reviews.

With a very brief lull between releases right now, this is one thing on my list to play with.

You should be able to create your own wiki pages and upload the PDFs as attachments. If you don't already have rights to the wiki, get them. I have a my own area where I can post all things Tech Doc that I want my developers to look at.

Please post anything you learn. I'll do the same.

Good luck!
Diana

[lauraj]

I also have a similar, but different, problem to solve. (Well, maybe. I am toying with the idea, haven't pitched it to management yet.)

I have some internal documentation that I authored in Flare and published as WebHelp, but I am now fully consumed on higher-priority (customer-facing) documentation and can't maintain the internal stuff. So now, devs are writing white papers and putting them in SharePoint and hoping the users find them. I am finally facing the fact that we won't have enough writers to own this doc ever, so I would like to move it into a Confluence wiki. At least then the devs could edit in in place. I realize it will be a chunk of work to move it over, but I don't know the best path.

Will Confluence "suck in" published WebHelp pages? If so, I can do that, and I think that maybe Becky could too, by creating a target to spit out WebHelp and publishing it temporarily to someplace that Confluence could find it. Anyone know whether that will work?

(Of course, this thread is a month old, so Becky might've found a solution already. What did you do, Becky?)

[karthikg]

Hello all,

I'd love to know the answer to this, which is very similar to what previous posts allude to, i.e. managing content across Confluence and Flare-generated outputs.

We have a similar situation at our company, where we've been reliably producing WebHelp from Flare for our in-application help. We now want to make this a reality on the Web, where we've now committed to Confluence for a public wiki (actually, internal wiki as well). We have JIRA/Salesforce deployed and will likely move towards integrating support for cases, answers, and JIRA/Salesforce-driven support which integrates pretty niftily with Confluence. OK, so now where will our Flare output fit in?

We'd ideally like to export a HTML5 output from Flare that gets used up by Confluence somehow, in such a way that it can add its native posting/forum feature to it (perhaps some code within all the Flare XML topics?). This way, there's a layer that resides at the Confluence side to provide feedback/posting/wiki functionality without actually altering the XML topics outputted from Flare. We can then replace the output umpteen times from Flare without overwriting any of the Confluence-driven conversation.

Any thoughts? or ideas for improvement to this approach?

Thanks!

[lauraj]

In my investigations, I've seen mention of a macro that allows the embedding of HTML code into a Confluence page. I haven't tried using it, because that's not really what I want -- I want a one-way trip into real, editable Confluence markup. But you might investigate this macro -- it could be what you need.

Strange as it may sound, the best trial I've had so far for my one-way trip is to add a Microsoft Word target to my Flare project, generate a huge Word file, hand-edit it to use the heading styles that Confluence recognizes (standard Word "Heading 1", "Heading 2", etc.), and import it into Confluence (during which import I can choose to start a new Confluence page at each Heading 1). Most of the formatting survives (with odd exceptions), and hyperlinks survive, but cross-references don't -- I either need to figure out why that is, or replace all my xrefs with hrefs before generating the Word file.

[BeckyDoyle]

What we have decided to do it to move forward with utilizing Flare Contributor. The main reason we're moving away from Confluence is that when engineering updates information there, it makes the process of updating our existing documentation much more arduous. This is primarily because we often end up having to re-write anything/everything written by our engineers. Then re-structure it to fit our template for our documentation. So when they add more information to existing Confluence wikis or create new ones, it basically requires us to start from the beginning all over again.

Needless to say, this can be very frustrating. There are 4 Tech Writers here and we already have more than enough work as it is.

We are hoping that by adopting Contributor in this format, the engineers can make changes to specific sections, where the updates need to happen, and we can still control how it is written, etc as we review accept/reject their changes.

We will still be using Confluence but in a manner of developing as-of-yet unpublished/written topics.

Now to learn about how to make Contributor work with our single sourcing software of choice, GitHub!

[rlauriston]

The loss of cross-references when importing Word is a long-known bug:

https://jira.atlassian.com/browse/OFFCONN-54

They also don't convert autonumbered paragraphs to ordered lists:

https://jira.atlassian.com/browse/OFFCONN-56

And content is reordered, with each TOC node being sorted alphabetically:

https://jira.atlassian.com/browse/OFFCONN-53

Vote for those issues and maybe Atlassian will fix them someday. Or maybe MadCap will see the business opportunity and sell a two-way Confluence connector for Flare.

[sdcinvan]

Wow oh WOW....not very articulate but that how I feel after reading this FIVE year old thread.

It began with Diana asking if there was a way to somehow integrate Flare with Confluence on January 2009. By the time I reached the last message, posted today I was very disappointed that there were only questions and no solutions! I'm going to send a ticket into MadCap with a URL to this thread. They need to help us figure out a solution.

I'm in the same situation!

For a year, I perfected my Flare skills and ignored that lingering issue that with Flare, documentation input is essentially ONE-WAY! This means that I can't offer any practical method for SMEs to review/collaborate on content, with full text edit capability. The only MadCap option is Contribute but unfortunately:
a) It is highly intrusive to force a one-time reviewer to install this Windows application.
b) More importantly, most of my SMEs don't run on a Windows platform.
c) It isn't very collaborative anyway.

What I need (or rather, what I believe most of us need)...
- Real-time centralized and OS agnostic collaboration tool (meaning, it must be web based).
- Allows round trip collaboration (From Flare to collaborative tool and back to Flare)
- Output a list out changes made (or round-trip method - see above) - either way, I think most or all of us would be happy.
- Full text editing (including image insertions).
- A commenting side-bar (for comments only).
- An accept/reject/reply to suggested changes mechanism.
- Record the name of the editor.
- Keep a record of content revisions.
- Allows for easy sync of new content. For example... one button to sync Flare content with collaborative tool.
- Relatively secure... some of us are working on sensitive/private content.
- Renders the collaborative content, at least, nearly as good as Flare's XML editor.

About the last point, that is a best wish sort of point. I would be very pleased just to have Flare output sync content to either:
a) A wiki-based tool like Confluence. Obviously Confluence's rendering ability is significantly lower fidelity but with a decent parser, a synced Confluence version would still be presentable and editable by SMEs.
b) Google Docs. I much prefer Google docs because of its accessibility (i.e. I don't need to log into our VPN to access Google Docs).

Some hope from me?

Having some form of tool that will allow my SMEs to fully edit the documentation I produce is so important that if I do not find a solution very soon, I will be forced to drop MadCap Flare and build all my documentation in Confluence. I really don't want to lose the powerful features of Flare but it is going to happen, if I cannot present a solution in the next month.

To that end, I have contacted Atlassian about developer APIs (https://docs.atlassian.com/confluence/REST/latest/), etc... and I am also looking at Google's developer page: https://developers.google.com/google-ap ... ents-list/


Love to hear from anyone else who is interested in something similar to what I described. What are your pain points and have I missed any issues that bug you about collaboration in Flare?

Thanks,
Shawn