JodieM.com.au » confluence

Creating Word Documents from Confluence

Jodie Miners — Thu, 20 Oct 2011 04:53:25 +0000

Expanding on from my One thing in One Place, Once post on reusing Confluence content, the next step is to export that content from Confluence into Word and or PDF to produce printable manuals from your content. Yes, I know, I have that thought too, why would you need to print something when it’s on Confluence and readable on the screen and directly linkable to the content. Well, sometimes I just have to lose that battle and understand that people do in fact like to have a paper copy of documents to read. So the important thing here is to ensure that the Word document or PDF content comes directly from your Confluence content so that you minimise the versioning issues. If you do a major update to your Confluence content, it’s a relatively straightforward matter of exporting and releasing a new version of your Word or PDF document.

To export from Confluence to Word I use Scroll Office from K15t. I have tried the Scroll Wiki exporter to export directly to PDF but it was an early version and I had some issues with it, and I prefer to tweak the export in Word first before doing the PDF output so I will focus on Scroll Office here. (There is also the Confluence PDF Export option if you want to play around with customising it to work for you). Scroll Office is a great product. There are some tricks to getting it working well, and there is still a little bit of tweaking required in the final Word document, but overall it is great – have a look at the documentationto get started with using it. And I must say that the guys from k15t have been very helpful in getting a few bug fixes done whilst I’ve been setting up this export process.My Confluence instance is a help system for a software product. The pages in Confluence are structured in a particular way:

Each screen in the software has a page in Confluence (this helps if we want to add som screen level context specific links to the app at a later date).
The hierarchy of pages in Confluence is set up exactly the same way as the menu structure in the software, that way people can navigate to the page that describes the screen they need some help about.
Each page describes what the screen does and also has a Navigation section that tells the user how would they get to this screen in the software. This is useful if they have come to this page via the search or via a hyperlink.
Each page also has links to the next most relevant topic, or the next screen that the user would use if they were on that screen.

When preparing the Word manual for the software there are a few differences with the way the content needs to be structured. As the document is in a linear form, and most users will be seeing the manual in their training course, we don’t really need all the navigation instructions or the links to the next topic, as the next topic is right below it on the page. There may also be some text that is specifically in the manuals such as training exercises or introductory comments. So there is a little bit of tweaking required in Confluence to be able to produce the ideal Word export.The first thing to understand when using Scroll Office is how Scroll Office handles headings – that will help you work out the way that the content for export should be structured. Basically the heading levels that have been used in Confluence are ignored and it all works on a hierarchy. Page Names are Headings in Word, then the h1. to h3. etc become headings under that heading. Pages in the hierarchy under that page also become headings, so depending on your hierarchy of your pages in Confluence you could have a very nested heading structure in Word. This is not ideal. So the trick (for me) is to create new pages in Confluence that will be my pages to export. I then include the content from my regular Confleunce pages into these pages and set up these export pages to have a much flatter hierarchy and heading structure (eg by including multiple pages into the one).

As mentioned above, I also want to exclude some of the content from my main pages in the export, so this is where the wonderful {builder-show} macro comes into it’s own. In the Base Page (the page where the content is edited), I wrap different content sections in the builder-show macro to show only certain parts of the page in the Base Page or the Manual Page. In the Manual page I use the {import}Macro to import the contents from the Base Page. See the example content below.

Page Setup in Confluence for Word Export

This way I have two pages of content but only one page that I need to maintain. The next step is to import two or more pages into my manual page, separated by headings. It does not matter that these manual pages are quite long, because I hide them from the main navigation menu – the users who come via the navigation only see the Base Page.

Another trick I use is the {scroll-pagetitle} macro. I want the headings on the Word document to be the same as the headings on my Confluence content, but as I’m creating new pages to export the content, I can’t have the same page names in Confluence. So I just add the word Manual to the end of my page name for my manual pages and then use the pagetitle macro to revert back to the same title on the Word export.

Word Tweaks

