Atlassian Confluence blogs atWikiConsulting.com

In this final part of my series on Atlassian Agile Process I wrap up and reveal XP's fundamental weakness. Oh and I cover socoipaths! And Ninjas. But no pirates. See also Part 1, Part 2 and Part 3.

Some Other XP Practices

Let me get the rest of XP out of the way. Sustainable Work Hours, Collective Code Ownership and Metaphor are XP practices we don't give much thought to. The first two we embrace completely and the third we pretty much ignore. Then again, Bamboo has a metaphor: Telemetry. Perhaps Metaphor is more important towards the beginning of a system's life.

Extra Practices

The following essential practices for our process are not defined in XP:

Specifications

Purists and detractors mistakenly think specifications are in conflict with XP ideals. We aim for our specifications to be both minimal and complete. Which is a blend of just enough documentation and turning the knobs to eleven (for that extra push over the cliff). They are written in Confluence to a template with a checklist for the dozens of essential aspects to a new feature. The checklist includes things like security, user interface design, caching, remote APIs etc. From the spec comes a stack of task cards.

Training

Alternating fortnightly with the process improvement meeting I mentioned in Part 1 the JIRA team has an hour for internal training. Confluence has a similar regime. Cross-team involvement is growing. In addition to team-internal technical talks, Atlassian has recently started larger cross-team developer training events. For example last week we were treated to one on GWT by the dynamic duo, Bruce Johnson and Joel Webber who were in town at Google Sydney. Increasingly training goes on outside the software process.

Hiring

Hiring, I think, should be a specified part of any development process. It's something I've been involved with for a long time and something I've learned about through making mistakes. Hiring also has a huge impact on your process.

Our agile process requires people to spend the effort to listen and talk to each other, working closely. You have to be a people person to like it. It doesn't suit sociopaths. Accidently hiring a sociopath is going to make XP impossible. Trust me, I know. To me this is XP's fundamental weakness. Of course if you only hire ninjas, you probably don't need much formal process. Ninjas just do what needs to be done.

Hiring great people is something we take very seriously at Atlassian and we try to make it quick and effective. Our interviewers are busy developers and our favourite candidates are going to get other offers. The hiring process involves screening, phone and face to face technical interviews and a coding test. We are conservative. We would rather err on the side of not hiring someone. Of course the problem is Ninjas are very hard to find.

We also do a lot of things to keep people happy once we have hired them. We have an awesome work environment and excellent tools. We are also hiring right now! Sociopaths need not apply.

• Comments Off

Or, an exploration of Javascript numeric types.

The Problem

Agnes called me over because she'd spent the last two hours banging her head against CONF-10035. Apparently, when editing a particular page on the Atlassian extranet, going to preview mode caused all the images and links on the page to be broken links. When the page was saved, though, everything worked fine.

Diagnosis

One of the advantages of being the Architect is that by the time you're called in to help with a problem, someone else has already done the important but boring parts of trouble-shooting. Agnes had already copied the page and all its attachments to her test environment, and was unable to reproduce the bug locally.

So I started thinking to myself. "It's got to be something weird, or Agnes would have worked it out already. What's different between the test environment and the extranet?"

A Digression

Confluence's database objects are all identified by a 64 bit primary key. This was a piece of deliberate overkill that comes down to never, ever wanting to have one of those "we thought 640k was enough!" moments as we explained to some fifteen-year Confluence customer that they just couldn't fit any more content into their server.

Sane Confluence servers are unlikely to ever make use of all that key-space, but it's good to have a ludicrously large buffer to play with. On the other hand, when the Great Bit Shortage of 2020 hits, Confluence will have to put up its hand as one of the culprits.

The Atlassian extranet has been running since the earliest days of Confluence development. It has been afflicted with every piece of dodgy alpha code we've felt like deploying. Extranet has never been a sane Confluence server. Some time in the depths of history, some bug crept in that bumped the database keys up well above the 32 bit limit, and there they have stayed ever since.

Back to the Problem

This bit of extranet quirkiness has turned out to be quite useful, as it has uncovered a number of bugs over time caused by people forgetting that a contentId won't fit into an int, especially in places where Java's static typing doesn't rescue you from mistakes. Places like the remote API, or Javascript.

Javascript has one numeric type, and according to the standard, it's represented internally as a 64-bit IEEE-754 floating point number, or what Java would call a double. As anyone who has worked with floating-point arithmetic on computers will know, such numbers are only approximate. According to the comp.lang.javascript FAQ, integers in Javascript start to lose accuracy when they go above 9x1015.

So practically, this means that at some point, the database IDs assigned by Confluence can get high enough that they can no longer be represented accurately as a number in a Javascript. So, as was the case in CONF-10035, the page had Content ID '69518087748071312', but when you clicked on "preview" it was being sent back to the server as '69518087748071310'.

