Blog Archives

Confluence 4 editor, wiki markup and XML storage format – tips from an expert

Graham Hannington is a Confluence fundi. He has steeped himself in the new “XHTML-based” storage format, bent the Confluence 4 editor to his will, and resurrected wiki markup in ingenious ways.

Graham has recently started adding his findings to this wiki: Advanced Confluence Tips. Here are the hints he has shared to date:

A huge thanks to Graham, for sharing the results of his indepth investigation and design work!

If you’d like to comment on Graham’s pages, or add some hints of your own, you can sign up for a username on the wiki. It’s free. :)

Brightening up the Australian winter

A Rainbow Lorikeet, encountered on a walk in the bush a week or so ago:

How to convert Confluence XML storage format to wiki markup

Are you looking for a quick, unsupported but still immensely useful way of converting a page, or a small chunk of content, from the new Confluence storage format back to good old wiki markup? The new XML storage format is used in Confluence 4. Wiki markup is used in Confluence 3 and is still required in parts of Confluence 4. Graham Hannington has created a web page that does the conversion for you. His tool is called the Wikifier. Just paste in the Confluence storage format XML on the left, and see the wiki markup appear on the right immediately.

I’m busy documenting the wiki markup and storage format for all the Confluence macros. Graham’s Wikifier is proving very useful indeed, so I thought I’d tell you about it. This is what it looks like, processing the much-beloved Cheese macro:

Graham provides other resources, including an XML schema for the Confluence storage format, and associated documentation: Graham’s Confluence resources page.

One use case – converting a page to a template

One problem with Confluence 4.0, 4.1 and 4.2 is that page templates must be written in wiki markup. They do not yet support the new rich text format used by the new editor. If you have developed a page and want to convert it to a template, you’re stuck, because the content of a page is no longer available as wiki markup.

To get round this problem:

  • View the storage format for the page that you want to use as a template.  How? The “View Storage Format” option appears in the “Tools” menu. It is available to Confluence system administrators, and to people who have permission to use the Confluence Source Editor, which is available as a plugin.
  • Copy the storage format of the page’s content, paste it into Graham’s Wikifier, and grab the wiki markup.
  • Use the wiki markup to create your page template in Confluence.

Caveats

See Graham’s comment announcing the Wikifier.

An extract from that comment:

What Wikifier is, and is not

Wikifier is a minimal test harness for an XSLT stylesheet I have developed that converts Confluence XML to wiki markup.

The XSLT stylesheet is by no means complete. I welcome your feedback. If Wikifier does not correctly convert some Confluence XML, please let me know (if you like, use the Contact mailto link on Wikifier), and I will do what I can (no promises, though).

Wikifier is not a replacement for the Confluence 3 wiki markup editor view.

Wikifier is only a test harness; it is not intended to be a fully fledged application.

I hope this is as useful to you as it is to me. :)

Updating documentation on a Bitbucket wiki

Bitbucket is a code hosting service. People sign up for an online repository, then share and contribute code using either Mercurial or Git. (Both are DVCSes, or distributed version control systems). When you get your repo, you also get a wiki. This week, I needed to update some documentation that was hosted on a Bitbucket wiki. It was fun! Here’s how it went.

As far as Bitbucket is concerned, a wiki is just another repository. I needed to update the wiki for Charles Miller’s Confluence JSON-RPC API plugin:
https://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki/Home
Bitbucket supports both Mercurial and Git. In this case, the repository uses Mercurial (hg).

I have used Bitbucket before, so I had already installed Mercurial and set up my configuration file. (The Bitbucket 101 guide explains how to do that.)

So all I needed to do was:

  • Get a copy of the wiki documentation, by cloning the Bitbucket wiki repository.
  • Make the updates in my local copy.
  • Push the updates up to the online repository in Bitbucket.

The details

I’m using a Windows computer. These are the steps I followed.

1) Create a directory on my computer where I want to store the Bitbucket repository. This is what I called the directory:

C:\Atlassian\BitbucketRepos\JSON-RPC-docs

2) Open a Windows command window and go to the new directory:

cd \atlassian\bitbucketrepos\json-rpc-docs

3) Enter a Mercurial command to clone the Bitbucket repository that contains the documentation. This puts a copy of the repo onto my computer:

hg clone http://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki

Here’s what it looked like in my command window:

C:\Atlassian\BitbucketRepos\JSON-RPC-docs>hg clone http://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
real URL is https://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
destination directory: wiki
requesting all changes
adding changesets
adding manifests
adding file changes
added 13 changesets with 13 changes to 2 files
updating to branch default
2 files updated, 0 files merged, 0 files removed, 0 files unresolved

4) Open a text editor and edit the file that contains the wiki page I need to change.

The wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.

This is what my directory looks like in Windows Explorer, with the “Home.wiki” file open in Notepad++

The directory structure of the cloned wiki repository on my Windows computer

5) Make my changes to the text file.

Yaayyy! Wiki markup. It’s slightly different to the Confluence wiki markup that I’m used to. Bitbucket uses the Creole syntax.

This was a bit unnerving, because there is no preview in a text editor. I was facing the prospect of pushing the file to Bitbucket before I knew what it would look like.

Then I found this site, where you can enter Creole markup and see a live preview:
http://www.meatballsociety.org/Creole/0.4/

Magic! I pasted in the content of my updated file and checked the results. All good.

