To all the members of the Atlassian Documentation team, would would you say are the biggest pros and cons of using Confluence as an online product documentation platform?

[Greg Kullberg]

There are so many tools out there for displaying product documentation online.  Lots of companies today use a variety of wiki platforms as well.  There are pros and cons of each wiki and non-wiki platform for doing this.  What would you say are the biggest pros and cons of using Confluence as an online product documentation platform?

[Bob Kennedy · Accepted solution]

I'm not an Atlassian writer either–we've built an end-to-end content supply chain we call DocOps with Confluence at the center.

Pros

Agility–the ease of use mentioned above lets everyone be an author, allows agile teams to generate customer content as the code is being authored.

Continuous delivery–Using plugins, content can be authored in one area of the wiki, versioned, and delivered in another whenever updates are required.

Collaboration–depending on how you secure your wiki, customers and other collaborators can either be given access to update the content, or limited to providing comments. Authors/curators receive notifications that can be addressed.

Integration–with APIs and plugins, Confluence can be integration into other platforms and apps so that your content can be viewed and commented on in other platforms such as Jive. You can also integrate your content into you product UIs so you can receive the same collaboration benefits as customers use the software.

Search/Accessibility–the search engine and APIs help customers locate information fast. Plus the techniques you practice to make pages easy to find in Confluence transfer directly to internet and enterprise search engines. 

Outputs–using plugins, you can let customers create their own Word docs, PDFs, or ePubs eliminating your team from having to labor over publishing, Customers get to choose what they want to publish so they can weed out pages they do not need.

Automated–content delivery and translation can be automated to turn what was once an ordeal into something that can be done in step with the agile authoring and delivery of the English content.

Analytics–using plugins and APIs you can create dashboards to track comments, likes, most accessed pages, number of hits, and so on.

We did all of this in 6-8 months while launching over 40 wiki spaces, translating to 19 languages. Like John above, I have a Master's in English.

Cons

Programming required--out-of-the-box, Confluence delivers a lot. However, programming is required to make use of the Confluence APIs to create plugins and features Confluence just does not have–like Search and Replace.

Plugins a must–If you want to scale, version, translate, create images, expect to do it with plugins. However, the bonus here is the plugin developers are experts at delivering this functionality. In most cases you get what you pay for.

Licensing–You are likely to need more than one server, so multiple licenses, or perhaps data center are real concerns.

Infrastructure–The initial entry for Confluence is very affordable (Cloud–hosted), but as you scale you will find the need to add users or scale up in other ways.

Agree with John's comments, too.

[Greg Kullberg]

Awesome list Robert, I totally agree. Just curious - how exactly did you achieve Internationalization? Was each language split into a different space, or did you leverage an add-on? What was the UI like for switching between the different languages?

[Bob Kennedy]

We use the AppFusions Translations Hub and the Lingotek TMS platform to manage the translations. Each language has its own space.

[Ellen Feaheny [AppFusions]]

Bob - awesome post! And thanks Greg for stirring up this topic!! Greg - CA is ripping it with their "DocOps" model. Bob was humble, but I will put it out there for him, to their credit and enormous hard work of evolving their internal doc processes and migrating existing content: https://wiki.ca.com Still work in process (i.e., more docs being populated), but coming along fast. The CA team came to us in Oct 2013, and they were singing in our ears with what they wanted to do, but like you, the translation piece was the tricky conundrum. At the time, we'd already been in development for 9 months on the translation integration solution (and "discussing it" for prior year to that). The CA team jumped in with both feet, helping us and Lingotek push it to a whole new level (given sheer bulk of content and demand), among other. == Next steps, or where I'd like to see this "use case" mature to == * An initial consortium of 5-10 corps + AppFusions + K15t + Atlassian that back this product documentation development approach, full-on, like CA has. * Development of authoring tools/utilities (plugins) geared to the technical writer to allow this "DocOps" approach with Confluence to become more mainstream for this purpose. From a tools standpoint alone, it needs to be able to compete with tools like FrameMaker, WebWorks, MadCap Flare, Author-it, and the rest. In some ways as a deployment platform, strategically I think it already has a strong leg up. If anyone's interested, email me at ellen@appfusions.com and lets discuss/do it. (Cross-link to translation comments here : https://answers.atlassian.com/questions/9385432/answers/9385472 ) == Some personal asides == This particular use case was one of the primary reasons I got involved in the Atlassian ecosystem back in late 2008, after watching Sarah Maddox for prior year from afar, in the early days of Atlassian documentation development. I thought she was absolutely brilliant and correct in the collaborative approach, vision, platform-model. I also thought she was absolutely *nuts* given where Confluence maturity was at the time (I think version 2.1 or less - it was all so raw compared to today). Here's a blog along similar contexts to your posts above... http://www.appfusions.com/display/Dashboard/2012/03/24/New+Confluence+Wiki+Industry-Shaker+Book+-+by+Sarah+Maddox+-+Get+it For posterity, here's a slideshare from 5 years ago, along same themes: http://www.slideshare.net/ellenfeaheny/customware-information-architecture-on-confluence