(To add to the confusion, Opera handles this number fine, as does Java when you convert between the long and double types)

But That's Not All

Normally, this wouldn't be so much of a problem. We found this out ages ago, and have since made sure that all our Javascript APIs pass content IDs around as strings. The complication, though, is that Javascript is weakly typed¹. Which means that if you accidentally type...

var contentId = #if ($pageId.toString() == '0') $draft.id #else $pageId #end;

...instead of...

var contentId = #if ($pageId.toString() == '0') "$draft.id" #else "$pageId" #end;

...Javascript will happily treat the variable as a number or as a string, depending on how you decide to use it. And neither of them will be the number you thought of in the first place.

Epilogue

I think my favourite kind of problems are the ones that take hours to find, and one line of code to fix. There's something very satisfying about it.

A man's car has been making a very scary grinding-metal noise, so he takes it to the garage. The mechanic walks over, pops the hood, revs the engine a few times, and scratches his chin. Then he walks over to his work-bench and picks up a small rubber mallet. He gives something in the engine a hard whack, and suddenly the grinding noise has gone completely.

The mechanic walks over to the driver. "That'll be a hundred and twenty bucks, thanks."

"You've got to be kidding! All you did was hit it with a hammer! I'm not paying."

The mechanic walks back to his bench, grabs a pad and pen, and writes the driver an invoice:

Hitting the engine with a hammer: $0.05
Knowing where to hit it: $119.95

¹ Dive into Python has a good summary of the difference between Strong/Weak typing and Static/Dynamic typing, although I'd phrase it differently.

• Comments Off

Mylyn is a wonderful Eclipse plugin focused on helping you work more effectively by connecting the IDE to the issue tracker. As their web-site says, Mylyn "reduces information overload and makes multi-tasking easy... by making tasks a first class part of Eclipse, and integrating rich and offline editing for repositories such as Bugzilla, Trac, and JIRA."

Mylyn brings JIRA right inside your IDE. You can view your whole list of assigned issues in JIRA. If you tell Mylyn which issue your working on, it will remember everything you do in conjunction with that issue. It begins to hide away all the extraneous stuff that does matter right now, allowing you to focus on what does.

If you need to change tasks, just let Mylyn know and it will save your context. When you're ready to come back, Mylyn will bring back all of the files, views and and jobs associated with your task, letting you pick up right where you left off.

What's more, Mylyn provides the ability to edit and comment on JIRA issues right from the IDE, whether you are online or offline. Mylyn handles syncing up any changes you make to JIRA when you come back online.

Take a look at the screenshot that illustrates all of this:

1. In the left pane, the Package Explorer is showing only the subset of the system related to the
   active task, called the task context. This helps reduce information
   overload and makes multitasking a single-click operations.


2. In the middle pane, the rich editor for JIRA issues supports instant open, offline access and
   editing, drag-and-drop attachment, task context sharing, and hyperlinking to
   source code and issues. This helps you code in a task-focused way without
   breaking your workflow.


3. In the left pane, the Task List integrates filters and highlights incoming changes. This
   allows you to de-clutter your inbox from email notifications.


4. Mylyn automatically groups incoming and outgoing changes by task and
   links commit comments to issues. This facilitates committing and tracking
   changes.

You can learn more about all these features at:

• http://www.ibm.com/developerworks/java/library/j-mylyn1/
• http://www.ibm.com/developerworks/java/library/j-mylyn2/

Atlassian has been working with the Tasktop team for the last few months to improve the integration between Mylyn and JIRA, and you can now download and install the Mylyn/JIRA connector for Eclipse here. The Mylyn 2.2 release is scheduled for December 19th and will include additional improvements to the JIRA Connector. To help us prioritize work for 2.2 and future releases, please let us know what you think!"

• Comments Off

Developers are funny:

http://jira.atlassian.com/browse/CONF-10000

• Comments Off

I've been at Atlassian for a month now, and it's time to admit that I never really got the whole wiki thing. (This is something I'm glad I didn't have to own up to during my interviews.)

Until now.

Before starting with Atlassian, I thought that Wikipedia was the only real world wiki. But apparently, Wikipedia is not the real world. I thought collaboration was something I was across — I was one of the more prolific users of the Sharepoint site at my old job. My family use a Drupal site to blog, even if the average time between posts is measured in months, rather than days.

But a wiki as a enterprise tool? Spontaneous collaboration? People going to the wiki rather than asking to be emailed? I wasn't skeptical, just unable to imagine how it could work.

Now, after four weeks of wikiing-the-Atlassian-way, I'm in danger of becoming a wiki fangirl.

What convinced me? Four days into my job, I needed to share some information with the other Internal Systems people. I assumed I'd be sending an email — the big decision was whether to write what I wanted in the body or attach a document. Neither felt very Atlassian-y. But then, I had an ah-ha moment — I could add a page to the wiki!

Plus:

• I needed a license key for IntelliJ IDEA. It's on the wiki.
• Every time I've searched for something, what I was looking for was in the first three search results.
• I haven't had to convene a meeting to get comments/updates to something I've written.
• Directing someone to the wiki is much faster than attaching a document to an email — think of all that extra free time I have!

Now, some of these are part of Atlassian's culture, rather than just because we use a wiki. But I also think most of them are due to the important paradigm shift of thinking about knowledge management rather than document management.

For whatever reason, it rocks. I love things being this easy. I love getting (almost) zero emails with attachments. I love not having a hard drive full of Word documents.

As for all the extra free time I have, from not attaching documents to emails? I spend it reading the internal Atlassian blogs. Which are also part of our wiki!

• Comments Off

A few days ago we introduced the newest Atlassian offering, JIRA Studio. JIRA Studio combines JIRA, Confluence, Subversion, FishEye, and Crucible in a single integrated development suite. While it's not yet quite ready for prime time, we're plugging away at it and as we continue to refine features, we'll be blogging them here.

One of the crucial features of JIRA Studio is linking. Linking is a big part of what makes five separate applications a suite. From anywhere in the suite, you should be able to easily insert a link to an association in one of the other applications. For example, you should be able to link to a JIRA issue anywhere from FishEye or Confluence simply by inserting the issue key. Or link to a Confluence page from JIRA without manually entering the page url.

Linking is made possible by the AppLinks plugin, a new plugin developed to facilitate intelligent integration of Atlassian applications. The AppLinks plugin allows you to set global and project-level associations between the applications, so that for any given JIRA project, for example, the related Confluence instance and space are defined. When creating a new Studio project, a new wiki space, JIRA project, and code repository are also created and linked.

Once these links are defined, any number of integrations become possible. We can modify existing plugins (for example, the JIRA Fisheye plugin) to be aware of the AppLinks plugin (meaning that you would no longer need to manually configure the plugin with the url of the associated instance, it would just know). We can create new plugins which take advantage of the aggregation allowed by this linking, and we can base suite-wide navigation on awareness of the associations.

While JIRA Studio is a hosted solution, the AppLinks plugin is a good example of a benefit for all our customers, hosted or install. The plugin will be available for download once its complete, and if you are running multiple Atlassian applications, you will be able to take advantage of it.

In order to enable linking, we needed to agree on a consistent link syntax. This syntax permeates the suite; entering a JIRA key should be the same no matter which application you're in. We eventually settled on this syntax:

• Issue Key = Project Key-number (eg. CONF-9024)
• Changeset Number = revision:changeset# (eg.revision:4572)
• SVN = source:file_name (eg. source:dashboard.action)
• Confluence = [space_key:page] (eg. [DOC:home])
• Crucible: review:XXX (eg. review:38956)

If you've used our applications, you'll recognise much of this syntax. All we've done is extend it throughout the suite. As with anything, there's a bit of a learning curve while you grow accustomed to using the links, but once you do, their value is enormous: being able to easily click to the associated code or wiki specification for a bug report, for example, can take hours off your development time and make de-bugging much less painful.

There will be plenty more to come regarding JIRA Studio. If you're interested in learning more or signing up for the Beta, please go check out jira.com.

• Comments Off

Featuring Chris Owen, senior Confluence developer:

• Comments Off

Developers really do have a language of their own, one which can be hard for non-developers to decipher. A terse sentence fired over IM can communicate reams of information.

"It's a kludge, but put the tuple from the database in the cache."

The problem is — as this video shows — even developers themselves can have a hard time understanding each other.

• Comments Off

Andrew McAfee recently wrote a post called How to Hit the Enterprise 2.0 Bullseye that looks at how multiple tools like wikis, blogs, and social networks are useful to workers in complementary ways. He defines a bullseye and set of concentric cirles that represent the typical worker's ties to others as strong, weak, potential, and none, then shows how each tool is most useful at a particular ring in the bullseye. For example:

"Evidence suggests that wikis let strongly-tied collaborators get their work done better, faster, and with more agility than was previous possible. With a wiki, what’s emergent is the document itself, with ‘document’ defined broadly."

For weak connections, he explains that the benefit of maintaining a social network is keeping updated on connections and being able to see when the potential for a stronger connection emerges. He gives the exmple of a Facebok status update that let him know a contact was accompanying a foreign head of state to a meeting on technology issues.

"...as a result of his Facebook update, which took him about ten seconds to type and me one second to read, I now know who to reach out to should I ever want to dive into European IT issues, or desire an invitation to the Elysee Palace . SNS lets its users build bridges to new human networks, and to let non-redundant information emerge."

For the potential connections — the outer ring in the concentric circle — he suggests blogs:

