Conflatulence

Video for Atlassian Voice of the Customer

2010-08-27T11:05:00.000-04:00

On August 26th, I was able to present my experience managing Confluence at my company with Atlassian's Voice of the Customer webinar series. You can check it out below or along with other videos on Atlassian TV.

I had a great time and there were some wonderful questions at the end. Be sure to check it out.

Webinar for Atlassian Voice of the Customer Series

2010-08-23T20:54:00.001-04:00

I have the absolute pleasure of sharing my knowledge of using Confluence at the next Voice of the Customer Webinar for Atlassian. You should register today!

From the announcement:

This Thursday, an Atlassian customer is going to share how they use Confluence. This is a must see webinar to learn about wiki adoption within an organization.

Charles River Analytics (www.cra.com) is a small research & development company delivering innovative solutions through intelligent systems. Please join us as Brad Rosenberg shares 1) how his company uses Confluence for knowledge management and team project collaboration, and 2) how a small group fosters wiki adoption, engagement and support. This is a must-see for any small business considering Confluence as a wiki solution or just looking for ideas on how to improve their practices.

I'm really excited to share some of my experiences with the Atlassian Community.

Embedding Internal Streaming Videos in Your Organization with Confluence

2010-08-23T20:40:00.000-04:00

At my company, we run a seminar series where presenters get to show off some of the cool stuff they're working on. Often, these are outside speakers sharing their latest research. We also use it as an opportunity for our own staff to share knowledge with the company or use it as a broadcast mechanism for informing staff about a new policy or procedure.

This sort of thing isn't new, pretty much all organizations do it. Google posts their technical talks online and shares it with the rest of the world.

The trouble is, within our company, if you're not available to be present for the talk, you've lost out. Well, that's not cool. What if it was really critical to what you're working on? Or, what if you attended, but can't remember that one brilliant point the speaker made? What about new hires who weren't around at the time of the talk? Why does that knowledge have to be lost?

Quite simply, it doesn't. We recently started recording our seminars, purchasing a Flip Mino HD for the task. Simple to use, it produces wonderful videos in clear h.264 encoded MP4 files.

But here comes the problem, where to put these videos for everyone to find?

Brainstorming a Solution

Well, we could just put them on the file system, organize them in subdirectories and try to give them easy to remember names. But who's going to go navigate through a maze of a file system directory hierarchy? There's gotta be a better way. Oh wait, there is... the wiki!

Attaching Videos to the Wiki

How about we just attach these video files to a wiki page and just embed the video as easy as an image? Well, a few problems. First, while Confluence supports embedding a number of multimedia formats (e.g., Flash, Windows Media, AVI files), MP4 with h.264 encoding is not one of them. We could post-process our media files and covert them to a format that Confluence supports, but we run into another problem, large file sizes. Our seminars run 45-60 minutes in length, generating a video file in the 1-2 gigabyte range. If we kept uploading them and attaching them to pages, we'd quickly run out of space. Furthermore, every time someone hit that page, they'd be downloading 1-2 gigs of data, which could be a nasty hit to our network.

Linking to Videos on the File System from the Wiki

Instead, we could simply link to the video file on the file system from the wiki. But, that doesn't feel too satisfying. Furthermore, while it might work for some users who are using Internet Explorer, Mozilla Firefox users would have to take extra steps because Firefox forbids linking to your local file system as a security precaution.

Using Video Hosting Services and the Widget Macro

So what other solutions exist out there? What we want is our own YouTube. Wait, why not just use YouTube? And there are a whole bunch of other services out there like Vimeo and Episodic if YouTube isn't to our liking. Furthermore, we can embed them directly using the Widget Macro. Sounds like a great solution. Unfortunately, most organizations (including my own) don't feel comfortable putting internal content out on the web, either for all to see or even if it's private.

Using a Hosted Media Server and a Custom Macro

