Category Archives: SharePoint

Comparing SharePoint and Confluence

People often ask how SharePoint and Confluence compare, especially as tools for building and hosting technical documentation. Here’s my take on it, as someone who has used both.

I’ve worked as document manager on SharePoint and as technical writer on Confluence. A while ago, I did a comparative study of SharePoint 2010 and Confluence. The focus was on using the tools for technical documentation. I examined the following aspects:

  • Designing and creating a documentation suite. Developing a document. Providing structure via mechanisms like a table of contents, a left-hand navigation bar, and logical page ordering. Classifying documents via keywords and other metadata, for ease of browsing and search. Moving documents around.
  • Collaboration. The features that enable collaborative content development and review. Comments. Concurrent editing. Checking documents in and out. Version control for individual documents and pages. Tracking of updates via page history, RSS feeds and notifications.
  • Workflow and permissions. Using workflow features to create a document or page in draft status, have it reviewed, publish the final approved version, and when necessary, update the document or page after publication. Controlling access to documents and pages via permissions.
  • Support for other formats. Publishing to formats like PDF, DocBook XML, and HTML. Integration with Microsoft Office. Use of the documentation site as destination for online help.
  • Managing attachments and legacy documentation. Uploading and serving existing documents and attachments.
  • Overall usability and reader’s experience. Collaboration with readers and other authors. Engagement of the readers in the documentation. Efficient use of time in the authoring and publication workflow. Aesthetics and simplicity.

Looking specifically at the wiki part of SharePoint, I found that the SharePoint 2010 wiki is not the same sort of tool as a standalone wiki platform. The SharePoint wiki is more like a set of web pages that are unrelated to each other. But because they are one of the components of the SharePoint platform, you have the power to manipulate and integrate the wiki pages with the other components.

SharePoint and Confluence are totally different things. Both have areas of strength and areas where they are less strong.

  • SharePoint is an all-in-one portal development and document management tool, with wiki pages tacked on.
  • Confluence is an all-in-one document development, document publishing and collaboration tool, with management of external documents tacked on.

My conclusion was that you should use SharePoint if both the following are true:

  • Your primary need is document management. There is a large set of existing documentation in various non-wiki formats, such as legacy Word and PDF documents, complex Visio diagrams and spreadsheet formulas. In addition, you have an existing, stable and tidy SharePoint installation with competent, full-time site administrators.
  • You need a wide variety of discrete content types all on a single portal, such as discussion lists, task lists, non-wiki documents, and web pages.

And Confluence is the right choice if both the following are true:

  • Your primary need is document development and presentation. You want a single platform for designing, developing, and publishing your documentation.
  • You want your documentation easily accessible to readers and authors, with a uniformity of interface that is unintrusive and predictable (in a good way). Content is king. Readers and authors collaborate on the page itself rather than in separate discussion lists.

A quick note: I’ve previously posted a similar report on Technical Writing World, in a forum, and in my book. Now I’m doing the here, to give more people the chance of finding the information. (Thank you WordPress and Google for the SEO goodness.)

Comments welcome. :) I’d love to hear from people who have used both tools, and also to hear if this information is useful to people who have used only one or neither of them.

Wiki docs – the challenge and the call

Calling all technical writers — are you a wiki hugger already, like me :) or just getting interested? Let’s get in there and make our voices heard. We’re in the front line, writing technical documentation and pushing it out to readers in far-flung corners of the world. Wiki technology has been around for a while, and many wiki developers are looking for new things to do with their product. New features and innovative mashups appear almost daily. Let’s speak up, tell them what we like, and help make wikis even better.

endithinks commented on my previous post, asking what the challenges are and when it would be inadvisable to use a wiki. And Don pointed out a couple of problems we’ve had to work around, when using a wiki for document management. He also identified the tree in my photo. Thank you, guys.

So, what does a wiki not do very well? Should it be doing those things at all? And what’s happening in that sort of arena?

A wiki is not a document management system. It’s not meant to be. If you need strict version control and records management for purposes of legal or other compliance, then you’d probably stick with a more traditional document management server, such as Documentum, Lotus Notes, SharePoint or what have you. Also, if you have a large existing base of documents in other forms, it would be cumbersome to upload them to the wiki and then ask your readers to view them as attachments to wiki pages. Instead, you might use a wiki as a knowledge management system running alongside your document server.