[John Paz]

I'm not a member of the Atlassian Doc Team (yet), but I've been using Confluence for 3-4 years now and feel like I can at least add a bit to this discussion:

Pros

1. Ease of use for beginners: It has a slick GUI that many users will recognize as similar to word processors they're likely already comfortable with. And aside from the occasional hiccup, the GUI is very responsive and the WYSIWYG editor is much better than most other wikis.
2. Makes your wiki feel like a web page: Too often wikis feel like the forgotten child of the internet, with their cluttered pages and overuse of tables, most wiki pages feel like the internet of 10 years ago. Confluence, however, has great of out-of-the-box features for handling images and connecting to content outside the wiki. Aside from actually coding the appearance of your wiki, Confluence gives you great controls over what your wiki will eventually look like.
3. Makes administering a breeze: As an admin, managing a Confluence instance (or even just one space) is nearly just as simple as it is to create content with the application. Managing templates, creating users, managing spaces, and customizing the look and feel of Confluence is so simple that a guy with an English degree can do it! (Please note, this commenter holds a BA in English and likes self-deprecating humor.)

Cons

1. Single-sourcing has a way to go: Yes, Confluence has Excerpt macros that are useful. And yes, Confluence is great with creating a useful information hierarchy. But if you've ever used a true single-sourcing documentation solution you know that Confluence, and wikis in-general, have a bit more work to do to compete with DITA-based systems that can churn out content for many different platforms from one source. Sure you can export to PDF/Word, but DITA+XML systems just do it better and with the precision of software delivery systems. The learning curve for those systems is much steeper than using a wiki though, and publishing content in this way virtually guarantees that only technical writers will contribute to the doc. That's not always a bad thing (higher-quality documentation), but it does inhibit other users from contributing directly to the documentation, and also turns the doc team into a bit of a production bottleneck. I've worked for an employer than used both systems, but only used Confluence to manage internal documentation.
2. Lots of work for reports: I really wish it was easier to track my user's activity within Confluence. It's not terribly difficult to set up Google Analytics for Confluence, but then this just forces you to use non-Atlassian applications regularly. The ideal solution would be something that works within Confluence, but as it stands there is little that comes standard with Confluence in regards to reporting on user behavior.
3. Like most Atlassian applications, dependency on add-ons is a concern: Simple things like tabs, centering random content, and better-than-crude table management are curiously absent from standard Confluence instances. It is no wonder that Atlassian's marketplace vendors thrive, and that's because the basic Confluence offering has a handful of serious gaps in functionality that many users come to expect. What's a bit more concerning than the fact I have to depend on so many third-party add-ons for basic functionality is that many of the great add-ons that provide this functionality are free, meaning there is little to no obligation from the developer to maintain the add-ons or provide regular support. And when new versions of Confluence come out it becomes painfully obvious which vendors are committed to supporting those free/low-cost add-ons and which have abandon their projects.

Overall

The good outweighs the bad in most categories, and documentation departments short on resources would consider Confluence a savior for their productivity. The learning curve for users is quite shallow (even developers can write doc easily!), and there isn't much of a need to get IT involved for day-to-day admin management; most technical writers would be comfortable Carrying out the admin activities for Confluence. That's huge. However, hardcore technical writers, those of us who need to publish to multiple platforms from a single source or that have very strict requirements, will find a bit to be desired from the colossus of content that is Confluence. 

[Greg Kullberg]

Fantastic response John, this completely matches similar experiences I've observed with trying to use Confluence as a documentation platform. Add-on dependencies is certainly a concern, but can be handled. And relying on Google Docs is good, but might not be good enough for some. Excerpt and multi-excerpt macros are also decent, but are no where near a DITA system. Beyond that, the pros certainly outweigh these cons. I also think one of the big drivers to go with a wiki for your product documentation (and a "pro" for using Confluence) is the ability/need to provide a collaborative environment with your audience. Being able to do something as simple as liking a page or adding comment is great. Some companies even give users the ability to edit the documentation directly and / or create new pages. The ability to create that interaction with both sides of the fence right inside/next to the documentation can be incredibly beneficial.