So we're back to wanting our own YouTube. Well, what options exist out there? There's a few, but most of them cost money. For example, the Adobe Flash Media Server suite of products is pretty popular, but we were looking for a lost-cost alternative, free being even better. Red5 is an Open Source Flash Server that handles streaming media. But, is there something even easier for us to use? After some searching, we found that we could simply run our own Apache web server with the h.264 streaming module and JW Player. Then all we had to do was implement a custom macro to serve it up.

Implementing a Solution

So we decided to run an Apache web server with the h.264 streaming module and using JW Player with a custom user macro. It was actually pretty simple to do. Let me show you how.

Installing Apache and h.264 Streaming Module

First up, go ahead and download and install Apache HTTP Server and the h.264 streaming module for Apache. You could also run a different web server, but we went with Apache. Also, note that the h.264 module is free to use for non-commercial usage. So, if you're planning on using this for commercial purposes, then you'll have to purchasing their commercial license (which is pretty inexpensive).

You might want to name your HTTP server something like http://video.mycompany.com/ or http://media.mycompany.com/.

Next, download the JW Player by Longtail Video. You'll need to drop the player.swf and swfobject.js into a specific web accessible directory in your Apache installation. Similar to the h.264 streaming module, JW Player is only free for non-commercial usage. So, if you're going to use it for commercial purposes, purchase a commercial license (again, really cheap).

User Macro

Finally, you'll want to create a user macro in your Confluence installation. At my company, we set this up as {video}. The video macro takes a few required parameters. First, you'll need to give your video a unique name using the name parameter. This is just to give Confluence a way to reference where to put video in your page. The more important required parameter is url. You'll want to replace this with the full url of where your video file is (e.g., url=http://video.mycompany.com/path/to/videofile.mp4). In addition to the required parameters, you can also specify a custom width and height in pixels. And there you have it. You'll be able to embed h.264 files (and other files that JW Player supports) as streaming videos directly in Confluence. If you want to get fancy, there are a bunch of specialized parameters you can add to JW Player such as skinning, fullscreen, autoplay, etc.). Take a look at the JW Player documentation for the full range of options.

#set($width=400)
#set($height=300)
#if($paramwidth)
#set($width=$paramwidth)
#end
#if($paramheight)
#set($height=$paramheight)
#end
{html}
<div id="$paramname">
The player will show in this paragraph</div>

<script src="http://video.mycompany.com/swfobject.js" type="text/javascript"></script>
<script type="text/javascript">

var s1 = new SWFObject('http://video.mycompany.com/player.swf','player','$width','$height','9.0.115');
s1.addParam('allowfullscreen','true');
s1.addParam('allowscriptaccess','always');
s1.addParam('flashvars','file=$paramurl');
s1.write('$paramname');

</script>
{html}

That's our solution to embed streaming video into a Confluence installation. Our seminars (and other videos, like software demos and walkthroughs) are now captured. That knowledge is kept safe and secure behind our own firewall where we can share those videos internally without exposing them to the external network. Users can skip to any point in the video without having to buffer the whole video first.

Using Apache, the h.264 streaming module, and JW Player is just one solution. How do you share your videos at your company? Share your experiences in the comments.

A HOW-TO Guide Recipe

2010-03-15T09:19:00.000-04:00

Recently, the Confluence Guru made a call to action for Confluence templates. Similar to Bill Arconati's request, the desire is to collate templates for the upcoming release of Confluence 3.2, which will feature bundled templates and a new template marketplace. Much like my recent post where I provided a meeting notes recipe, I'm happy to share some of the knowledge I've gained at my company for the benefit of others. So, here's a HOW-TO Guide recipe for Confluence.

People use enterprise wikis for a lot of things, such as letting project teams collaborate or creating product documentation. However, across any organization there are always policies and procedures that need to be followed to accomplish things. There's a process for filling out a timesheet, requesting vacation time, or setting up VPN client software. Sometimes in an organization, these are well-documented and easy to find. Usually, however, they're not, requiring you to go ask Bob in Accounting or Christine in Human Resources how to perform a task. That is, if you're lucky to know who to ask. Often, you'll jump from person to person until you figure it out (or possibly not!).

