The book is all about using a wiki for technical communication. It’s called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinare for technical communication. It will be published in February by Richard Hamilton at XML Press.

The book cover

I love the illustrations in the book, and especially the picture on the cover. They are the work of a talented artist named Ryan Maddox.

Who is the girl on the cover?

She is the hero of the book. She is a technical communicator extraordinaire. Let’s dub her X for now. When you read the book, you will follow X as she sets up a Confluence wiki and adds a technical documentation space. Learn from her expertise with the wiki editor and macros. Share her adventures in agile development and search engine optimisation. Grow wings, as X does, and make your wiki documentation fly. Discover why X says we need a “kiss my wiki” attitude.

Guess her name – one guess per comment, guess as often as you like

What is X’s real name? Add your guesses as comments on this blog post. It’s just her first name, one word, that you’re looking for. You can add as many comments as you like, and write whatever you like in the comment, but please put only one suggested name per comment.

The first person to get it right wins a free copy of the book. You can choose whether you want a printed book (paperback), a Kindle version or an EPUB version.

If no-one has guessed the right name in the next few days, I’ll add a hint.

Let the fun begin.

Another chance to win

Here’s another opportunity to win a free copy of the book: Head on over to XML Press and sign up for email notification about the book. Your name will be automatically entered into a draw for a free copy.

Hint: Think chocolate

Here’s a clue: Our hero’s name has something to do with chocolate.

Keep guessing. I’ll add another clue soon!

(Hint added on Sunday 15 January, early morning Sydney time.)

We have a winner!

The name of the girl on the cover is…  Ganache. Congratulations to Jill Brockmann on guessing the name and winning a free copy of the book!

So, Ganache is the name of our our technical communicator extraordinaire. But this may be the first time ever that the word is used as a person’s or character’s name. Ganache is also a mixture of chocolate and cream, used to fill chocolates or cakes. People often add a flavour to the mixture, such as chopped raspberries to make a raspberry ganache.

Thank you to everyone for taking part. I hope you’ve had as much fun as I have!

(Winner announced on Sunday 15 January, 6pm Sydney time.)

Our development team has built a tool that documents an application’s REST APIs within the application itself. What’s more, you can test the REST resources and methods too. All from the application’s user interface. Now, that’s embedded help for nerds. I’m writing this post because I think many technical writers and developers will be interested in this solution. It may trigger ideas about adding something similar to other applications too.

The tool is called the REST API Browser, and it is implemented as a plugin. At the moment, it is available only within the Atlassian Plugin SDK. In the future, you may be able to download the REST API Browser as a separate plugin and install it into any Atlassian application.

So, what does the REST API Browser do, what is the Atlassian Plugin SDK, and how can you get the REST API Browser to work within an Atlassian application?

Overview of the REST API Browser

This is what the REST API Browser looks like, when running inside an application called JIRA:

The /user/search REST resource in JIRA

JIRA is an issue tracker developed by Atlassian. The above screenshot shows one of the JIRA administration screens, part of the application’s user interface. I’m running JIRA on my local machine, in plugin development mode. The REST API Browser is available as one of the options on the application’s administration screens. It’s as simple as that.

In the screenshot, you can see the resources in the JIRA REST API, starting at the /user/search resource. For each resource, the REST API Browser shows the methods (GET, POST, PUT) and the parameters available.

You can even do real-time testing of the APIs, by submitting a request and seeing the response. In the screenshot below, I have run a GET request using the /user/search resource, asking for details of username “admin”. You can see:

• A form, prompting you for the parameters relevant to the resource and method. In this case, the only parameter is the username.
• The request, as formulated by the REST API Browser.
• The response headers.
• The JSON in the response body.

A REST request and response

The application’s REST APIs at your fingertips!

Which REST APIs does the Browser show?

The REST API Browser displays all the REST and JSON-RPC APIs available in the running installation of the application. That means all the remote APIs that are part of the application’s default installation (JIRA, in this case) as well as any additional REST APIs provided by a plugin.

So, if you install a plugin into JIRA, and that plugin exposes a REST API, the resources will show up in the REST API Browser too. Magic.