Of course the best export from Confluence only happens if the Word Template is set up well with good heading styles (down to about heading level 6), bullets, numbering, headers, footers, page numbers, title pages etc. Spend some time tweaking your Word Template along with your export pages in Confluence to get the best results. There are some tweaks I do in Word, for which I use Macros (these are for things that are specific to my Confluence instance so I won’t bore you with the details). It is great that Scroll Office allows the document template to be a macro enabled template, so the macros are already built into the document when the document is exported.I do suggest that you do a thorough check over your Word document once it has been exported and tweak the content looking out for the following:

Update the Table of Contents.
Remove additional paragraph returns after images (k15t said they plan to fix this in an upcoming release).
Adjust page breaks.
Check spelling again (yes, it is amazing how many spelling errors you pick up seeing it in a different format).
Resize images or adjust formatting if it helps to get things to fit on the pages better.

The less you need to do with final tweaking in Word the easier it is to re-export the content next time.

The final step is to save the Word document as a PDF file, which of course Word 2010 does out of the box. After you have created this PDF file it may even be worthwhile adding these documents to a page in your Confluence site so that users can download the completed PDF file.

Using these steps I have been able to create 3, 150 page word manuals and a few smaller quick guides on how to use the software – all based on the base content pages.

I hope this helps you, but if you have any tips or other suggestions on how to get great looking printed manuals from your Confluence content then please let me know in the comments.

Building a Glossary in Confluence

Jodie Miners — Sat, 13 Aug 2011 12:00:14 +0000

When building a Confluence site, or any Help documentation, it is very important to have a Glossary to help explain some of the terms that will be used in the documentation.

Confluence has a few examples of glossaries in their own help system, but of course I wanted to take it a step further – I wanted my glossary terms to have hover text in the main body of the help system, then with a hyperlink to the full glossary text. Also, the glossary should be on one Glossary page and be able to be included in the printed documents.

So, of course, it’s User Macros to the rescue – that along with a lot of help from the Confluence support forum, here’s what I came up with:

The Glossary Macro

{anchor:$ParamName}
h3. $ParamPhrase
{cloak:id=$ParamName}
{multi-excerpt:name=$ParamName}{html}$ParamPhrase{html}{multi-excerpt}
{cloak}
$Body

Create the macro to “Convert wiki markup to HTML”.

Breaking down the macro:

We create an anchor to come back to this Glossary entry at any time from the main content.
The Parameter phrase is shown in a heading 3 style. The phrase can contain multiple words – eg “Glossary Entry” may be a phrase for a Glossary term.
There is a cloaked (hidden) section containing a multi-excerpt macro, which contains some HTML formatted text. The multi-excerpt macro will be used to display the Glossary term in our main content pages.
The HTML text has a dotted green underline and a hyperlink back to this page, it also has a “title”, which forms the hover text (or Tool Tip) of the Glossary term.
Finally the body of the macro is shown – this is the full text of the Glossary.

Glossary Macro Usage

We call the Glossary Macro on our Glossary Page with the following code entered into the Wiki Markup of the page.

{glossary:Name=MyName|Phrase=My Glossary Phrase|Tooltip=My Hover or Tool Tip Text}The main description of the Glossary term. 
This can contain as much information as needed.{glossary}

You end up writing the ToolTip again in the the body, but as both bits of content are stored in the same place, it is easy to update them.

This will display on the page as:

My Glossary Phrase

The main description of the Glossary term.

This can contain as much information as needed.

The rest of the content is hidden because it is inside the cloak macro.

The GL Macro

This is the macro that allows us to use the Glossary term in the main content of the Confluence site and link back to the Glossary page, as well as show the ToolTip on hover over the link.

The macro text is simply to use the multi-excerpt include macro to show the multi-excerpt text we set up on the Glossary page.

{multi-excerpt-include:pageTitle=Glossary|name=$paramName|nopanel=true}

This will display our Glossary phrase as such:

This is My Glossary Phrase used in a sentence.