This is where a wiki can come in handy. You can use it to help organize these step-by-step procedures in a common location and keep things up to date. Having them stored in a common place means even your newest employees will know where to go to get answers to questions they have.

At my company, this is the HOW-TO Space. The HOW-TO space features a single home page that indexes and organizes HOW-TO Guides. From that home page, you can also add a new HOW-TO Guide or Request a new HOW-TO Guide. When you add a new HOW-TO Guide, we use the following template:

Name:

HOW-TO

Description:

A General Purpose HOW-TO Guide

Template Content:

{section}
{column:width=50%}
{panel:title=Table of Contents|borderStyle=solid}
{toc}
{panel}
{column}
{column}
{panel:title=Purpose|borderStyle=solid}
{excerpt}
This section should provide the overall purpose of the HOW-TO Guide. (e.g. intended audience, lesson)
{excerpt}
{panel}
{column}
{section}

h1. Requirements
* This short section should outline the requirements of the reader to use the guide.

h1. Instructions
# This section provides step-by-step instructions for the reader to follow to perform the particular act described in the HOW-TO.

h1. Tips & Warnings
* List any particular common difficulties that the reader may come across

h1. Related
* Link to any related HOW-TOs or External Links

Labels:

how-to

Let's do a little walkthrough of this template. First, we pop in a nice table of contents at the top. Next, we provide a purpose of the HOW-TO, such as "This HOW-TO will inform full-time employees how to fill out their timesheet" which will also be the excerpt if we ever include it in another page. Next, it's a good idea to provide a set of requirements, essentially prerequisites that the user should have either done before or have at-hand (e.g., have an account with the timekeeping system). Now comes the meat, a set of instructions that go through a step-by-step process. You can then follow this up with any tips or warnings, as any process is likely to have. Finally, finish things up with a set of related HOW-TOs or other resources that might come in handy. You can replace "Related" with either the {related-labels} or {contentbylabel} macro to dynamically generate this piece. Or, you can actually use my own user macro, the {related-content} macro, which combines them both. If you're not a fan of user macros, I'm currently in the process of turning {related-content} into a full-fledged plugin.

So there ya go, a nifty little recipe for creating HOW-TOs. It's become really useful at my own company and likely to do well at yours.

You can even go so far as to create a HOW-TO on HOW-TO Write a HOW-TO!

Do you have a similar space or template at your company? Share how you document policies and procedures in your organization in the comments!

Organizing Your Wiki Content - Part 3: Labels

2010-03-08T06:58:00.000-05:00

In Part 2 of Organizing Your Wiki Content, we demonstrated how page hierarchies can provide a natural way to organize your wiki content. But what if your content doesn't flow so nicely? In Part 3, we discuss Labels.

This is the continuation of a series of posts on Organizing Your Wiki Content:
Part 1: Direct Linking
Part 2: Page Hierarchies
Part 3: Labels
Part 4: Fine-Grained Controls
Part 5: Including Content
Part 6: Wrap-up

Labels

So how do you provide dynamic organizing principles if your content doesn't fall into natural page hierarchies? The answer is labels. Labels (also known as tags) are a way to annotate your content with appropriate topics. Labels are the primary way to find things on many popular web sites like the photo sharing site flickr, social bookmarking site delicious, and communication sites like twitter through the use of #hashtags.
By adding a few labels to your page, it's easy to find content that shares that label as well. By simply clicking on a label on a page, you can search your Confluence installation that have that label, either just in that space or across all spaces.

Browsing labels after clicking on the "label" label

Another way to dynamically pull in content using labels is by using the {contentbylabel} macro. The {contentbylabel} macro will list content that have labels that you specify. You have a lot of control using {contentbylabel}, including which spaces to search through and what kind of content you'd like to include. My {related-content} user macro is another way to leverage the power of the {contentbylabel} macro, allowing you pull in content directly based on the labels of the current page, skipping the step of making you specify the labels. I'm currently in the process of moving this from a User Macro to a full-fledged plugin.

Related-Content: Edit Mode