Introduction to Atlassian Plugin SDK

The Atlassian Plugin SDK is a tool for developers who want to create a plugin (add-on) for an Atlassian application. For example, you may want to add a new option to the Confluence page menu, showing all authors who have ever updated the current page. Or you may want to add a new option in JIRA that points to your organization’s intranet site.

But the SDK is useful even for people who don’t want to build a plugin. You can use the SDK to download and run an Atlassian application on your own machine, in plugin developer mode. One of the features that you get is the REST API Browser.

How can you get hold of such sweetness?

Here’s a quick start guide. First, install the SDK and use it to download and run your application:

1. Follow the guide to installing the Atlassian Plugin SDK. Do just steps 1, 2 and 3. You can skip the last step, which sets up an IDE (Eclipse, IDEA or NetBeans), if you do not need a development environment.
2. Create a directory in your file system to store the application executables. Let’s assume you want to run the REST API Browser in JIRA. Then, for example, you could create a directory called myjira.
3. Open a command window.
4. Go to the new directory that you just created, myjira.
5. Run atlas-run-standalone --product APPLICATION. For example, atlas-run-standalone --product jira.
   Note: There are two dashes in front of the word product.

After following the above steps, you will have the application running on your computer. When all the downloads and installation are complete (which may take a while), you will see a message in your command window that includes the URL for the local installation of the application.

For JIRA, the message will look something like this:

[INFO] jira started successfully in 174s at http://localhost:2990/jira
[INFO] Type CTRL-D to shutdown gracefully
[INFO] Type CTRL-C to exit

Now you can access the application in your browser and use the REST API Browser from the application user interface:

1. Go to your web browser and enter the URL given for your application. For example, http://localhost:2990/jira.
2. Enter the username and password: admin / admin.
3. Go to the application’s administration screen. For example, in JIRA: Click Administration at top right of the screen.
4. Click REST API Browser on the administration screen.
5. Choose an API from the dropdown list at the top left of the screen.
6. Choose a resource from the list on the left of the screen.
7. See the methods (GET, POST, PUT, etc) and the parameters available for that resource.
8. To test the resource, enter the parameter values as prompted then click Execute.

The documentation has the details of running the REST API Browser in the SDK, and of viewing and testing the resources.

Getting technical: How the REST API Browser works

The source code is available on Bitbucket, as part of the Atlassian Developer Toolbox. The developer’s guide describes how to ensure that a REST API is included in the Remote API Browser. That document also gives a summary of how the browser is put together.

Pretty neat, huh

From a plugin developer’s point of view, the REST API Browser is very useful. From a technical writer’s point of view, I think it’s pretty revolutionary. Has anyone seen other examples of embedded REST API documentation?

Kudos to Rich Manalang and the Atlassian developer relations team for developing this shiny tool. Here is the blog post in which Rich announced it: Introducing the REST API Browser and the Atlassian Developer Toolbox.

I’m a technical writer at a company called Atlassian. We write all our product documentation on a wiki. For example, here is the Confluence user’s guide. What’s more, we have configured the wiki permissions to allow anyone to add comments to the pages. (We also allow known contributors to update the pages – but that’s another story.) Every now and then, the question comes up for debate again: Is it a good thing to allow comments on the pages? Up to now, we have decided each time to keep the comments. (Well, except for the developer documentation. More below.)

Multi-faceted question

We could rephrase the question like this:

Should we ask for feedback on the documentation? If so, are comments the best way of getting that feedback?

Or like this:

Should we allow everyone to comment on the documentation, or just known people?

Or:

What benefits do our customers get from being able to add and read comments on the documentation?

Or:

What benefits do we, as technical writers, get from the comments people add? And do we suffer any pain?

Mmmm…

What  benefits does the organization get from allowing people to add comments to the documentation?

And so on.

Examples of comments

On the Atlassian product documentation, we allow everyone to add comments. Even people who have not logged in to the wiki – their comments  are recorded as “anonymous”.

Some comments are very relevant to the documentation itself. For example, the comments on this page about supported platforms in the Confluence administrator’s guide:

Some of the comments on the supported platforms page