When you hover over My Glossary Phrase the text “Hover or Tool Tip Text” will be shown
When you click on the phrase it takes you straight to that anchor on the Glossary page.

GL Macro Usage

The GL macro is simply called by entering the following text in Wiki Markup mode.

This is {gl:MyName} Phrase used in a sentence.

(macro names are always lower case).

Overall Glossary Page

See the content on the Confluence documentation that I wrote about creating a great looking Confluence Glossary page with an alphabetic index at the top of the page.

So it’s very simple to include Glossary words in the body of your Confluence document, the overall Glossary page looks good, and all of the glossary content is maintained and updated in One Place, Once.

I would love to see if you have any ideas for any improvements in this user macro, or if you have a great Confluence glossary page to show off.

The “One Thing, in One Place, Once” Rule using Confluence

Jodie Miners — Sat, 13 Aug 2011 10:51:19 +0000

As a database designer, I am a huge believer in the “One Thing, in One Place, Once” rule (aka Normalization, in database speak).

As I’m currently building a full enterprise help system in Confluence, of course I’m going to extend that rule to my help content also.

I started with the ideas of Re-Using Content in Confluence and Building an Inclusions Library as written by Sarah Maddox from Atlassian, then as I started to need more features, I moved on to some of the other methods for content re-use, so I thought I would summarise them.

There are 4 ways that I use to re-use Content. The {include} macro, {excerpt} macro, the {multi-excerpt} macro and the {builder-show} macro. The {include} macro is the simplest and the {builder-show} is the most complex and most powerful.

I’m mainly using these features to produce a printable version of the help content, which is a bit different than the Wiki content, as it is presented in a linear fashion, and doesn’t have as many links to content unrelated to the narrative of the document.

Have a look at the following diagram, it shows some examples of the 4 macros that I regularly use. The first box is the base page, where the content is originally created. The second box is the wiki markup mode of the page where the content is included. The third box is what will show in the final layout of the page.

(click to enlarge)

Include Macro

The {include} macro simply includes the full content of the base page into the display page.

I use this macro for small notes and info panels that are used in multiple places.

On the display page enter the following in wiki markup mode:

{include:Base Page}

The {include} Macro is a bit limiting as most of my main pages has a section at the top that shows how you navigate to this screen – I don’t need that in my printed document.

The {include} Macro can be used from other spaces with the following syntax {include:SPACEKEY:Page name}. (Also see the Perimeter Plugin from CustomWare for the {secure-include} macro, which is useful for including from spaces that the user does not have access to).

Excerpt Macro

The {excerpt} macro allows for a defined section of the base page to be included in the display page. The content that is between the two {excerpt} tags can be included in the display page.

On the display page enter the following in wiki markup mode:

{excerpt-include:Base Page|nopanel=true}

I use this macro only occasionally for very simple pages as I find it a bit limiting as it can only be used for one continuous section of content.

The {excerpt-include} macro can only be used for content within the same space, similar to the {include} macro.

Multi Excerpt Macro

The {multi-excerpt} macro is part of the Multi-Excerpt Plugin. This is a very cool plugin, but it does cost – luckily it’s not that expensive.

This plugin allows you to have multiple excerpt sections in the base page appear in the display page – the cool thing is that the excerpts can be displayed in any order you want.

Each excerpt defined must have a unique name on the page.

On the display page enter the following in wiki markup mode:

{multi-excerpt-include:pageTitle=Base Page|name=excerpt1|nopanel=true}

The addition of the spacekey parameter allows the Multi-Excerpt macro to be used across spaces, so it is quite useful.

I use this quite a bit, but it still has one limitation – you can’t nest multi-excerpt macros – but I may be asking for a bit much there.

I use it to include the overall page description, then the screen shot, then the steps on how to use the screen, but exclude the navigation and the links to other pages, in my printed content.

Builder-Show Macro

The {builder-show} macro is part of the Adaptavist Theme Builder Plugin and is the coolest macro. The way I use it basically turns Confluence into a bit of database – yes it’s a bit complex to set up, but once it’s set up, the maintenance of the pages is going to be very easy.