Related-Content: View Mode

Pros

Using labels is a great way to dynamically discover and link to content across page hierarchies and across spaces in your Confluence installation. What's even more impressive is that labels can create a folksonomy that emerges based on how your users are using your wiki instead of imposing a top-down taxonomy. At my company, we use labels and the {contentbylabel} macro for knowledge management, categorizing projects and organizing our repository of HOW-TO guides.

Cons

While labels can be used to organize your content in an ad-hoc fashion, it can be problematic. First of all, it requires your users to label their content, an extra step that you'll find users don't always do. Also, you'll find that different users will apply different labels for the same category of content (e.g., how-to vs. howto, hr vs. human-resources). This can create some divergence where one group of users applies labels in one way and another group applies labels in another way. Confluence does provide some suggestions when adding labels, but not everyone will abide by that and it isn't a total solution.You're more than likely going to need some WikiGardeners to keep things tidy.

Direct linking too static? Page hierarchies too restrictive? Labels unwieldy? The next article in the Organizing Your Wiki Content series, Part 4: Fine-Grained Controls, will demonstrate how you can be a power user to organize your wiki content.

Are you a big fan of labels? How you found some nifty tricks that work for you and your organizing? Share them in the comments.

Meeting Notes Recipe

2010-03-04T07:57:00.000-05:00

Recently, Bill Arconati of Atlassian asked what templates people in the Confluence community are using for the upcoming Confluence 3.2 release. I was happy to oblige and I'm interested to see what other suggestions he received.

At my company, one of the ways we use Confluence is to organize our meeting notes. This can be advantageous for several reasons. First, having a common product at the end of a meeting can be useful to use as a reference point a few days later after everyone has probably forgotten what was decided. Furthermore, it can be useful for someone who couldn't make it to the meeting to get caught up on what they missed. Additionally, the transparency of putting it on the wiki means those who might be interested in the meeting content can find it indirectly, promoting knowledge discovery. This has the additional effect of providing a passive way of keeping upper management informed of what's going on. However you slice it, having a shareable record of what went on is beneficial.

Meeting Notes Page

So, what's the best way to organize your meeting notes? Well, first of all, you want an easy place to access them. At my company, we have many projects being worked on 2-3 person teams. On our Confluence installation, each project either has a page in the Projects space or has its own individual space. This depends on whether it's a simple project or whether the project team wants to make use of advanced features such as blog posts or permissions. Either way, each project has a homepage. We begin by creating a child page of that homepage for meeting notes and adding the following content:

h1. Current Meeting
{children:sort=creation|reverse=true|first=1}

h1. Meeting Archive
{children:sort=creation|reverse=true}

Each child of this page will then be an instance of Meeting Notes. This page will collect those pages, placing the most recent one (either upcoming or the next one scheduled) under its own heading and the rest of the pages in reverse chronological order. As I recently discussed in Part 2 of the Organizing Your Wiki Content series, Page Hierarchies and the {children} macro can be used in interesting ways. Once you start adding meeting notes, this page will start taking on this form:

Meeting Notes Template

Okay, so now we have a page that organizes our meeting notes, but what should our meeting notes pages actually look like? At my company, we use the following template:

Name:
Meeting Notes

Description:
General Meeting Notes template

Template Content:
{toc}
h1. Purpose
{excerpt}A simple summary of the purpose of the meeting{excerpt}

h1. Agenda
* Agenda Item

h1. Attendees
* Link to attendees

h1. Meeting Notes

h2. Subtopic

h1. Action Items
* Add Action Items

Labels:
none