Other comments can be requests for help, or suggestions for new features or improvements in the product. Often a reader will add some information that will be useful to other readers. This one is on the page about configuring Tomcat’s URI encoding:

A reader offers information to others

Advantages of allowing comments

A quick list:

• People tell us about errors or gaps in the documentation.
• People use the documentation as a tool to help each other.
• We learn about new ways that people are using our products, and sometimes even about new ways that they want to use the documentation.
• The documentation becomes an active hub of interesting information. Readers receive notifications when other people add comments, and so keep coming back to the documentation to see the latest. The documentation sticks in their minds as a good place to find what they need.

Disadvantages of allowing comments

Another quick list:

• Comments can make a page hard to read, if there are too many of them.
• People may add worthless comments, spam, or even nuisance comments.
• It is time-consuming, if not impossible, to respond to all the comments.
• It is time-consuming, if not impossible, to clean up the comments when they are no longer needed. (But we could automate this.)

Please add a comment to this blog post, telling me what I’ve missed in these two lists.

No more comments on the developer documentation

A few months ago, we moved all of the developer documentation to a different wiki, the Atlassian Developers site. By “developer documentation”, I mean the API reference guides, the plugin development tutorials, and all the stuff related to developing add-ons and extensions for our products.

The developer documentation is still on a wiki. In fact, it’s a Confluence wiki just like the product documentation. But we have customised the look and feel, and added some plugins. The thing to note, from the point of view of this post, is that we have turned off the page comments. Instead, there are two panels at the bottom of each page:

Atlassian Answers and feedback panels

The “Atlassian Answers” panel shows a list of posts drawn from a discussion forum called Atlassian Answers. The panel is supplied by a plugin for the wiki that hosts the documentation. The plugin matches the labels on the documentation pages to the tags on the discussion forum. The matching process is not perfect. In particular, labels and tags are not the most reliable way of matching content from a discussion forum and a documentation site. We plan to improve this, by a smarter matching of page titles and content.

The “feedback” panel is supplied by another plugin. When a person clicks “Yes”, “Somewhat” or “No”, a dialog appears where they can give us more information. The plugin posts an email containing that feedback, which in turn triggers the creation of an issue on our JIRA issue tracker. The technical writers and developer relations team can then assess and react to the feedback.

Comparing comments and feedback forms

An advantage of comments over feedback forms is that readers can see and respond to each other’s comments. People can benefit from the advice of other readers. They can hold a conversation and help each other solve problems, quite independently of the documentation authors.

Comparing comments and discussion forums

An advantage that comments have over discussion forums is that the comments are right there on the relevant page. People do not need to go looking for them on a separate discussion site. The information in the comments complements what is on the page.

On the other hand, a discussion forum is in itself a repository of information. I guess, as a technical writer, I’d like to keep people’s attention on the documentation. I’d prefer it if the docs did not become a dead site, for reference only.

But what serves the customer better?

What do you think?

Heh heh, it’s a complex question. And now let me add this specific question to the list: Would you cry if we removed the ability to comment on the Atlassian documentation in particular? (This is just a general question. There are no definite plans at the moment to remove commenting.)

Let the comments begin.

My earlier post let everyone know that I’m writing a book about technical communication on Confluence, titled Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. We’ve been busy with the technical review for the last two weeks. The review phase finishes this weekend. Then I’ll incorporate all the feedback, finalise the content and compile the index. The deadline for final content is end of December. I’ve taken two weeks’ leave, starting today, to focus on the book and meet that deadline. Yaayyy!

I submitted the book proposal in May 2011. Publication is due at the end of January 2012 – a little over a month away. I’ve been keeping track of the time spent on various aspects of the project: writing, admin, design, review, and promotion. When the book is out, it will be interesting to see the proportion of time spent on each activity. I’ll publish some graphs and a timeline. There are probably one or two technical writers out there who’ll be interested.

Hehe, that makes me think of what our CEO said when he heard that I’m writing a book. It was something like this: “Congratulations! All technical writers are frustrated authors, aren’t they!” He said it with a big smile.

A quick update on my Paperbark tree

Just over four years ago, at around the time when I started this blog, I also planted a couple of trees. One of them was a Prickly Paperbark. A few weeks ago it flowered for the very first time. The timing is rather nice, because the flowers bloomed just as I posted the announcement of the book!

Here’s a closeup of the flowers:

One tricky aspect: There is no indication that the image is selected. Just click it, and it will be OK.

How to wrap text around an image in Confluence 4.0

In case you’re wondering, it’s easy in Confluence 3.5: When you insert an image using the image browser, there is an “Align” option in the image insertion dialog, where you can choose no alignment, or left, right or centre alignment.

When using wiki markup (in either 3.5 or 4.0) you can enter an alignment parameter in the image markup. For example,

!MyPicture.png|align=right,border=1!

Happy word wrapping.

This is the title of the book:

Confluence, tech comm, chocolate

A wiki as platform extraordinaire for technical communication

It will be published in early 2012 by Richard Hamilton at XML Press.

What’s in it?

The book is primarily a guide to developing technical documentation on Confluence. But that’s not all. There are ideas and philosophies, tips and tricks, and special notes for technical writers about why a wiki is the tool we dream of. Many of the ideas apply to wikis in general, although the book focuses on Confluence because that’s the one I know best.

It’s a book for technical communicators, from someone who knows and loves them. It’s also for product owners, CEOs, developers and anyone else who is considering a wiki as a platform for technical communication.

The first part of the book introduces wikis and Confluence. Part 2 is an in-depth guide to developing technical documentation on Confluence. It starts with planning and design, moves on to developing content, through workflow all the way to release management. The more esoteric concepts are there too, such as content reuse, structure, style and online help. In part 3 we see what it’s like to work on a wiki. The book finishes with a section crammed with ideas. It’s all about making the most of the unique features that a wiki provides, to turn your documentation into technical communication extraordinaire.

Just in case you’re wondering: This isn’t an Atlassian project. It’s all my own, though of course Atlassian management and my closest colleagues know about it. It will be fun to see what other Atlassians have to say when they see the book. And when they see this post.

By the end of the book you will know everything I’ve learned in the past four years of working on a wiki. Oh, and chocolate plays a part too.

More coming soon

The illustrations are done. I love them! We’re about to start the cover design. I’ll show it to you as soon as it’s ready.

Who’s in the book?

There are even some characters in the book. I’ll introduce you to them soon. Watch this blog.

In Confluence 3.5, the location was visible in the wiki markup. I’ve logged an issue about the problem in Confluence 4.0: CONF-23945. Keep an eye on that issue for news about possible fixes.

The workaround in brief

1. Right-click on the image in the editor and select “View Selection Source”. (That is the name of the option in Firefox. Other browsers may word it differently.) You will see the HTML <img> element.
2. Find the src attribute.
• If the image comes from an external source, you will see a URL. That’s easy.
• If the image is attached to a Confluence page, the <src> attribute will look something like this: src="/download/attachments/181535157/1.png. The number in the middle, in this case 181535157, is the identifier of the page to which the image is attached.
3. Now construct a URL to view the page that contains the image, using the page ID instead of the page name: http://MY.CONFLUENCE.SITE/pages/viewpage.action?pageId=181535157.

A real example with pictures

In our release notes, we use a stylised number to illustrate the highlights of the release. The numbers are images, named 1.png, 2.png, and so on. We store them on a single page and reuse them in all the release notes.

Here I am editing the JIRA 4.4 release notes. I have right-clicked on the image that shows the number 1 in a grey circle:

Right-click on the image

Click “View Selection Source”, to see the HTML for the image element:

HTML for the image element

Grab the long number from the src attribute. In this case, it’s 181535157. That the identifier of the page to which the image is attached.

Construct a URL to view the page that contains the image, using the page ID instead of the page name, and use your magic number for the pageID: http://confluence.atlassian.com/pages/viewpage.action?pageId=181535157.

That URL takes you to the page called “_Images for Release Notes“, which is where we store the images for reuse in our release notes:

The page where the image is attached

Notice that you can get to a page via two URLs. One uses the page ID, the other uses the page name.

And voilà, you’ve found your image.

