Guess a name to win a copy of my book

Would you like to have some fun, and perhaps win a copy of my upcoming book too? Just guess the name of the girl on the cover! The first person to get it right will receive a free copy of the book, in a choice of paperback or ebook format.

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.)

REST API documentation embedded in the application

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.

Should we allow comments on documentation pages

This is a very interesting question: Should we, as technical writers, allow comments on our documentation pages? It’s interesting because it’s a multi-faceted question, and because people have such strong feelings about it. My quick answer is, “Yes”. Ha ha, but there’s always a “but” or two. Read on, and then I’d love to know what you think.

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.

A quick update on my book

The Confluence, Tech Comm, Chocolate wiki is buzzing! That’s where I’m writing the book, and that’s where the technical reviewers are giving their feedback at the moment: on the wiki. It’s good fun seeing all their comments flow in. Their input is very useful indeed.

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:

How to wrap text around images in Confluence 4.0

I have just learned how to wrap the text around an image in Confluence 4.0. W00t. Just click the image to select it, then click the left-align or right-align button in the editor toolbar. Simple when you know how!

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.