[Ellen Feaheny [AppFusions]]

+ 1 Needs an Authoring / Tech Writer toolkit (plugins) developed for this to really become great and mainstream. Tons of great energy here - we just need to bring it together, coordinated. We'd love to help make it happen - since it needs this passion and technical writing insights for it to be done right. It is very industry specific, just like all the other tech doc tools are. We will invest in developing these tools with some great customer supporters like you all.. #Sincere ellen@appfusions.com

[Steve Boydon]

I'm with you on this. Confluence is soooo feature rich and provides little extras with addons every time you are looking to do something else. Yes some of the addons are not quite there. However, I have worked in organisations where they take an OTS product and spend £1mm + having it customised. If you look hard enough in Confluence you can find a away to achieve almost everything. As Greg says its the ability for collaboration. I am an auditor and also write policies, procedures etc. The majority of companies are still using Office documents to write their documentation. Its's almost a given that minor non-conformities will be found because some documents will be out of date, still in draft or not approved. This in itself makes Confluence worthwhile as a document wiki. Again excepts, the best thing since sliced bread. Such an easy way to make things standard. Write a introduction once and hey presto it can be used everywhere, Budict OMG, go install it now. How often do you have acronyms, those sets of 3 capital letters strewn about all over the place. Use Budict and hover over a term and you get the meaning pop up. My only missing feature which has been discussed but never implemented are 'variables' Although using multi=excerpt you can have a company name, type it once and then it is consistent over the whole site. When added Confluence as a base system will be complete :) We still have all the addons to achieve those little things you need to do. What I like about Confluence is its ability to adapt, I've never looked at DITA stuff, but i get the impression the features are a little one dimensional. In so much that they are pure documentation. Confluence adds soo much more. Maybe look at this as you would do buying a piece of tech, smartphone, tablet, pc, laptop. Each has its own value, to me DITA is a laptop or desktop depending on which one, Confluence is a smartphone not even developed yet, it is ever changing to what we need. With all the accessories made that can add on exactly what you want, A laptop or desktop only allow cases, more space, more ram, faster cpus, but restrict you in where you can go and how easy they are to use at the flick of a button. in the end the pro's and benefits of Confluence, and oh yeah, the price far outweighs the cons. Especially for small to medium enterprises that need to comply with standard a/b or meet a customers requirement. Confluence to me allows the small fish to play with the sharks. (sorry for that one) Steve

[Greg Kullberg]

I find it amazing how many people still create things in Word documents and email them out Steve, or just throw them up on a share somewhere. It's so inefficient, and very prone to version control hell. I wrote this a while back with my thoughts on it: https://medium.com/new-media/the-document-is-dead-47e3da4994de. Thanks for pointing out BuDict, I hear you about having all of these acronyms inside of organizations. As a new employee it can be pretty tough learning all the lingo.

[Steve Boydon]

I believe people and organisations are afraid of change. Ever since my foray into corporate world, documents are still being created in formats that are in my mind way past their sell by dates. As an auditor and documentation writer I see day after day documents that are stored using all means available, sent in emails, to 10's of people, then probably stored again and again. People then refer to them for ever and ever and don't always get the updates. Confluence solves all of this without any addons Watch - soo simple, Only watch documents you need to. Comments - provide feedback to the author. Version history - No brainer for me, next time you get a Word document try looking at the history or if comments and tracked changes are enabled, go fathom that. As for addons, Adhoc Workflows - on the spot peer review and approval builtin. Have you ever tried approving a Word document (outside of Sharepoint) pretty archaic And while i am on it.Pros for Confluence against SharePoint. In my mind achieves more than what people use SP for. Additionally in essence you need to license, SharePoint, MS SQL and Office to make it work. So the last pro has to be cost. Out of the box for an organisation of 25 people how much does Confluence cost............ No contest

[Kelly M. McDaniel]

I'm also not an Atlassian writer, however, I have used Confluence to migrate from Framemaker to the Eclipse IDE and produce Eclipse Help. I accomplished this by using the K15t Eclipse Export plugin, the REST API URL produced by the plugin, and Bamboo to automate the entire process. After export from Confluence, I copied the REST API URL. In Bamboo, I made the Bamboo application a Confluence User (user name and password), with credentials and export permissions. When the build was kicked-off, Bamboo logged in to Confluence, used the REST API URL (which contained all my export configuration information) to export to Eclipse Help. We then ran some bespoke trivial regex routines for our proprietary conformance, and rolled the Eclipse Help into our RCP product. After automation, every time a build was called, CURRENT help was produced and rolled in. Because we were on a fast-iteration agile schedule, it was essential that product and documentation stayed as close to concurrency as possible. Although this may sound complex in description, in many years of technical writing this was the most successful, most productive, most effective project I've built.