Here’s how I use it – There are a number of fields on each screen. The same field can be used in multiple screens, and the same description is applicable to each screen. If I keep the description in one page, then I can use that description in multiple pages – but it only ever needs to be updated in the once place in future.

With the same field description being used on a few screen pages, and the printed manual for those screen pages, it can be used in up to 5 places – all based on the same source.

The main set-up for this macro is done on the base page, where we put in codes to say which pages the content will display on.

{builder-show:title=Display Page}
This is the first excerpt from my page
{builder-show}
{builder-show:title=Base Page}
This is the rest of my page
{builder-show}
{builder-show:title=Base Page, Display Page}
This is the second excerpt from my page
{builder-show}

The first and third sentences will be shown on the display page, and the second and third sentences will be shown on the base page. Sentence 3 will be show on both pages.

The display page contains the one macro – the {import} macro.

{import:Base Page}

And that’s all there is to it .

There is one small limitation with this macro – the content on the display page must be shown in the same order as it is on the base page.

I hope that has helped give you some ideas on how to re-use content in your Confluence site, and if you have any more cool macros to share, please leave a comment.

Getting into my Confluence Editing Groove

Jodie Miners — Fri, 06 May 2011 07:17:17 +0000

I love Confluence. If I could use Textile Markup to do any editing of documents at any time, I would. If Textile Markup was in Google Docs, I would love it (although, now that the keyboard shortcuts are more similar to Word, it’s a little easier).

Of course Confluence is more than about the editing, but in this post I’m going to be concentrating on the editing features of Confluence – especially Wiki Markup. I do not use anything other than Wiki Markup when editing in Confluence*. Even though the Rich Text Editor has improved in later releases, it is still much easier to do “* type the text” to create a bulleted list than to take your hands away from the keyboard and find the icon to apply the bullet style.

(* I do use Rich Text editor when working with large tables – that is my only concession).

I am currently writing a very large help system in Confluence for a web based App that I work with. There is so much to do, that I need to be quick and have systems in place to do things without repetition.

The one thing that is difficult about editing in Confluence as much as I do, is that it is slow – this is the nature of web based applications It is slow to get into edit mode, and even slower to save the page and display the finished content again. There is Word connectors and WebDav, but they can be a bit of a pain and I just want to quickly edit text in a simple text editor. I can guarantee it that every time you think that a Confluence page is finished – there is always one tiny edit that needs to be done, one comma missing or a spelling error – it is this continuous editing that takes so much time.

What I also want most of all is syntax highlighting in Wiki Markup mode – so I can concentrate on the text, and ignore the macro’s and links etc, or quickly find that h2. line with the bit of text I need to edit.

The Confluence Plugin “Confluence In Place Editor” (CIPE) is great as it allows you to edit just the section of the page that is within a heading, and the main advantage of it, is that a text popup window pops up instantly – no more waiting to launch into edit mode.

So I have come up with my workflow for editing Confluence pages – using a number of tools, and I think, even though it is a bit clunky it is faster and cool, because I now have syntax highlighting.

My Apps

These are the apps that I have open when writing my Help System

My app in the browser depending on which one I’m writing about (generally Firefox).
Confluence in Firefox (with Text Area Cache plugin enabled – this is a godsend – just do not use any Web based editing eg Confluence, WordPress etc without it).
Notepad ++ (yes, I’m a Windows user, you could do similar with TextMate for Mac).
Snagit (yes, Snagit is now available for Mac also).
Dropbox (definitely the best thing since sliced bread).
The Confluence In Place Editor Plugin

Notepad++

I Created a User Defined Language for Confluence – based on this site and refining it myself. Text I have formatted in different colours are:

! for images
* for bold and bullets
# for numbered lists
Numbers
{text between braces} for macros
h1. h2. h3. etc
[Links to Pages] in blue

I’m sure there are more things I could colour, but that is a good start and makes the Wiki Markup much more readable.