6) Save the text file.

7) In my command window, go to the directory that contains my Mercurial repository. In this case, it’s the “wiki” directory:

cd wiki

8 ) Commit the changes to my local Mercurial repository, including a commit message:

hg commit -m “Linked to the documentation on the Atlassian Developers site for full instructions”

9) Push the changes to the online repository at Bitbucket:

hg push

It worked! Here is what I saw in my command window:

C:\Atlassian\BitbucketRepos\JSON-RPC-docs\wiki>hg push
real URL is https://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
pushing to http://bitbucket.org/cmiller_atlassian/confluence-json-rpc-plugin/wiki
searching for changes
http authorization required
realm: Bitbucket.org HTTP
user: sarahmaddox
password:
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 2 changes to 2 files

Here is the wiki page before my updates:

The Bitbucket wiki page before my updates

And after:

The wiki page after I had pushed my updates to Bitbucket

Here is the page history:

The page history

And yes, to the eagle eyed who spotted the number of files updated, I did update another wiki page at the same time. ;)

Here is the Bitbucket documentation on how to use the wiki.

Cops, crims and Confluence 4.0 change management

Atlassian has just released Confluence 4.0, a major update to the wiki software. The highlight of this release is a smart new all-in-one editor. It replaces the two editors available in earlier versions of the wiki. Now, as you would guess, the editor is the heart of the wiki. When the editor changes, the world changes. ;) That’s true if you spend all of your day on the wiki, as I do. How can we make sure it’s not a world-shattering change for people when they get the new Confluence? Technical writers and change management to the rescue!

Imagine this: You walk into the office on Monday morning, twitching your eyebrows in a vain attempt to get your eyes wide enough open to see the computer screen. The calendar pops up. Yikes, there’s that meeting in 10 minutes and the wiki page is not quite ready yet. Gulp a mouthful of strong hot Java. Fire up the trusty wiki. Click the edit button. What the…!??!! Someone’s changed the wiki. No more wiki markup editor. No more rich text editor. Your brain breaks up into little chunks and skitters away across the universe. Its last cohesive thought is, Why was there no warning of this change?

Luckily, the above paragraph is fiction. :)  The Confluence technical writers have spent quite a bit of time on some change management material, aimed at helping people prepare for the new editor. This post is about technical communication and change management. It’s also a bit about Confluence 4.0. ;)

The Confluence 4.0 change management guide

The front page of the change management guide is here: Planning for Confluence 4.0. It summarises the change management guides available for each type of audience: administrators, developers, and other wiki users.

The guides cover a number of aspects of Confluence 4. To help people get up and running fast with the new editor in particular, we have created some quick reference guides:

We published the Confluence 4.0 Editor FAQ quite some time back, to give people a place to ask questions and a page to watch for news and updates. It’s been very interesting to see the feedback from everyone. The product managers, developers and QA engineers have been kept quite busy responding to questions and suggestions, as you can see from the comments on that page.

A quick note to wiki markup fans

Take heart. Wiki markup never dies!

Aims of the change management guides

The guides are designed for business users, and primarily for managers and team leaders who will need to train their staff and update their in-house procedural documentation.

When an organisation decides to upgrade its Confluence site to Confluence 4.0, the change management team can make use of our guides to let the wiki users know what’s about to happen. They can prepare training material and quick reference guides based on the material we’ve created.

A story of cops and crims

Where did the idea for the change management guides come from? Back in May 2010, I wrote a blog post on our internal wiki suggesting the need for this sort of documentation at major software releases such as Confluence 4 looked like becoming. As an illustration, I told this story:

A while ago I worked as technical writer for the New South Wales Police, during the time when the NSW Local Court Reform Act was passed. The new Act affected the way policemen arrested people, processed the arrest in the police stations, took fingerprints, entered information onto the police computer system (called “COPS” of course), held the suspect in the holding cells, took them to court and handled bail. In fact, it changed just about everything related to arrests and court procedures.

My role was pretty interesting. I had to document the changes to COPS (a green-screen mainframe system!) as well as do the change management for the local bobby on the beat. I designed posters that were to be stuck up on the walls of police stations around the state, quick-reference cards for court officers, and in-depth procedures for the guys who processed the arrest and holding of the suspect. I wandered around the depths of the Kings Cross police station (an education in itself) and watched people reporting for bail.

It was a revelation to see how the change affected people who were just trying to do their day job and now had to deal with a totally changed computer system too.

That blog post was over a year ago. Since that time, we’ve been planning and working on the Confluence 4.0 change management guides.

A new editor? Could do it with me eyes closed, mate!

Cops, crims and Confluence 4 change management

I can haz read teh docs. No wurriz, she'll beh right.

I snapped this photograph at the Sydney Wildlife World last week. It’s a real koala, not a toy. Promise! Its less than elegant scientific name is Phascolarctos cinereus.

I’m excited about this new direction in the documentation. I hope many organisations and many people will find the change management guides useful! I also wonder how many other technical writers focus on change management as well as straight “how to” guides. Let me know if you’ve been doing something similar.

A bit of marketing fun

The marketing team have also been busy. Last week they published a neat, cheeky infographic placing the wiki in the world’s communication timeline: Communication through the ages. There is also a web page, published today, with an excellent overview of the new features in Confluence 4.0.

Follow

Get every new post delivered to your Inbox.

Join 1,454 other followers

%d bloggers like this: