It's "Reuse" not "Re-Use"

Technical Writing in a Wiki – Content Re-use and Structure

MS Word, includetext, and templates

Editor's Note: The link to http://www.paulpehrson.com/flare-content-reuse/ needs to be tested.
Five years ago today, I posted the following on Techwr-L:

On 4/7/2015 1:01 PM, I wrote:

I am so JEALOUS! Over the 20+ years of my career, conversions - whether it
was OfficeVision to Word, WinHelp to HTML, or Word to Confluence - have been
my favorite projects. Even outside of work, I love converting - CDs to MP3,
vinyl to MP3, and cassettes to MP3. Conversions are my passion!

Recently, we've transitioned from authoring in Word and distributing PDFs to
using Confluence. I did not know anything about Confluence until I started
trying to maintain content in it.

One thing I think is worth considering - are your users going to "accept"
your docs on a wiki? We jumped into it, internally reviewed it (within our
dept & and within the company), gave it to the end-users and the first thing
they said? "How do I print a PDF of all the pages?"

<sigh>

We had to add a process for creating a PDF of the user guide that is posted
on our Home page. We make it clear that the PDF is a snapshot of the content
as of MM/DD/YY and that it is going to be quickly out of date if you print
the thing.

All that said, if you suspect you have multiple versions of the same text,
what I messed around with was creating a single (somewhat massive) Word doc
with all the Word doc content in it.

However, before I could do that, I took a copy of each document and replaced
the paragraph character with "- [unique_code]" so that when that document is
combined with all the other Word docs, you know where it came from. For
example, we have a "Adding a User" heading in all of our docs. If you
*don't* add a unique code to each paragraph, you get this:

Adding a User
Adding a User
Adding a User
Adding a User
Adding a User

And you don't know where they came from. For us, states are a good way to
group things so I had:

Adding a User - AZ
Adding a User- CO
Adding a User- FL
Adding a User- TX
Adding a User- VA

So, after you have that pre-processing done, combine the docs into a single
Word doc, because ultimately, what you want is something like this:

Adding a User - AZ
Adding a User- CO
Adding a User- FL
Adding a User- TX
Adding a User- VA
Changing a User - AZ
Changing a User - CO
Changing a User - FL
Changing a User - TX
Changing a User - VA

Then, you create a single version of your procedure, looking at how each
version is different. If there's something customer-specific, then you make
a note of that, but the end result is a single way you are going to tell
your users how to "add a user", how to "change a user", etc.

Then, and only then, do you begin thinking about include fields and such.
Otherwise, you are going to have very similar fields that have only slight
variations that are used for specific customers, but not a single "include"
for all of your docs.

That said, I came across this page the other day -
http://www.paulpehrson.com/flare-content-reuse/ - that may be helpful. It's
older (2007), but some of the philosophy behind it (not the Flare-specific
things] may help you out.



-----Original Message-----
From: Jay Maechtlen
Sent: Tuesday, April 07, 2015 1:19 PM
To: TechWrl list
Subject: MS Word, includetext, and templates

We're using Office 2013 on Windows 7, deployment planned on SharePoint.

1) Anyone using includetext fields to consolidate multiple Word docs? Any comments on best practices, templates, styles, etc?

2) Anyone deploying on SharePoint Wiki sites? We intend to move docs to the Wiki, but building in Word until the Wiki is really ready. (and/or we know how to use it well enough.)

Current docs are combination of Word and Excel docs.

Comments, suggestions welcome.
Thanks
Jay

--
Jay Maechtlen
626 444-5112 office
626 840-8875 cell
www.laserpubs.com

My Thoughts

In addition to being Alex's 20th birthday, readers of this blog know I was laid off from Pearson on Tuesday, January 26, 2016. Today, on the 1000 day anniversary of being laid off, I want to go back in time to when I noted the changes I point out below and how they made me cringe. Even after 1000 days of not being involved, I'm betting these issues make me cringe as a technical writer.

---

---

The way text that is only within a drop-down and how the Confluence search works likely still bothers me. I know I wrote about this previously, but it is important enough (to me) to reiterate.

1. If you search for the word "exceptions" in the global search for the Confluence site, it is found, as shown below:
2. If you click the search result and then search for the word on the page, it is not found.
3. In order to find the word, you have to expand the drop-down. I disagree with making the user have to figure out where the text is located. In the mindframe of a user, I would think the global search for the Confluence site is broken.
   

---

Editor's Note: When this post was created, it was 3/23/2017, and today, 10/22/2018, is the 1000 day anniversary of that horrible day. Updates had been made to https://support.assessment.pearson.com/x/dRFgAQ - and it was worth it to point out what is pointed out above.

Best Online Help You Have Seen

1. These Are Nice and they were created with Confluence...
2. https://docs.memsql.com/
3. https://github.com/PharkMillups/beautiful-docs
4. http://www.circularlabs.com/documentation2/documentation.html - I enjoyed reading this:
• Be warned that Mobius is a complex program with an enormous number of options. Many people say that it is "too complicated", the user interface is "ugly", and the documentation is "boring". All of these are true. If you are looking for a DL-4 emulator with photo realistic knobs you can just plug in and play then look elsewhere. If you are looking for a new musical instrument you can customize to work the way you want it to, then you've come to the right place. Just be prepared to do some reading and ask a lot of questions.
5. http://linlaurie.com/portfolio1/
   

