Writing a book with DocBook and a Confluence wiki

We’re in the final stages before sending my book off to the printers. Exciting! While we wait, let me tell you a bit about how the publishing team and I have produced the book. We’re using a Confluence wiki and DocBook XML.

Here’s our process in brief:

• Plan, write and review the book on a Confluence site.
• Use the Scroll Wiki DocBook Exporter to convert the content to DocBook XML.
• Use DocBook XSL-FO style sheets to create a PDF file for sending to the printers.
• Use XSL to generate ebook formats too.

This post is about writing and reviewing the book on the wiki, and converting the Confluence content to DocBook XML – the first two points in the list above. Richard Hamilton, at XML Press, is the expert on the further DocBook processing.

A bit about the book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Details are at XML Press. It is all about developing technical documentation on a wiki, with a focus on Confluence wiki. And just to be ultra meta, I’ve written the book on a Confluence site. Dogfooding FTW!

Writing, planning and technical review on the wiki

Richard Hamilton and I have spent the last nine months on a Confluence wiki site. We kicked off our planning there in May 2011. Since then, I’ve spent around 400 hours writing the content on the wiki. Ryan Maddox, our illustrator, has uploaded his images onto the wiki. For two weeks in early December, the technical reviewers joined us there too – six knowledgeable and enthusiastic people:

• Alan J. Porter – Writer, speaker, consultant
• Anne Gentle – Technical writer for OpenStack
• Ellen Feaheny – CEO of AppFusions
• Mark Fidelman – Social business GM at harmon.ie
• Robert Rhyne Armstrong – Director of documentation for RouteMatch Inc
• Sherif Mansour – Technical product manager at Atlassian

The wiki was abuzz with review comments, opinions and counter-opinions, laughter and chat.

Now it’s gone a bit quiet while Richard and I work on the last stages of book production. When we launch the book, we’ll open up the wiki site too. You’ll be able to join us there and make it buzz again.

DocBook for the publication processes

DocBook is an XML standard for documents, developed by O’Reilly as a means of making their publishing process more efficient. It is now an open standard maintained by OASIS.  Richard Hamilton, at XML Press, uses DocBook XML to publish a range of books on the subject of technical communication. Using a customised set of the open source XSL style sheets for DocBook,  Richard can create HTML, PDF (through XSL-FO), EPUB and other epublishing formats from the DocBook source.

Converting content from Confluence wiki to DocBook XML

So, I’ve finished writing the book and the reviewers have worked their magic too. It’s all on a Confluence wiki. The content is stored in the Confluence database in wiki format. How do we get it to DocBook so that Richard can create the print and ebook formats?

Enter the Scroll Wiki DocBook Exporter.

Scroll Wiki DocBook Exporter is a plugin for Confluence, developed by K15t Software. (A plugin is a small piece of software that extends the functionality of the wiki. It is similar to an add-on for a web browser.) Once you have installed the Scroll Wiki DocBook Exporter on your Confluence site, you can export a page, a set of pages or an entire space, to DocBook XML.

How to use the Scroll Wiki DocBook Exporter

The first thing is to add the plugin to your Confluence site. You need to be a Confluence system administrator, then you can install the plugin in the usual way:

1. Log in as a Confluence system administrator.
2. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
3. Type “scroll wiki docbook exporter” into the search box and click “Search”.
4. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
5. Click “Install Now”.

See the Confluence documentation on installing plugins.

You will need a license key from K15t Software. They provide a free evaluation license that gives you full functionality for 30 days.

Once the plugin is installed, a new option appears in the Confluence “Tools” menu, allowing you to export the content to DocBook format.

1. Go to the page that you want to export. If you want to export a set of pages, go to the parent page of the set.
2. Click “Tools” > “Export to DocBook”.
3. Adjust the options in the dialog that pops up:

Scroll Wiki DocBook Exporter

When you are ready, click “Start Export”. The plugin will create a zipped file containing the DocBook XML and attachments, and will offer the file to you for downloading.

A sample of the output

Here is one of the book’s pages on the wiki:

Front page of the book on the wiki

And here is an extract of the DocBook XML:

<?xml version=”1.0″ encoding=”UTF-8″?>
<book xmlns=”http://docbook.org/ns/docbook” xmlns:xlink=”http://www.w3.org/1999/xlink” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd” version=”5.0″ xml:id=”scroll-bookmark-1″>
<info>
<title>Confluence, Tech Comm, Chocolate</title>
</info>
<part xml:id=”scroll-bookmark-2″>
<title>Confluence, Tech Comm, Chocolate</title>
<chapter xml:id=”scroll-bookmark-3″>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
</chapter>
</part>

[SNIP]

<index />
</book>

Index, footnotes and figure captions

The Scroll Wiki DocBook Exporter supports these too. The plugin adds a number of macros to Confluence, which you can use to mark up the index entries, footnotes and figure captions. I’ll write another post with the details. I’m sure many people are agog to know how this works.

Working with K15t Software and XML Press

Richard and I have worked on this project with Tobias Anstett and the rest of the team K15t Software.  They are great people to work with: knowledgeable, enthusiastic and energetic. As far as I know, this is the first time anyone has written a book on Confluence for publication via DocBook XML. We have added new functionality to the plugin, especially for the index and footnotes, adapting and tuning as we go.

Thank you all. It’s exciting to help perfect a plugin that many other authors and technical writers will be able to use.

And I can’t wait to get my hands on a copy of the book!

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.