Let's walkthrough this template. First up, every meeting should have a purpose. It doesn't need to be anything complex, but this is a good way for your meeting attendees (and anyone who comes across this page in the future) to know what this meeting is about. We wrap this content in the {excerpt} macro in case at some point in the future we want to include that information as an excerpt in another page or as part of a report. Next up, we write out the agenda. It's always a good idea to have an agenda for a meeting, just to keep yourself on track and identify what is in and out of scope for the meeting. Before the meeting occurs, you can invite the attendees to add items to the agenda itself (I usually send a link to this developing page in a Meeting Request in Outlook). Following the agenda, we have a list of attendees. Here, I like to link directly to users on the wiki when I can. You can always update this list after the meeting occurs to know who was there and who wasn't. This leads us to the bulk of template content, the meeting notes themselves. I try to break these out by subtopic, each corresponding to an item on the agenda. Then, we sum everything up with the action items from the meeting, which summarizes who needs to do what based on whatever was decided. Additionally, usually at the top of this template I place the {toc} macro to provide a table of contents. This is a helpful addition so visitors to the page can drop down directly to a subtopic in the meeting notes or jump to the action items. Finally, I personally don't find adding a meeting_notes label to the template to be that useful, but you could add one if you so desire.

Using this template, your Meeting Notes will start looking like this:

So there you have it, a useful Meeting Notes recipe to use in your organization. You can spice it up however you'd like. One way you can do this is by using the {add-page} macro in Customware's Linking Plugin in the parent page to create a link to add a page using the Meeting Notes template directly. This makes things easier for your wiki users instead of requiring them to select the Meeting Notes template when creating a new page independently. Additionally, you can use the Reporting Plugin to change up how you organize your meeting notes if you're not a fan of the {children} macro. The Reporting Plugin will give you alot more control into how to display those meeting notes.

Do you use Confluence to organize meeting notes? If so, do you use a similar method or do have an alternative? Share your techniques in the comments!

Organizing Your Wiki Content - Part 2: Page Hierarchies

2010-03-01T07:29:00.000-05:00

In Part 1 of Organizing Your Wiki Content, we discussed how you can use direct linking to organize your wiki content in a natural way. However, one of the major issues with direct linking is it's static, forcing you to incur overhead to keep the content current. Instead, we'd prefer to organize our content in a dynamic way. Page Hierarchies provide a simple way to do this.

This is the continuation of a series of posts on Organizing Your Wiki Content:
Part 1: Direct Linking
Part 2: Page Hierarchies
Part 3: Labels
Part 4: Fine-Grained Controls
Part 5: Including Content
Part 6: Wrap-up

Page Hierarchies

In Confluence, Pages are separated into page hierarchies as part of a Space. Each page can have many children. This lets you have a natural way to organize your content. Children of the parent page can provide more detail about a specific topic or be organized into a step-by-step process. For example, in the Confluence Documentation, the top page is broken down into User's Guide, an Administrator's Guide, and so on, all accessible from the home page.

Most Confluence themes, including the default theme, leverage page hierarchies in some way by using two Confluence macros, {children} and {pagetree}. The default theme displays the children of a page at the bottom of the content area. The documentation theme displays a pagetree in a panel to the left for the whole space.

(Default Theme - With Children at the Bottom of the Page)

(Documentation Theme - With PageTree on the Left Side)

You're not limited to using these themes to supply this functionality. You can also use these macros directly in your page content.

Pros

The advantage of organizing your content into page hierarchies is that it's fairly natural. When adding a page to the current page, your new page will automatically be a child of that page. This is one of the easier ways for your users to add content as it requires no advanced knowledge of Confluence. Furthermore, you can use the {children} and {pagetree} macros yourself to organize the content in the page. For example, organizing meetings notes or crafting a step-by-step guide.

Finally, one of the biggest advantages of using page hierarchies is that when new child or descendant pages are added, your content is dynamically updated. New child content can be easily discovered from the parent pages.

Cons

There aren't too many cons of using page hierarchies. However, page hierarchies can be a bit limiting. First of all, you can't use page hierarchies to link to pages in other spaces. Also, all children of a parent page will be listed when you use the {children} macro, so this can create some unintended consequences if you wanted to list the steps of a process and have a sibling page that isn't part of that process. Finally, you can only order child pages are a few ways: alphabetically, by creation date, or modified date. This makes things difficult if you have an explicit ordering you'd like to use, in which case, direct linking might be your best bet.

What about more loosely coupled content that doesn't fall into a strict single hierarchy? The next article in the Organizing Your Wiki Content series, Part 3: Labels, will demonstrate how labels can help you.

Do you prefer to use page hierarchies as your general method of organizing wiki content? Share your experiences in the comments.

Organizing Your Wiki Content - Part 1: Direct Linking

2010-02-21T09:45:00.000-05:00

Managing your organization's wiki can be a difficult process. Ideally, you want to ensure that your users are able to find the content they need in a natural way. Additionally, you want to make sure some structure is in place that makes adding content just as easy to foster growth. Confluence offers several different ways to organize your wiki content, each with their own strengths and weaknesses. Let's explore each of these methods.

This is the beginning of a series of posts on Organizing Your Wiki Content:
Part 1: Direct Linking
Part 2: Page Hierarchies
Part 3: Labels
Part 4: Fine-Grained Controls
Part 5: Including Content
Part 6: Wrap-up

Direct Linking

One of the founding principles of the Web is the hyperlink. The hyperlink is what allows us all to navigate through the web, jumping from each bit of content to the next. The hyperlink is what makes Google's PageRank algorithm so powerful for discovering the most relevant content for your search term. Hyperlinks are what add value to blogs, allowing you to reference other material on the web. This blog article is full of them! Hyperlinks are what have made Facebook and Twitter so popular as a form of content sharing. Truly, hyperlinks are what wikis are all about. How many hours have you lost exploring Wikipedia, jumping from one article to the next through links?

So, it's no surprise that the primary way to organize content on your enterprise wiki is by directly linking to additional content. Confluence offers some very easy ways to do this, both through the rich text editor and through wiki markup.

Pros

Direct linking is great because it allows you to explicitly point to the content that's relevant. Even better, Confluence monitors the incoming and outgoing links on your wiki page. If you ever move, rename, or delete the content being linked to, Confluence will update your page automagically. This avoids broken content on your wiki, which can dissuade your users.

Cons

Unfortunately, direct linking isn't without its share of problems. First, direct linking is static. To update, it requires an explicit action on the part of a content creator. If a new piece of content is created that is relevant to an old page, you need to go back to that old page, edit it, and link to the new page. Otherwise, you'll never be able to find the new page directly from the old one. Content discovery is impeded, something we're trying to avoid. Second, if you link to pages that do not exist yet (e.g., you're creating a step-by-step guide and you only get to Step 3 of 8), your users will see unfinished content. If they click on those links, they'll quickly jump into creating a new page, which can be overwhelming for users that don't feel comfortable with creating whole new content instead of just adding to it.

So, we want to organize our content in a dynamic way to avoid the overhead involved in keeping content current. There's several ways to do this.

To find out how, continue on to the next article in the Organizing Your Wiki Content series, Part 2: Page Hierarchies

Do you prefer to directly link to most of your content? Have you figured out a trick for using links that works for you? Share your experiences in the comments.

Welcome to Conflatulence, a Confluence User's In(digest)ion

2010-01-02T20:34:00.004-05:00

The rise of web technologies has inspired new ways to collaborate, not just across the Internet as a whole, but also at the enterprise level. Wikis, web pages that anyone can edit, are a powerful way to manage knowledge across a company and break down communication barriers. One of the more popular pieces of enterprise wiki software is Atlassian Confluence. We use it at my company, and I gotta say, it's fantastic.

I'm Brad Rosenberg, and I'm a Confluence user. Welcome to Conflatulence.

What you'll find at Conflatulence is a collection of my experiences managing Confluence for a group of about 100 techies and non-techies for knowledge management and project collaboration. I'll discuss some of the ideas that keep rattling inside my brain, reflect on Confluence updates and trends, provide tips and tricks I've found to be helpful, and document my forays into Confluence plugin development.

It's my hope that Conflatulence will become a popular resource for other Confluence users and developers. Not only that, but I hope to use Conflatulence as a way to engage with the Confluence community, create lively discussions, and capture inspiring thoughts. So please, join in on the conversation.

Let's get started.