Some Confluence Resources

I do not long for the days when I used Confluence on a daily basis at Pearson. I am happy using RoboHelp at work as I work on Knowledge Management & Disaster Recovery documentation.

1. https://www.google.com/search?q=confluence+tutorial+youtube
2. https://wiki.nci.nih.gov/display/WikiTrainFAQsTips/Wiki+FAQs+and+Tips
3. https://confluence.atlassian.com/doc/move-and-reorder-pages-146407727.html
4. https://marketplace.atlassian.com/addons/app/confluence/top-rated?query=spreadsheet
5. https://xmlpress.net/2017/02/28/confluence-tech-comm-chocolate-free-ebook/
6. https://jira.atlassian.com/browse/CONFSERVER-14198
7. https://www.atlassian.com/blog/archives/why-we-removed-wiki-markup-editor-in-confluence-4 
8. https://www.k15t.com/software/scroll-translations
9. https://confluence.atlassian.com/confeval/billing-and-licensing-evaluator-resources/customization-and-professional-services/do-i-get-access-to-the-source-code-if-yes-can-i-customize-the-code 

---

Hi Keith,

I haven't had to create a spreadsheet in Confluence, so can't answer that specific question.

But in terms of a bit of advice based on a couple years of experience maintaining content on a Confluence site with thousands of pages of content:

   1. If you have a single hierarchical arrangement in which you wish to
   present the topics you create, just organise them in the order you wish in
   the page tree, and you're good to go! If you wish to re-use a single topic
   in multiple different locations in the tree, a separate folder of
   topics-for-inclusion + the Include Page macro to include a shared topic in
   a particular page in the tree seems to do the trick quite nicely. It's not
   quite the same as a full-on authoring system with re-usable content blocks,
   but you can fake it acceptably using that technique.

   2. ** Consider your strategy for search early **. Search is one of the
   weak points of using Confluence as a documentation presentation platform.
   You can mitigate this by using naming conventions for topics that include
   terms users can put in searches, using labels, and even putting information
   in different spaces associated with different types of information since
   search can easily specify the space to search. Because clicking on a search
   result does not advance the displayed page to the location of the search
   string on the page (or highlight the search string on the page) when it is
   opened, we learned quickly that users prefer smaller topics if they plan to
   locate content using search more often than using a TOC or the page
   hierarchy -- because there's less of a document for them to page around
   looking for the content they require.

   3. ** Consider your strategy for versioning early **. You can do this by
   hand, using separate spaces for different versions, so that users can
   search for docs for different versions of a product by specifying the space
   associated with the desired product version -- this allows pages to have
   the same title across versions. Advantage: You can easily clone the space's
   content to a new space for a new version of the docs. Or you can do this by
   hand, with all documentation in the same space -- which requires you to put
   the version at the end of each title so that multiple versions of a
   document can exist in the same space. Advantage: It pleases an admin who
   sees a separate space for each version to be an excessive use of Confluence
   spaces, at the cost of making it a bit of a nuisance to create a new doc
   set for a new version of the product, for any pages that are not
   automatically generated an uploaded with a version-unique title. (No more
   will be said about that.) Or you can try out Scroll Versions and see if it
   meets your requirements.

   4. If you use Scroll Versions to manage across versions (it's not bad,
   depending on what you want to do, but it's not glitch-free either), beware
   that at least as of a year ago -- and probably still today -- you cannot
   post pages using the REST API if you want those pages to be managed by
   Scroll Versions.  We require this for some of our automated documentation
   production -- many of our collection TOCs and individual reference pages
   are generated using local table-driven tools and XSLs that create and post
   Confluence-internal-schema-compliant XML -- so Scroll Versions was out.

   5. Plug-ins are your friend. As Sharon Metzger pointed out, they are
   variable in quality, and some are very much worth the money.

   6. Beware moving and copying pages with embedded images that were first
   added by cut and paste. It seems to be better to explicitly insert images
   file-by-file if you ever plan to move pages around later. (This may only be
   an issue across spaces or may be an issue across permission boundaries.
   Once we determined explicit inserts fixed it, we just proceeded with that
   as process without investigating further.)

   7. Know that the Confluence Server editor is glitchy, but usually not
   fatally so. Confluence Cloud may have similar issues but I haven't put the
   hours into it that I've put into Server. If you are in the editor 6-8+
   hours a day and your topics tend to be on the longer, multi-page side,
   remember this: Control-Z will rescue you from all manner of scary ills!
   Occasionally -- 5-10 times a week for me -- you might be copying and
   pasting around a document, or attempting to apply a heading style, or doing
   something else other than simply typing in the editor, and find that your
   whole document suddenly renders in a particular style, the entire body of
   your document disappears, a cell in your table now contains what used to be
   the entire next row of the table, etc. When this happens, do not panic,
   just undo. Although Confluence sometimes gets the "do" part wrong, it
   RARELY gets the "undo" part wrong.

   8. If you want to buy a third-party theme setup plug-in, beware that
   they can interact poorly with other third-party plug-ins and Confluence
   itself. A theming package my employer uses causes me to constantly get
   "Cannot save page" messages from intermediate auto-saves during editing or
   for final updates -- even though Confluence does seem to save the page.
   Atlassian and the theme plug-in vendor are playing the "No, it's them!"
   game at each other; it's been an issue for most of a year.

   9. Sharepoint tends toward the over-designed end of things. Confluence
   tends toward the under-designed end. Neither are built to be full-featured
   content management systems, just easy-to-use web-publishing systems for the
   masses. The more you use Confluence, the more you will wish it can do, that
   it can't do, and the more you will understand that when they bolted a
   WYSIWYG editor on top of their product's existing non-WYSIWYG wiki editor,
   the end result works like a WYSIWYG editor bolted on after the fact. It is
   a relatively simplistic tool whose power derives from the ability to create
   plug-ins to do things that it, itself, cannot do. Welcome to the club.

   10. If you have a need to export content to Word docs, the Word export
   plug-in seems to produce acceptable output. It's not as well-formatted as a
   document created from scratch in Word would be, but it's OK.

Kind regards,

Helen.

---

The Other P Anniversary

At 10 AM on Tuesday, January 26, 2016, I went into a conference room for a meeting called "Performance Review." It was during this meeting that I was laid off from Pearson after 4 years, 7 months, 3 weeks, 5 days (1701 days). I pray that I never have to go through what happened between Tuesday, January 26, 2016, and Wednesday, March 9, 2016, EVER again. That time in my life - 1 month, 1 week, 5 days (43 days) SUCKED. It was on Wednesday, March 9, 2016, when I received the phone call with a job offer. I started a short 2 weeks, 5 days (19 days) later on Monday, March 28, 2016.

Three Years to the Day

Today is the 3 year anniversary of the PearsonAccess Next & TestNav 8 documentation going online. This was a big deal at the time because we had previously authored in MS Word and distributed PDFs to the customer. Now, we were going to author in Confluence and there would be no distribution - customers would simply access the content through the Confluence site.

---

---

---

I was telling one of my current co-workers about some of the challenges we faced on that team:

• There were some animated discussions where I was the 'majority' - aligned with others on the team.
• There were some animated discussions where I was the 'minority' - not aligned with others on the team.

I'll conclude this post with a final thought about January & Pearson. Later this month, there will be another anniversary.

3 Years' Experience

I pray for anyone that is going to work at this place for a number of reasons. There are just so many things wrong and, to be blunt, shitty, about this ad.

To start, the tools they use are all over the map. The job ad mentions:

• WordPress
• RoboHelp
• Dreamweaver
• Confluence
• Sharepoint

Then the ad lowers the 'boom' on the reader and states "experience with MS Word and other help-authoring tools" is also what they are seeking.

You might think I'm kidding?

No, I'm not.

---

• Experience with WordPress, RoboHelp, Dreamweaver, Confluence, and Sharepoint

---

They also want someone who can edit videos, work with HTML, XML, and CSS on top of all of that.

---

• Experience with image capture and basic video editing software
• Strong computer skills and an understanding of computer principles
• Experience with HTML, XML and CSS
• Excellent verbal and written communication skills.
• Experience with MS Word and other help-authoring tools.
  Editor's Note: the period exists in the job ad but was formatted as bold for clarity

---

The choice is simple: add a period at the end of each phrase in the bulleted list or remove the period in the last item.

The following screen capture shows the absurd HTML source code for the screen capture below. I pasted it into Notepad - and you might notice when I took the screen capture, I hadn't saved the .txt file. My initial thought was "Why the hell would I want to save this garbage code?" until it occurred to me I can use it as a teaching hour for Alex, who is earning his Management Information Systems degree . . . and may need to troubleshoot this type of code in the future.

---

---

To be fair or at least less condescending than I was above, I don't consider this company to be at fault for the formatting issues that I see in the following screen capture. I do fault the company for not giving a shit about how they don't seem to care that their target audience - a professional technical writer - could react to seeing their job ad. The ad was posted a day ago. Is there not anyone in the company that verifies that their job ads look correct? I am not being mean when I say this, but even Alex would know there is something not right about the way the job ad looks. He may not be able to pinpoint the place in the HTML code to fix it, but he would look at it and say, "That's wrong."

---

---

On top of all I mentioned above, there are two more things I found insulting The first is their second bullet point:

---

3 years’ Technical Writing experience in a professional software development environment

---

Is there such a lack of basic punctuation exist at this company that they allow "years'" to be published?!? 
The second is this phrase:

---

Please note: Assessment testing may be required for this position.

---

After all of the atrocities and writing errors, you're going to test me if I apply for this position?!? It would be very appropriate to be given the HTML source code for this ad and to say, "Fix this code." Any "assessment testing" that is trying to gauge a candidate's basic writing skills is an insult.

I am happy where I work and have no inclination to move to Denver, CO, to work for this company. Why would anyone want to work in such a disjointed situation?!?

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.