When editing your document, save the file in dropbox so it’s updated constantly and backed up (just as it would be if you were editing in Confluence).

Snagit

All screen shots of my App are done in Snagit. I don’t upload them to Confluence until the very end as there is always one last minute change you want to do. I put numbering on the screen shot to point my help text at the correct location on the screen – I just use the default Snagit numbers.

It is very helpful to have the text file and Snagit side by side so you ensure that the numbering in the text is the same as the screen shot. (Win Key + Left and Right arrows FTW!)

I also upload my .snag files and my .png files to Confluence, so I don’t have to store them in a separate location – Confluence is my master repository for images. When I need to edit my screen shots for a new release, I just download the .snag file, modify it, create the .png file again, and upload both files back to Confluence.

I use the idea of the _includes page as an image library as shown in this post.

My Workflow

Here is my workflow for creating and editing my Confluence pages:

Create the screen shots and work out what needs to be written about.
Add any numbering or other enhancements to the screen shot in Snagit.
Create the text in Notepad++, viewing the Snagit screenshot side by side with the text to get the text right.
Add the Screen shot link into the document based on the name you have called it in Snagit and the name of your Image Library page.
When the text looks right, paste it into Confluence and have a look at the layout and structure of the document. (Note, there will be no screen shots visible yet – this makes it a bit cleaner to focus on just the words).
Display the Confluence page and the Notepad++ document side by side on the screen, so as you see things in the Confluence page that need fixing, you can quickly edit the Notepad++ document. (You can do this with two browser windows open side by side also and use the normal Confluence editor).
Check the spelling in Confluence as it uses your built-in browser spell checker with the words underlinked (Notepad++ spelling checker is not that great).
Paste the edited text back in to Confluence when you are done. Using the CIPE plugin helps with that as it makes it much quicker to load than going into edit mode.
Once all the text is correct, drag and drop your image files to the Image Library page.
Refresh and check the completed page in Confluence to make sure everything looks great.

So, that’s my workflow. What is yours? Do you have any great ideas that will help streamline my processes, or will my ideas help streamline your processes? Let me know in the comments.

Things to show for 2010

Jodie Miners — Sun, 16 Jan 2011 23:40:14 +0000

This is just a post to capture some of the things that I was involved in in 2010 that have been reported / blogged about elsewhere.

Atlassian Doc Sprint

I stumbled across the site for the Atlassian Doc Sprint and thought it sounded quite interesting so put up my hand to volunteer for the project. 2 days in at the Atlassian Sydney office and working with the Atlassian team in SFO via video conference was great. I love going into other companies and “looking behind the curtain” to see how they work. I learnt some things about technical writing and got to meet the team of technical writers at Atlassian. There are definitely some things that can be improved about the Doc Sprint, but as a concept, I think it’s a great idea, and if you are into Atlassian products, I’d recommend doing it next time to get involved.

So now, there is a page or two on the official Atlassian documentation that was created by me (mind you, the end result is nicely tidied up to fit with the Atlassian style). Here is a post by Sarah Maddox explaining the guide to Developing Technical Documentation on Confluence Wiki.

Girl Develop It

Girl Develop It is a fantastic initiative by Pamela Fox from Google to train women in all thing tech. It is based on the similar program set up in New York. Kate Carruthers introduced me to the program so I signed up to help out with the first course – HTML and CSS. The course was a great success and Kate did a blog post and video of me talking about the course. Pamela has also released her course material which is full of great information. I learned even more than I was giving back, I’m sure. Next up in February is the Javascript course – Book in now, it’s well worth it.

My Top 10 Apps for 2010

Jodie Miners — Mon, 27 Dec 2010 07:19:43 +0000

Following on from my post of My Top 10 Gadgets for 2010, I realised as I was writing it that there were some cool apps and software that I was using this year that deserved to be mentioned. These are not apps that I’ve bought or started using this year, but the ones I have had to most use for this year.

