Monday, September 18, 2017

Drop the Mic

Hawks Win



Of this Earth

Eddie Vedder seems like a cool dude, especially after jamming with some street musicians in Chicago: http://www.nbcchicago.com/news/local/Eddie-Vedder-Joins-Street-Musicians-for-Surprise-Performance-Outside-Wrigley-Field-445364623.html

Madcap Flare v. Confluence

This is a discussion that I found interesting on LinkedIn. I wanted to remember it. I think it's hilarious on one level and sad on another level that there are plenty of people who do not believe Confluence is suitable for end-user documentation.




MADCAP FLARE VS CONFLUENCE

My apologies to members who may have seen this same post in other groups - I just want to make sure I am getting info from as many sources as possible:

Here's my issue...

Having used Flare for some 8 years now, I'm completely biased. I just started a new job, and they are re-evaluating their authoring tool... they've never had a technical writer before - previously they had a BA doing the online help - so they used Doc-to-Help (I have never used it).

So this morning, someone mentioned to my boss that we might consider using Confluence to create our context-sensitive online help. However, I know even less about Confluence than I do about Doc-to-Help... except that I've once in a great while heard it as an option for help, but more often for creating and maintaining a knowledge base.

I'm really looking for input as to the pros and cons of Confluence vs Flare. In a quick google, the items i see that might be big ones are 1) full ability to do context-sensitive, 2) ability to create conditional text, 3) options for creating multiple targets, and 4) slick features such as drop-downs and toggles.

However, my bias may have affected what I have read thus far. Has anyone used both - if so... what benefits can I offer my boss for using Confluence - particularly considering the flexibility and power of Flare (can you tell it's my favorite? lol)

Thanks for any input you can provide.

Craig Wright FISTC

Hi Kelley,

I've used both (and another option that I'll mention shortly). Fear not, Confluence can do a lot of the things that Flare can do BUT it comes at a price - you are going to need plug-ins for things like content reuse and features like that. Also, the cloud version of Confluence was pretty terrible, so I'd avoid that unless it has dramatically improved in the last couple of years. When I used it, you couldn't even get access to the source HTML to fix things like number lists.

On the plus side, Confluence is a CMS, so has features that Flare doesn't like user permissions and it can connect to JIRA. Not sure if Flare 2017 supports that, but previous versions didn't.

You're right about the different outputs not being supported, but I believe there are plug-ins for creating smarter-looking HTML and PDFs.

Craig Wright FISTC

Another issue is that Confluence is usually for more collaborative efforts. That can be great, but if you are trying to produce consistent, well-written content it can get messy - too many cooks spoiling the broth. Especially if some of those cooks are not particularly good writers.

Craig Wright FISTC

So in a straight race, I'd prefer Flare, but I have to admit that I worked more quickly in Confluence. But have you considered other options? Take a look at Paligo - it has content reuse, conditional content, etc. like Flare, plus CMS features like Confluence, and it is structured content too. Pure XML rather than Flare's XHTML, so no proprietary tags - easier to convert to other formats. I've used it recently to output content to HTML5 and Zendesk articles. I like it's HTML5 output as it has an accordion-style side menu which is still not available in Flare.

If you are used to Flare, you will pick up the basics of Paligo really quickly.

Craig Wright FISTC

You can get a demo at http://www.paligo.net.

kelley bennett

Craig Wright FISTC - thanks so much for your input - actually a few people have recommended Paligo... so i'm going to check out your demo link... I, of course, prefer Flare... as I've already gotten thru that learning curve so i could pick up and go a bit quicker... so I need to check pricing, etc... I'm really not liking the Confluence idea for our purposes... but I'm really trying to keep an open mind...

Thanks so much for your time and effort in answering my questions.

Craig Wright FISTC

No problem. The learning curve from Flare to Paligo is much smaller, trust me. Content reuse and the approach to topics is slightly different (if you want it to be), but there's nothing that should phase you too much. I'm not sure about the flashier features like drop-downs - still need to learn that for myself.

kelley bennett

Yes... I am a big fan of the drop downs and togglers! So if we end up doing a live demo I will ask about that... Is it capable of CSH? I assume so.

Thanks again

Liz Fraley

That's like comparing apples to magpies.

Ed Hawco

I agree with Liz Fraley that it's like comparing apples to magpies. I used Confluence for a while a few years ago, and found it limited. I was able to do some decent things with it, but there were always glitches. Annoying things like version control presented challenges, and it seemed like licenses for plugins were always expiring, etc. I managed to make it work for a single user guide, but I would not have wanted to use it for multiple documents.

@Faith Knight: I use Help & Manual as my main tool, and it works very well for me (lone writer managing about 40 doc projects.)

Fariha Rostai

What's 'Help and Manual'? Are you referring to Robohelp or is this a different tool? Any links appreciated. Curious to try out Paligo as well. Very interesting topic.

kelley bennett

just an fyi... folks, I get this isn't a straight comparison challenge (apples to magpies) - but it's what I have to show... I am trying to show why we don't want Confluence and we do want Flare - and the comparison is the only way I can do that... I really appreciate all the input.... and most of it has confirmed what I thought about Confluence for our purposes... it's just simply not on for our needs. THANKS SO MUCH TO EVERYONE!

Robert Lauriston

Confluence Server plus Scroll PDF, HTML, and Versions plugins will do everything you asked for, but Paligo integrates all of that in a single product with a single point of support. After using Confluence for three years and Paligo for one I can't imagine going back to single-user installed Windows software.

kelley bennett

Thanks, Robert Lauriston
We have a demo scheduled with Paligo on Wednesday!

John Brewer

Confluence, despite a lot of hype, is essentially a big wiki. It's good at providing a platform for a whole bunch of people to collaboratively build content. Once you're in Confluence though, you're pretty much locked into a online document with a limited look and feel. People suggest Confluence because it's easy for developers to access and edit content, and that's true. Everything else about it is a negative, especially for writers. It kills look and feel. It's tough to get Confluence content into PDF, and if you do it's very basic. Interactivity requires a bunch of programmers and a lot of hours, etc. Confluence is usually suggested because developers want a chance to write, or because someone is balking at Flare maintenance fees. Are either of those your situation? If so, I may be able to provide more targeted advice?

Robert Lauriston

When I started my job four years ago I chose Confluence Server + Scroll plugins over other alternative single-source authoring tools including Flare because based on my experience at previous jobs it was the best tool for my needs. I got professional-looking PDF output out of the box, and tweaking it to meet our requirements was faster and easier than with Flare. Unlike other wikis (except MindTouch), Confluence topic source is XHTML, and it's extremely similar to Flare's topic source.

John Brewer

Really? All I was able to get out of Confluence was basic "MS Word-style" blocks of text followed by a block of photograph, etc. No wrapping text around images, and highlighting text was kinda wonky. Getting links to transfer to PDF was also hit or miss. Part of my problem was also the Confluence online support. A lot of it was dated, though the user community was pretty passionate and, therefore, helpful. :)

Were you using the hosted version of Confluence or the server-based version? My experience may have been based on the fact that we were using the hosted version, so getting plug-ins working and installed was a real hassle.

Robert Lauriston

As I said, Confluence Server. Confluence Cloud didn't support the necessary plugins. Scroll PDF Exporter is now available for Cloud. HTML Exporter and Versions are not. Since I single-source to PDF and web help, I don't worry about wrapping text around images, that doesn't seem like something that would add any significant value for users.

John Brewer

How do you handle content reuse? A lot of small Confluence pages knitted together by the plugin? Seems like that would make for good revision tracking, which could be cool. Do the plugins handle things like variables and conditional text as well?

Robert Lauriston

Scroll Versions makes some fairly radical changes to the Confluence environment to support conditional text, topic reuse, branching, and so on. If I hadn't switched to Paligo I would probably have added it, but up to that point it had not been a requirement. Paligo handles that stuff very elegantly.
William Bailey
I have been using Confluence for technical documentation for 5 plus years (did a lot of FrameMaker and InDesign before that). I wont go back. The productivity lift is huge, and it functions as the company's intranet.

You can style a Confluence instance with CSS -- pretty straightforward.

With scroll PDF, I can get to 80% of what I could get with FrameMaker. I get pretty professional PDFs. Takes work to get started, but the results are there.

For content reuse, there are three things I use: page include macro, excerpt macro and the multiexcerpt macro. Makes it easy to reuse pages down to paragraphs.

One must: user macros. I created some to generate professional looking figure and table titles (that export to PDF). I have even created macros to handle variant content.

You cant do everything with Confluence that you can do with FrameMaker, for example, but I give that up for all the tools and ease of collaboration.

John Brewer

Sounds like my negative experiences were more linked to the hosted version of Confluence then. With the proper plugins, and some knowledge of macros, Confluence can be an authoring tool for tech docs. In my experience it was great for collaboration but the back-end work was a hassle.

In the spirit of the original question, what negatives have you experienced with Confluence? Where does it fall short compared to Flare?

Robert Lauriston

I think I needed only three user macros in Confluence, all for Scroll PDF output: keep with next for <p> and <li>, and a <pre> variation with a smaller font for command output wider than 80 columns.

Robert Lauriston

The main negatives I encountered with Confluence were minor formatting bugs, which I fixed using the source editor to tweak the XHTML. Flare was worse on that score, though. I had to fix things in source mode all the time (most often a table row getting an extra cell or losing one).

Robert Lauriston

Another major negative with Confluence Server is the lack of support for importing legacy content. The only supported import format is Word, the headings have to have the default style names to break pages correctly, cross-references are not converted, and SEQ field paragraph numbers are converted to static text. That was not an issue for me at this job since I was starting from scratch, but it was one of the main reasons we didn't migrate from FrameMaker to Confluence at my last job.

John Sarra

Before you go too far down the Confluence road, find out who suggested it and what they know about it. It definitely is not an online help tool, although it could be a pretty good knowledgebase. I don't use Flare, but from what I've heard about it, and since you know it and you're going to be the one writing the help, I'd pursue that path.

Mick Davidson (MISTC)

As a long-time Confluence user and big fan of Atlassian products in general, everything that Craig Wright FISTC says is correct. So do not use Confluence for your Help, it is not the right tool. You can, in your code, link from your application to specific Confluence content, but that's about it without employing plugins as Craig has already said.

CREATIVE VIRTUOSITY S.P.

I do not consider Mad Cap Flare a document management system. It is a Technical Writing application for web based documentation that is primarily XML based.

Elizabeth Harris

The authoring interface in Confluence is not great.

Faith Knight, PMP MSPM

Just downloaded the cloud version of Confluence and created a really simple how-to article in about 10 mins. It's OK. Seems just like Word to me.

LaShunda Manly

Thanks for posting this question and thank you to everyone for commenting. We use Confluence as an internal documentation tool and have been considering it for customer documentation. Your comments confirm what I discovered during my research...that we must purchase additional plug-ins and do a lot of back-end work to get the functionality we need. Since we have a very small team, not sure anymore if this is the way to go.

Robert Lauriston

I used Confluence Server + Scroll HTML Exporter to generate web help that was as good as what I created at my last job using FrameMaker + WebWorks ePublisher Pro and better than I created previously using Flare. (That plugin is not available for Confluence Cloud.)

Joanna Boxill

Are you aware that Madcap owns Doc-to-Help

kelley bennett

Yes.

Craig Wright FISTC

Mick Davidson (MISTC) "everything that Craig Wright FISTC says is correct" .

Well there's a first!!

Craig Wright FISTC

Faith Knight, PMP MSPM Wait until it starts adding random formatting in and you can't get into the source code to remove it. Plus, there are a lot of restrictions on what plug-ins are compatible with the cloud version. It doesn't have much in the way of advanced authoring features - which are included in the main product with lots of other tools.

kelley bennett

Hey Craig Wright FISTC, that sounds EXACTLY like Word! Lol

Dave Drexler

I think this is an apples-to-oranges comparison. Flare and Confluence are two very different tools. Confluence is first-and-foremost a wiki. That means it's designed for many-to-many collaboration, not for one-to-many publishing. As Robert points out, there are plugins (the Scroll family, specifically) that give you some of the publishing features you'll want if you're trying to pound the round Confluence peg into a square publishing hole, but you may not be happy with the results. If, however, you want to play to Confluence's strengths and enlist your audience in updating and augmenting your documentation, then Confluence will definitely win over Flare.

Robert Lauriston

Confluence Server plus the Scroll plugins gave me everything I would have used in Flare, plus integrated web-based review, page history, and notifications. It also had the advantage of letting me work on whatever system I was testing on, Mac, Linux, or Windows, hardware or VM. That said, Paligo does all that and more.

Nina Barzgaran

I agree with Dave Drexler to a 't'. I've worked with Flare on a very large documentation project and now am using Confluence elsewhere. The C.s plugins mentioned (esp. Scroll) are fine as far as it goes. But the things you can do or cannot do in Confluence are apparent at once if you've ever used Flare. Perhaps you could put it this way: if you need 'a little documentation to go out' besides using Confluence as a wiki - and have little to no experience in formatting html or XML code - and wouldn't want to have it - then Confluence is your tool. But anything sophisticated or involving build processes together with a well-controlled formatting, content reuse, variant as well as version differentiated publishing, variable usage, etc. - there's almost nothing else but Flare.

Lisa A. Wathen Nina:

"[A]nything sophisticated or involving build processes together with a well-controlled formatting, content reuse, variant as well as version differentiated publishing, variable usage, etc. - there's almost nothing else but Flare."

Exactly that. Also crucial is localization support. (While you may not currently need it, should that change in the future, you have no infrastructure to make that move.)

Robert Lauriston

"there's almost nothing else but Flare": I've used a lot of authoring tools and evaluated most of the rest, and that's simply not true. Speaking solely of the tools I've used heavily, Paligo, Confluence Server + Scroll plugins, or FrameMaker + WebWorks ePublisher could be a better choice, depending on your requirements.

Robert Lauriston

I published web help from Confluence Server for three years, first using Scroll DocBook Exporter and then Scroll HTML Exporter. There are also plugins for CHM and EclipseHelp.
https://www.k15t.com/software#all

Krista Parker

Conditional text: https://openedx.atlassian.net/wiki/spaces/DOC/pages/36012396/Conditional+Text
Context Sensitive:
https://community.atlassian.com/t5/Confluence-questions/Confluence-4-0-context-sensitive-online-help-mapping/qaq-p/332388

As for drop downs and toggles, there may be macros you can include (3rd party) that will help you achieve this, but I don't know of any off the top of my head. I'm not familiar with Flare, but I've used Confluence for documentation and help, and I've never experience an issue. However, I'm biased, as I work for an Atlassian consulting company.

Robert Lauriston

Confluence doesn't support conditional text, you can add it to Confluence Server with Scroll Versions. Krista's conditional text link is to Confluence-hosted documentation for Open edX, not for Confluence itself. (opendex.atlassian.net is a Confluence Cloud instance for the Open edX Community.)

Annette Corbett

I've never used Flare but have experience with Confluence which was the intranet platform at a company I worked for last year. Uploading graphics and adding pleasing aesthetics is a challenge, especially for people uploading content infrequently (use it or lose it!). I was told by a tech guy it was far better suited as a wiki. The online help is nothing short of amazing, however, with a ton of resources. I certainly hope to use it again. Best of luck!

Robert Lauriston

Adding graphics in Confluence is no harder than in Flare or Word. A casual user might have trouble, but an experienced tech writer wouldn't have any problem.

Ramila Baskar

Hi all,

This topic sounds very intresting. I used hardly Confluence for technical or internal documents. Now, I understand that CSH is also possible through it. Does it give the look and feel similar to that of robohelp output.
Please do clarify?

Robert Lauriston

The web help generated from Confluence Server content by Scroll HTML Exporter is similar to WebHelp generated by RoboHelp or Flare.

Eric Ponvelle

Every company that I have worked with whom has used Confluence inevitably stops using it.

I think the wiki like nature of it makes people feel that collaboration will be a huge part of the success of a Confluence solution, but sadly, in my experience anyway, this leads to a lot of duplication, horrible IA, and confusing documentation that is often out of date.

I am using Flare in my current role, and we do a shared project via Tortoise, which works well for our large documentation that has something like 1800 files. The export options are great since we still have to support PDFs.

I would love an online only solution like Confluence or straight up developing a wiki solution, but it would require a very self aware team to maintain.

Sondra Menthers

I personally prefer Confluence even though it has limitations, such as tables cannot be resized easily, limited fonts and colors, etc but other than that, with proper hierarchical planning, its easy for others to find things, easy to have others contribute to pages as a team, so your role would be to edit and cleanup anything devs contribute for example, which makes it easier than constantly getting information from SMEs the old fashioned way. It also works perfectly with JIRA so you can easily for example, create Release Notes from bug reports.

James Strohm

@Annette, using Confluence as a wiki-like tool is an excellent strategy when you can get your SMEs to pour their information into it. When that happens, you'll inevitably face problems with taxonomy structure, but if you're extracting a lot of info from a Confluence install, you can add keywords that'll make your searching easier.

But -- publish in an app that makes your documentation creation the easiest for you. In my latest gig, I've come to like Word (sorta) but secretly enjoy when others use Word and experience colossal Normal-based Fails.

When I started this gig, I told my mgr. that Word was maxed out for the length of my docs, and I wanted to explore using a different app. Well, that turned out not to be a good answer -- first for financial reasons, and second-- if SMEs can't use Word, then they sure the heck couldn't learn a real doc tool. I recall being at Motorola in the 1990s -- they used Framemaker, I spent 1/4 my time mentoring Framemaker and fixing their Fails.

Carin Smith

I've used both Flare and Confluence (along with several other documentation tools), and after a very short learning curve I fell in love with Confluence. It's now my preferred method for developing documentation and help. It is just as easy as Flare, offers far more options for output, and is highly collaborative if teams or SMEs are involved in designing documentation. I highly recommend it.

David Riggins

Sorry if I missed it, if someone else commented, but what does Confluence cost?

Lobhas Paradkar

In my current role, I am using Confluence and though I don't need to create an online help in near future. I would love to explore this possibility with confluence. I have created context sensitive online help using Robohelp in my previous stints, however, looking at confluence it seems difficult to create online help.

Please share reference material if you have, on creating online help using confluence.

Drop the Mic