"And what about all the people in the third ring of the circle in the figure — the potentially valuable colleagues who our knowledge worker just hasn’t met yet? Wikis and SNS in their current configurations don’t help her learn of the existence of such people, but an internal corporate blogosphere could."

If a critical mass of blogging is cultivated in an organization, it creates an information flow for people to tap into by setting up searches for topics of interest, then monitoring RSS feeds of blogs they find useful.

There are multiple ways to use wikis, blogs, and social networks to be better informed, share your knowledge and expertise, and find others who share your interests. Regardless of how you use them — and it's to your benefit to investigate them and find the uses that suit you — Andrew has offered an excellent rationale for their value.

• Comments Off

Out of the box, Confluence is beaut. Add a plugin or two, and your documents glow. So which plugins do we use in the Atlassian product documentation?

Here at Atlassian, we use a wiki for almost all our product documentation. On our Confluence site, you'll find user guides, administration guides and other technical documentation for Bamboo, Clover, Crowd, Crucible, FishEye and of course for Confluence itself.

* Quick quiz: Which product is missing? Answer is at the bottom of this blog.

To add extra structure and style to our documentation, we use the macros provided by some Confluence plugins. We limit ourselves to just a few plugins, because we're aware that many customers download our documentation in XML format and upload it into their own Confluence installations. And they don't necessarily have the same plugins installed as we do.

Giving it some structure

The question we're asked most often is this:

How do you get that dynamic table of contents in the left-hand panel?

We've inserted the pagetree and pagetreesearch macros into the page layout for most of the documentation spaces. You can find some guidelines here. Below is an example. (Click the image to open an expanded view, and click the link below the image to go to the documentation page itself.)

Example 1
View the real page.

The {pagetree} macro generates the table of contents on the left. It shows the pages in the space, starting from a given level in the page hierarchy.

We use {pagetreesearch} to confine the search results to a space, or even a lower-down hierarchy of pages. This is great when you have a large Confluence instance, where the search results can be a bit overwhelming.

The toc macro (see example 2 below) generates a table of contents from the headings on a single page. You can limit it to show only a given level of headings. In our release notes, we've used {toc:minLevel=2|maxLevel=2}. So we can use the 'h1' level of heading as a section break, without it appearing in the table of contents. In the example below, 'Highlights of Confluence 2.6' is a level-1 heading and 'Fresh look for the Default theme' is the first of the level-2 headings.

Example 2
View the real page.

To show 'related topics' and mini tables of contents, we use the children macro (not illustrated here) and the contentbylabel macro (see example 3 below). We find the {children} macro useful for a carefully-structured hierarchy of documents, whereas {contentbylabel} is handy for a more loosely-associated set of pages such as FAQs and 'related topics'.

Example 3
View the real page.

To repeat information on more than one page, such as introductions and overviews, try excerpt-include and include. (Not illustrated here.)

Making it look good

Confluence allows you to upload and display ready-made images and photographs. In addition, you can create and edit images and diagrams within Confluence itself, using the Gliffy plugin. Here's an example:

Example 4
View the real page.

To make a note stand out from the rest of the page, we've enclosed it in a panel and made it float to the right of the page. See example 5 below. The {float} macro is part of the Composition plugin.

Example 5
View the real page.

The section and column macros give our pages some structural style. You can see them in action in examples 1 and 2 above. For other pretty layout effects and emphasis, try note, warning, tip (see example 3 above) and info. To preserve formatting in code and other extracts, we use code and noformat. (Not illustrated here.)

Archiving documents and managing releases

We provide a separate set of documentation for each major release of a product. For example, the current Bamboo space contains documentation relating to the most recent Bamboo release. And there is an archive space for Bamboo 1.1.

To create the archive copies of the spaces, we use the Copy Space plugin (still in a beta release).

More about macros and plugins

• Plugins are add-ons to Confluence. Some plugins are pre-installed in Confluence. Your Confluence administrator can decide whether to install others.
• A plugin may allow you to use one or more macros on your Confluence pages. (More about using macros).
• Take a look at the full list of Confluence plugins and the documentation for each of them.
• To see which macros a plugin contains, administrators can go to the Plugin Repository on your Confluence instance and click the plus sign under the plugin name. The Plugin Repository page will also tell you whether the plugin is installed on your version of Confluence.
• Not all plugins are officially supported by Atlassian. Refer to each plugin's documentation page in the plugin list for information about its status. The macros shipped with Confluence are listed in the Confluence User Guide.
• Tip: To see the macros and other markup which generates a specific wiki page, go the 'Info' tab of the page and click the 'View Source' link near the top right of the tab.

* Answer to the quick quiz: JIRA, of course. The JIRA documentation is housed in Apache Forrest at the moment. We plan to move the documentation to the wiki soon.