Confluence - I have used Confluence probably more than any other software this year, and I still love it. I jointed Atlassian for two days for their Doc Sprint a while back, and have been creating lots of complex pages using forms and macros. I love this product.
Google Apps – Basically if you don’t yet have Google Apps for Your Domain, and you have a domain, then get it. It just works! I would recommend GAFYD to any organisation unless they have a specific reason or are large enough to use Microsoft Exchange.
Google Docs – Even though it was sad that Google Wave died this year, there have been so many great features added to Google Docs that I now use either Google Docs or Confluence more than Word. Some of the great new features are Drag and Drop images, Heading Style keyboard shortcuts, Collaborative editing and mobile editing.
Dropbox – How much do I love DropBox? Let me count the ways… It’s one of those apps that falls into the category of, if you don’t have it already, just get it now!
Access 2010 – As with most of the 2010 office suite, Access 2010 is a vast improvement over Access 2007. Having built one major client app in Access 2007 and Access 2010 each, I will very much think to say to clients that unless they upgrade to 2010, there is not much point continuing.
Snagit - One of the projects I have been doing this year is writing a help system in Confluence. So ScreenShots are a key part of that project. Snagit is indispensable for ScreenShots. Snagit 10 has some great new features also that makes it worthwhile to get the upgrade.
Sketchflow - I did a full project Mockup in Sketchflow. I now have a bit of a love / hate relationship with Sketchflow. It has it’s place if you are creating a full Silverlight or WPF app, but probably stick with Balsamiq for simple Mockups.
Visio 2010 – Again there are so many fantastic new features in Visio 2010 that makes it so much easier to create good looking and easy to update diagrams. The new live connectors feature alone is worth the upgrade.
Notepad++ – I use Notepad ++ extensively and just found some great new features in it that makes it even better.
Google Chrome – My browser of choice now and the great new features of the Chrome Apps and Syncing makes it the best browser now. I still do use Firefox for web development, however as I love Firebug still.

Other Mentions:

Gmail - still my favourite email app – every time I have to use Outlook (event though 2010 is much better), I die a little inside.
Various VPN’s – I use at least 4 VPN clients and it allows me to connect to various client workplaces and work remotely, which is great.
Office 2010 – Apart from the specific mentions above, Office 2010 is just a fantastic improvement over 2007.
Google Wave – Such sad news this year that Wave was killed off. But overall it might be good – there are features that have been integrated into Google Docs, and now Facebook messaging will be taking a leaf from Google Wave – can’t wait to see that.
SharePoint 2010 – I haven’t done much work with SharePoint this year, but I can’t wait to get my hands on SharePoint 2010 for a real client’s site to see how it works.

Confluence and SharePoint Wikis

Jodie Miners — Sun, 31 May 2009 09:50:30 +0000

This is the contents of a talk that I gave at the May 2009 meeting of SBTUG. It was a session on comparing the features of the wonderful enterprise wiki product Confluence by Atlassian and the wiki features of SharePoint.

The session content was delivered to the user group using the confluence online trial sandbox where you can try most aspects of confluence online before you buy.

This talk will not go into the following

Other Wiki’s other than SharePoint and Confluence – See WikiMatrix for a complete comparison of all Wiki Software http://www.wikimatrix.org/index.php.
The whole debate over the use of Wiki’s and whether you can trust the content on Wiki’s – this is for a corporate usage where there is unlikely to be anonymous comments allowed.
WikiPatterns – although you should look at this site if you are interested in Wiki’s at all - http://www.wikipatterns.com/display/wikipatterns/Wikipatterns.

What is a Wiki

According to wikipedia, a wiki is:

A wiki is a website that uses wiki software, allowing the easy creation and editing of any number of interlinked (often databased) Web pages, using a simplified markup language. Wikis are often used to create collaborative websites and to power community websites … originally described it as “the simplest online database that could possibly work.”

SharePoint and Wiki Features

Wiki Features

No external Editor, no uploading documents, edit button on the page
Wiki pages are constantly a work in progress - http://c2.com/cgi/wiki?WorkInProgress (but Confluence has some add-ins for Page Status)
Revision Comparison
Recently Edited Pages
Links can go anywhere (not a structured hierarchy)
Comments and Discussions

SharePoint features

Document Management
Integration with MS Office

No Matter how structured and organised your content is and how good your search is in SharePoint, a Wiki still makes the information much more discoverable as it’s not hidden away in documents, it’s just a few clicks away at all times.

But Structured Publishing pages on SharePoint could just about do the same thing.

Confluence and SharePoint Comparisons

Confluence

For

Has many many features for corporate Wiki useage
Many installation options (eg Database could be MySQL, Oracle or SQL Server)
Is the most extensible Wiki platform through the Macro’s and Add-ins
Atlassian have won multiple awards
Confluence is now the defacto standard for corporate wiki’s
It can integrate with SharePoint
Has excellent Word and Excel editing capabilities

Against

Built on Java – many MSFT only businesses may be scared off by that
Smaller company – people may think, will they be around in a few years time
Has to be integrated with Active Directory to be useful for business – this can be difficult
Output to PDF limited and very hard to customise
Not there just yet with Office 2007 support (although it is coming)

Other

Does not use CamelCase linking notation (like other wiki’s), uses Free Linking (Square Brackets) instead – seehttp://en.wikipedia.org/wiki/Wiki#Linking_and_creating_pages
Atlassian’s own Comparison Page but it is very old (2005) http://confluence.atlassian.com/display/DISC/Comparison+Matrix

SharePoint

For

Is already part of SharePoint – nothing extra to maintain or install

Features of SharePoint that can be used with the Wiki (from http://woodywindy.spaces.live.com/blog/cns!773832677F575173!653.entry
- Setting Alerts to be notified of changes *
- Setting the permissions of the library, or even individual pages *
- Adding metadata fields – for example, subject tags, or even links to supporting documents
- RSS feeds *
- Requiring approval and document check-out for changes
- Creating different views of the information
- Friendly URL’s *
- Add Web Parts to your Wiki Page

The items above with a * are available in Confluence also

Against

It’s not really a Wiki
Only uses SharePoint’s basic editor
Uploading images is a really big pain
A list of things that SharePoint can’t do from http://www.henricodolfing.com/2009/05/sharepoint-as-enterprise-wiki.html
- There is no support for standard Wiki markup language.
- The content editing capabilities of the default SharePoint Web Editor are limited.
- There is no taxonomy solution, i.e. content tagging and hierarchical categories.
- There is no content rating
- There is no support for subscription RSS feeds.
- No support for comments on Wiki pages. You can add discussion boards, but those are something different than what you would expect from a Wiki.
- The capability for generating reports on the Wiki activity are rather limited.
- There are no Wiki content templates (but this you could easily solve by creating a few page templates yourself).
- There is no easy way to attach files to Wiki pages. You have to do this by adding the content to a document library, and then include the link in your Wiki page.
- There is no support for things like Wanted pages, Orphaned pages, Most/Least Popular Pages, and Recent Visitors.

Other

Here are some links to articles about the SharePoint Wiki feature

To Wysiwyg or not to Wysiwyg

There are a lot of for’s and against for wysiwyg editing of wiki’s. See http://c2.com/cgi/wiki?WysiwygWikiUsefulArguments

Wiki syntax is much simpler than HTML - like a simple conversion layer between rich text and html
One of the main advantages of a wiki is its lightweight structure Confluence has a few basic formats, if you can’t say what you need to say with a few heading styles and bold and italic, it’s probably too complex.
Wiki syntax is simple, straightforward and intuitive - once you get used to working with it, it is much quicker to create documents
Keyboard shortcuts make editing quicker - http://confluence.atlassian.com/display/DOC/Keyboard+Shortcuts

However

Large Tables are a real pain - http://confluence.atlassian.com/display/DOC/Working+with+Tables

A Quote from http://woodywindy.spaces.live.com/blog/cns!773832677F575173!653.entry

One of the complaints often leveled against SharePoint’s wiki is its lack of support for “wiki markup” beyond intra-site page links. While this is true as far as it goes, it doesn’t consider what that markup is designed to do – compensate for the plain-text editing features of most wiki systems. For example, to make italic text in many wiki systems, you enclose the text in ”double apostrophes”. Yet while there are some conventions, there is no true “wiki markup” standard.

SharePoint Demos

(the demos for Confluence were done in real time during the talk).

Screen Cast Demo 1 http://screencast.com/t/oau54Mt3ONs

Navigation
Breadcrumbs
Wiki Pages
Orphaned Pages

Screen Cast Demo 2 http://screencast.com/t/MtM5ZPUC

Create Link to new Page
Insert a Table
Format some fonts – yes you can easily make it very ugly
Go to history
Restore an old version

Screen Cast Demo 3 http://screencast.com/t/hMljFNIe0

Insert a picture into a SharePoint Wiki – showing ow difficult it is to just add a simple picture into a SharePoint wiki.

Extending the Wiki

Confluence

Plug ins http://www.atlassian.com/software/confluence/plugins/
Intranet / Extranet
Full Website see http://www.customware.net
Wiki Wednesday http://www.customware.net/repository/display/WikiWednesday/Wiki+Wednesday
See Confluence Pricing http://www.atlassian.com/software/confluence/pricing.jsp

SharePoint

CKS:EWE http://cks.codeplex.com/Wiki/View.aspx?title=Enhanced%20Wiki%20Edition
- Free
- Not Supported
- in Beta 2 now
- Beta 3 planned
- Development seems to have slowed
SharePoint Wiki Plus http://www.kwizcom.com/ProductPage.asp?ProductID=524&ProductSubNodeID=525
> $2.5k per server http://www.kwizcom.com/ContentPage.asp?PageId=663

The Bottom Line

My thoughts

Use the Wiki Feature on SharePoint but maybe don’t call it a Wiki, or you might put people off Wiki’s for ever.
The SharePoint Dev Wiki is on Confluence http://www.sharepointdevwiki.com
SharePoint is great for structured, corporate information that are policies and procedures that do not need to be edited regularly. If you are a SharePoint house, then use the Publishing Pages and document libraries for the structured information and allow Wiki’s in smaller team sites where a few people are editing them and they are small and single subject based.
Comparing Confluence Enterprise Wiki to SharePoint Wiki is really not fair. SharePoint is not an Enterprise Wiki, and has never tried to be.
However, comparing a corporate Intranet built on SharePoint vs one built on Confluence may be a better comparison, but that is a topic for another session.
In a future session we will look into the Confluence SharePoint Connector to see if it really does enable a company to have the best of both worlds.

Thoughts from others

From WikiSym 2008

The wiki is the place for fast collaborations.
Sharepoint is the place to go for final documents (authoritative).

From http://www.henricodolfing.com/2009/05/sharepoint-as-enterprise-wiki.html

By definition, SharePoint is something completely different than an enterprise Wiki. If all you want is a Wiki, you don’t have to spend your time on implementing SharePoint. There are better solutions out there. But a Wiki is very rarely the only thing that a company wants, and if SharePoint does the most things you as a company wants, then it is very easy to add some 3rd party Wiki functionality and that way satisfying your need for an enterprise Wiki as well.

From http://blogs.atlassian.com/news/2009/03/comparing_sharepoint_to_confluence_wiki.html

Document-centric collaboration systems like SharePoint certainly have a place in the universe. Atlassian has always maintained that SharePoint is an excellent tool for storing and managing online Office documents. That’s why we partnered with Microsoft to build the SharePoint Connector. Martin’s post forces us to think about the differences between the wiki way of collaborating and the SharePoint way of collaborating. Those differences run deeper than a few superficial features like browser support and wiki markup. At it’s core, Sharepoint strives to be something different than an enterprise wiki.