Category Archives: indexing
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.
- 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:
- Log in as a Confluence system administrator.
- Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
- Type “scroll wiki docbook exporter” into the search box and click “Search”.
- Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
- 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.
- 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.
- Click “Tools” > “Export to DocBook”.
- Adjust the options in the dialog that pops up:
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:
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″>
<title>Confluence, Tech Comm, Chocolate</title>
<title>Confluence, Tech Comm, Chocolate</title>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
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!
Can you use a wiki for technical documentation? Yes!
Is it a mindshift? Yes!
Is it fun? Yes!
Am I a wiki hugger? Yes!
I’m a technical writer with nine years’ experience. I’ve used many tools of the trade, including Microsoft Word, Adobe Acrobat, RoboHelp, XDK, Help and Manual, HTML Help, QuarkXPress, Documentum, Lotus Notes / Domino and Microsoft SharePoint. And now I’m using Atlassian Confluence, a wiki. Yes, I’m biased, but with good reason ;)
Writing technical documentation on a wiki is what I do every day. Here’s an example. So I’ve decided to write a few blog posts about it. This post is one, and there are more to come. So watch this space.
Like other media, wikis have a lot of advantages and also some quirks. Treat your wiki right, and it will come through for you. Often it’s a matter of recognising a wiki’s strengths and using them in a creative way to perform or even replace a more traditional function. For example, you could try using labels/tags to generate:
- The index – see my previous blog post.
- Lists of ‘related topics’, which we often put at the top or bottom of an online help topic.
- Frequently asked questions (FAQ).
So, let’s get down to the nitty gritty.
First, you might have the luxury of choosing your wiki.
Here are some things to consider:
- Does your wiki allow you to restrict access to the pages, and what permission levels does it allow? For example, you might want to prevent anonymous users from seeing anything at all. Or you might allow everyone to view your pages, but only logged-in users can comment on them and only users belonging to a certain group can add, edit or delete content.
- What overall structural framework does the wiki provide, to allow you to organise your manuals, chapters and pages?
- How easy is it to structure the information within a page using styles, headings, frames, etc?
- How easy is it to upload and insert images?
- Does the wiki let you export/download the content into another medium, such as PDF or HTML?
- Do you know anyone who is using a wiki for technical documentation, and can you get some tips from them? Alternatively, take a look at some of the documentation already published on a wiki. I’ll put some examples at the end of this post.
- Does the wiki keep a history of changes to a page, and allow you to revert to a previous version?
- What tools are there to help your readers find information, such as indexing, table of contents and search?
- Does the wiki allow customisation – at the highest level of adapting styles and presentation, and at the deeper levels of allowing you to add plugins, change the default page layouts and even change the source code?
- How vibrant are the developer and user communities – is there ongoing development and support of the wiki?
Here’s a really useful tool: WikiMatrix lets you compare wikis. You can even your own requirements to see which wiki is best for you.
Now that you have a wiki, start planning your documentation:
- Consider the overall structure of your documentation suite, much as you would plan a user guide or a set of documents written in Word or something else. Plan how that structure will fit into the wiki’s framework. For example, you might want to write a user guide and an administration guide, each consisting of sections, chapters and pages. Will you put each guide into a separate instance of the wiki? If you are using Atlassian’s Confluence, you might consider putting each guide into a separate ‘space’ (a sort of wiki within a wiki). Or you might use a space to collect all the documents for a particular product – that’s the route we’ve chosen. For example, our Crowd space contains the user guide, administration guide, installation guide, etc.
- Think about the structure of each page. If your wiki allows you to create templates, that’s useful. But a light touch is best here. Given that you’re probably going to have multiple authors with different styles and skills, I’d go for overall consistency of look and feel rather than detailed content-level standardarisation.
- Think about the style and character you want for your documents e.g. formal or chatty, stylish or basic. Tailor your use of styles, macros, colours, etc to suit this character. In the list of wiki documentation sites at the end of this post, you’ll see a few different styles.
- Plan your permissions - who should be able to do what. We allow all Atlassian staff full edit rights. Non-Atlassians and anonymous users can add comments and of course can view the pages.
- Remember that it’s a wiki, so its power lies in its flexibility and dynamism. Don’t lay down too many rules, and do allow as many people as possible to edit the pages.
- Have you hugged a wiki today? Get intimate with your wiki’s capabilities and tools. If your wiki allows you to install extra plugins and macros, get to know them too. This will help you quickly find a solution to any questions that arise.
- Think about your labels or tags carefully – plan them as if you were planning the keywords for an index in a more traditional type of documentation.
- You, as the technical writer or person who owns the documents, should subscribe to an RSS feed or a watch-list of all changes and comments. That allows you to monitor what’s happening and tweak the content if necessary.
Jump in, create a page and start writing.
Some examples of technical documentation published on a wiki:
Atlassian’s documentation and discussion site
Atlassian Confluence Hosted Administration Guide
Atlassian Crowd documentation
Adaptavist User Guides
Ubuntu User Documentation
I’ve run out of time – if anyone has any more examples, I’d love to hear about them.
Watch this space:
Do you feel that this post has raised more questions than it’s answered? I hope it’s given some good starting points. And stay tuned for more – I’ll expand on some of the points in my next blog posts.
I’ve spent a fair bit of time as a book indexer. For a couple of years, I was leader of the Association of Southern African Indexers and Bibliographers in the Western Cape. A few books have my name printed inside the front cover. You might find one on your coffee table.
A BTW: So there are people who create those indexes in the backs of books? Can’t we get computers to do that? Yes, there are professional indexers out there. And no, computers don’t do a good job of it, though indexers do use custom indexing software to speed up the process.
Now I’m writing technical documentation on a wiki.
Indexers like things to be clear cut.
- They worry about things like this: Is it better to say “books, indexing of” or “books, and indexing” or just plain old “books, indexing”?
- They are proud that their index includes precisely the correct terms, and that each term points directly and unequivocally to the relevant page(s).
Take a wiki. Content is dynamic and slightly chaotic. You may write a page that is perfect and precise. Next time you look at it, someone has changed it. The other person sees things slightly differently to you, so your nicely defined concepts have morphed a bit. Someone else adds their viewpoint, and the concepts are now definitely squishy (in your own view, anyway).
How can we fit something as precise as an index into something as fluid as a wiki?
What tools does a wiki provide for creating an index?
Enter the ‘fuzzy index’
(Cf. Wikipedia’s definition of fuzzy logic.)
Since wiki content is constantly changing, any index is bound to be slightly less reliable than in a more controlled environment. So why not go with the flow. Instead of concentrating on precision, the wiki index could aim to:
(a) include all wiki content in the index in some form or other, and
(b) help readers to find the information they need, by methods other than the traditional alphabetical and hierarchical index.
Here’s a plan:
- Use keywords (metadata, tags, labels – whatever terminology your wiki uses) to indicate the main point(s) of your page.
- Encourage other people to add their own keywords too – especially if they change the content of the page.
- Use some sort of visualisation technique, based on popularity or relevance of keywords, to help readers find the content which is most relevant to their needs.
- Make sure that the wiki’s search engine can include the tags/labels/keywords in its search results.
Here is an example using Confluence‘s labels to form an index. Click the images to expand the screenshots.
Labels (tags, keywords, metadata) applied to a wiki page (near top left):
All labels, displayed alphabetically, forming a traditional-looking index:
Labels ordered by popularity (i.e. number of times the label is applied to a page) – a sort of cloud:
List of pages which have a particular label, displayed when you click a label on one of the above two screens:
Search results, including labels which match the search term (near top left).
Of course, if you do need precision and tight control of your content, you can lock down your wiki pages via the permission settings (which just happen to be the topic covered in the above screenshots). This will prevent your concepts going squishy and make your index less fuzzy. It all depends on the purpose and character of your documentation.