[John Paz]

Wow! What a fantastic solution you've got here. Did you design this yourself?

[Kelly M. McDaniel]

Kelly M. McDanielDeleteConvert to answerjust a moment ago The Confluence/Eclipse IDE side, yes, I did. The Bamboo side was done by my R&D Software Development Manager in Bamboo. He set-up the build processes. However, I used the fully-configured, software developer IDE, so I rolled my own context-sensitive help within Eclipse, and could run a local build at any time to verify my work. This is an important component of fast-iteration. I am open to helping with this style of process automation, fast-iteration, chaos mitigation. I believe that the technology should be completely transparent to the writer. Anything else is a distraction from Task One: Supporting Customers.

[John Paz]

I've used such a setup at a previous employer. And I can attest to the complexity of the setup, as well as the ENORMOUS benefits of taking the time to set it up correctly. Being able to deliver your documentation from a single source is where all documentation departments need to head. However even at the aforementioned previous position, we still used Confluence and the automated single-source solution exclusively; Confluence was for internal documentation and the latter for external users. I really admire your solution for combining the two. Thanks so much for sharing. You'd do well do start a blog or write some guest blog posts about your solution, as I'm sure it would lead to lots of attention to your hard work (and potentially future gainful employment opportunities).

[Ellen Feaheny [AppFusions]]

Kelly - beautiful example of "DocOps" :) and how it should be ..

[Kelly M. McDaniel]

Aw, shucks, Ellen, I had a lot of fun doing it. I approach each situation such as this with the philosophy that we are the humans. We invented technology, and it should serve us, not vice versa. The corollary is "Technology should enhance our humanity, not diminish it." To me, each of these projects is a massively complex puzzle, and many of the pieces are unknown. The joy of discovery, even discovering something I got dead-wrong, pleases me greatly. You don't learn much from getting everything right the first time. Y'all don't be strangers. Look me up, we'll connect, and talk about some of our favorite solutions...regards, Kelly. www.linkedin.com/pub/kelly-m-mcdaniel/2/64a/938/

[John Paz]

Read my mind, Kelly... I already tried to follow you here on Answers (wasn't able to for some reason)... You can expect an invite from me via LinkedIn in the near future. Your philosophy, Kelly, is great a closely reflects my own. I love learning new things, and the more complex the problem the better! Cheers! See ya around.

[Kelly M. McDaniel]

@John Paz "You'd do well do start a blog or write some guest blog posts about your solution, as I'm sure it would lead to lots of attention to your hard work (and potentially future gainful employment opportunities)." I'd love to, really, but believe it or not, I am blog-ignorant. You have encouraged me. My next Google saerch will be "How to start a blog."

[Kelly M. McDaniel]

Thanks, John. I recently did. Check it out at: http://ProAustinWriter.com

[Nils Bier _K15t_]

Hi all,

nice discusseion.

Talking about DITA vs. Confluence, you might be interested in the following blogpost: https://blog.k15t.com/2014/07/apples-and-oranges%3A-seven-reasons-why-confluence-and-dita-are-hard-to-compare

Furthermore please feel free to have a look at the case study how the Atlassian Tech Writers use Confluence to keep pace with their agile development teams: https://www.k15t.com/company/customers/atlassian-technical-writers-keep-pace-with-agile-development-and-manage-versioned-content

Cheers,
Nils

[John Paz]

Wonderful information! Many thanks for sharing.

[Nils Bier _K15t_]

I've just uploaded a presentation about techcomm with Confluence here: http://de.slideshare.net/k15tsoftware/get-everyone-involved-technical-communication-with-wikis and we have a video interview of Rachel Robins showing how they use Scroll Versions: https://blog.k15t.com/2014/09/interview%3A-learn-how-atlassian-tech-writers-keep-pace-with-agile-development-tools-%28video%29

[John Paz]

Thanks so much!

[Matt Reiner _K15t_]

This new guide on writing documentation in Confluence does a good job of explaining the benefits of using Confluence and how different technical writing techniques are performed: https://www.k15t.com/rock-the-docs.

[Bob Kennedy]

Thanks for the references.

[Nils Bier _K15t_]

sure :-)