In Confluence 4.0, to convert a bulleted list to a table:

1. Copy the list.
2. Paste into a Microsoft Excel spreadsheet. Excel will treat each bullet and line feed as a separate row.
3. Select and copy the cells in Excel.
4. Paste them into the Confluence editor. Voilà!

This trick works in Confluence 4.0, but not in Confluence 3.5. It works with Microsoft Excel, but not with a Google Docs spreadsheet, nor with a Zoho spreadsheet. It is worth trying with other spreadsheet applications, if you happen to have one lying around. Let us know what happens!

Here it is in pictures. Click the images to see an expanded screenshot. Here is a list in the Confluence 4.0 editor:

Bullets

Copy and paste into Excel, then select the cells in Excel:

Excel

Paste into the Confluence editor:

Table

Confluence 4.0

Enter the following in the Confluence search box, assuming that your macro name is “x”:

macroName: x*

For example, let’s say that you want to search for all “include” macros:

macroName: include*

Or let’s say that you want to search for all “excerpt-include” macros:

macroName: excerpt-include*

Notes:

• The key word is case sensitive. It must be “macroName”, and not “macroname” or any other variation.
• There is a space between the colon and the macro name.
• The macro name (x, include, excerpt-include, and so on) is the value that you supply in wiki markup. (It is the name of the macro as defined in the “atlassian-plugin.xml” file.)
• The asterisk at the end of the macro name is required, to ensure that the search picks up all references. (Evidently the reason for this is that the value in the query is stemmed, but the value in the Lucene index is not stemmed. The asterisk will prevent the stemmer from kicking in.)

Searching for a macro in Confluence 4.0

Confluence 3.5

In Confluence 3.5, you can enter the curly brackets and the macro name surrounded by double quotation marks, like this:

“{excerpt-include”

Or this:

“{children”

Or even this, to find all occurrences of the include macro that include a given page:

“{include:my page name”

The trouble is that this will pick up all occurrences of the search term, both with and without the curly brackets.

As an alternative, try this plugin, which provides a user interface for a Confluence 3.5 macro search: The Macro Usage plugin. It is not (yet) compatible with Confluence 4.

Thank you

Thank you to Daniel Kjellin, the Confluence developer who wrote the Confluence 4.0 macro usage search, and who told me all about it! I just discovered it today. I hope you find it useful too.

Project Management – Plan, Do, Check, Act, by Julie McKibbin

In this session, Julie McKibbin took a look at the project management life cycle and the critical path. Then she examined why it is important to technical writers. Julie was inventive in her use of materials. She used presentation slides, a flip chart and a whiteboard, all at once. It was also a very interactive session, with lots of audience participation. We did an exercise on planning the preparation of a roast dinner, including listing the ingredients, defining the critical path and creating a flow chart. One of the teams (from the back of the room, of course) had an amusing flow chart with multiple contingency plans that involved meals at Mackers and going hunting.

IT accessibility, by Richard Hodgkinson

Richard Hodgkinson talked about accessibility for ICT, and why it’s important in technical communication. He discussed the needs of elderly people or disabled people in what is fast becoming an eSociety. The eSociety assumes that we all have access to electronic services. This is not always the case. Remembering and managing multiple passwords is difficult.

It is possible to design for these needs. A good example is the Sagem VS3 mobile phone brought out by Vodaphone a few years ago. It was simple, with clear displays and only the basic functionality as required in a phone.

Richard walked us through the existing standards and guidelines for accessibility design, of which there are a number.

Documentation is important in this arena. Think of the setup guides for various household appliances. Keep it simple, provide only the information that is needed, use media that have accessbility features. Document the accessibility aspects of the documentation too. Widget and Makaton are symbol languages that are available for use in instructions for multilingual and accessible requirements.

Death by PowerPoint, by Frank Munday

Frank “Choco” Munday presented the final session of the day. He was introduced with the words, “be prepared to have your socks knocked off!” Choco’s session was all about how to design PowerPoint presentations so that they are not a cause of death. He delivered the presentation in typical exuberant style. Just the ticket for a closing session.

Til next time

See you at ASTC (NSW) 2012!