Keep an eye on the new stuff happening:

  • Atlassian and Microsoft have announced a Confluence-to-SharePoint connector. This is exciting for those of us who know and love :) Microsoft SharePoint. The connector is very new, so it’s a free download while still in beta. If you’re interested, try it out. I think that this is a great time for technical writers and SharePoint power-users to have their say on what the Confluence-SharePoint integration should do. It’s a bit basic right now.
  • An intriguing snippet of information in a comment from xaop on a blog post by Craig (2nd comment in the list) mentions integrating their Docbook publishing process from Subversion into their project website, so that customers can link tickets, wiki pages and comments into the docbook. I’d like to know more about that one.

Wikis don’t really do workflow. In most cases, a wiki is for instant gratification — view, edit, save, and bob’s your uncle. But again, things are on the move. Here are some new developments I’ve come across. Let me know if you’ve seen others.

  • Comala Tech have written a workflow and approvals plugin for Confluence.
  • Atlassian is working towards the launch of JIRA Studio, which will allow people to use Confluence (wiki) and JIRA (project management and issue tracking) on one integrated platform. There will be some interesting source control and review tools in there as well.

Wiki editors are not always easy to use. Many of them rely on wiki markup, and there’s not much standardisation of the markup codes used in different wikis. But things are on the move:

  • DITA Storm offers a browser-based DITA XML editor which you can embed in your web application.
  • A number of wikis offer WYSIWYG editors.
  • I’ve used Confluence and Twiki. I much prefer wiki markup to a WYSIWIG editor. But many of my colleagues swear by the WYSIWYG editor.

I’m a self-professed wiki hugger, and I’m not alone in that. A wiki has a certain charm and gives ‘everyman’ a sense of power (that instant gratification again). And wikis do a lot of things very well indeed. Because wikis are the flavour of the month, even after being around for a few years, they’re growing and changing apace. Now’s the time to have a say in their development.

Let’s make ourselves heard. Download a wiki and try it out. Most wikis let you try one for free, and some offer an ongoing free personal licence.

Make a fuss about the things that wikis are missing (see all the comments on and the votes for this requested Confluence improvement) and pat the developers on the back for the bits they get right. Let them know we ♥.

If you’re interested in more ideas and experiences in using wikis for technical documentation, read some of my other blog posts on wiki docs and watch this space — more coming. Also, wander over to Anne Gentle’s blog and search for other wiki writers’ blogs.

There’s a lot more happening. Let me know what you’ve seen and done.

Look at my buttons

As most of you know by now, I am a technical writer at Atlassian. Each member of our technical writing team is responsible for documenting specific products. At the moment, these are mine:

Buttons
  • Confluence is kind of: “Here I am – look at my buttons!”
  • Crowd is the strong silent type: “I’m working away in the background, taking care of stuff for you. You won’t see me until you need me.”
  • FishEye‘s effortless charm hides a manic cleverness: “Here’s looking at you babe.
  • Crucible offers with a nonchalant air: “Do you want to talk about it?

When it comes to wikis, a good-looking GUI is really important. That’s GUI, not ‘guy’ – though a handsome man never goes amiss. You need to get intimate with your wiki. Every click should give a frisson of satisfaction. Every new page should look awesome on first save. It’s like a good first date. You want to want to come back for more. Delayed gratification is not what you’re after. Otherwise, you’d write the code yourself, in all those xxxML varieties, right?

So I’m really pleased that Confluence 2.6 is here. It’s been a long time coming, and it’s my first big release since I joined Atlassian. So I’m kind of fond of it. It comes with a new theme, more pictures dotted about, and a friendly style. Some people think it’s ugly, but I’m ready to go to bat on that one. Button
Another button I had a lot of fun devising a new format for the release notes, with much input from other Atlassians. That’s the way things work in the company. You put up an idea, and everyone throws comments at it. After a bit, the final result emerges. Take a look at the new format of the release notes, and let us know what you think.
Why would a pretty GUI and a sense of achievement be good things to offer users of a wiki? Well, people will be comfortable using the wiki, feel proud of what they’ve created and develop a sense of ownership of the site and its content. Above all, they will come back for more. I’m thinking I might wander along to wikipatterns and add a new pattern, based on this paragraph. I’ll call the pattern something like ‘UI Delight’.
Some people have made Confluence their own by metagrobolising the look and feel. Yet another button Here are some pretty cool sites powered by Confluence: Toxipedia, CustomWare and thesarvo.

Are other wikis sexier than Confluence? And how about Microsoft’s SharePoint – is it pretty or friendly? Let me know what you think…

Follow

Get every new post delivered to your Inbox.

Join 1,446 other followers

%d bloggers like this: