ffeathers — a technical writer’s blog

Today I did a stone sculpture workshop at the Brookvale Ceramic Studio. It was awesome. This blog post has nothing to do with wikis. Instead, it’s about something that’s a bit harder to undo once you’ve done it. ‘Written in stone’ they say — but you do have a few hours before this particular type of stone sets.

I’ve never done anything like it before. A friend said, Do you want to try stone sculpture. So I went along, armed with an idea of what I’d like to carve, plus my lunch, old clothes and some closed-in shoes. The lunch and attire were as instructed in the studio’s leaflet. The vague idea was based on the picture on this book cover:

Above: Cover of ‘Educating Eve’ by Geoffrey Sampson, published by Cassell, showing Egyptian figurine from about 4000 BC. © British Museum.

We were met by our instructress, Nola. She’s great - professional, skilled, fast with ideas and designs, and when the pressure hits she’s as cool as a cucumber. At times, this came in very useful. Beginners all, we tended to lose noses, fingers and toes. Not our own, of course, but those of our under-construction masterpieces.

I thought I would find a rough-hewn chunk of stone waiting for me at my work table. But no — there was a a bag of cement mix, a couple of buckets and a spatula:

For the first hour, we played with cement mud. It was a bit like making an apple-crumble pie — start with the dry ingredients and add the wet ones slowly, rubbing the mixture continuously to keep it crumbly. Then it got wetter, and it was more like mixing the icing for a cake. We had to aim for that consistency when the icing will form a nice gooey clump, but won’t flow off the edge of the cake. Or, if you’re not into baking, think of the sea sand just on the edge of the waves. It looks dry, but when you press it the water seeps out.

This part was very hard work. As the mixture got wetter, it got heavier. And we had to ferret out all the lumps and all the dry bits. At last, we could pat it all into a box:

While the cement mix was drying, we drew our designs on paper and then practised carving them on soap:

After about an hour, the stone was ready for the real fun to start. First we drew our design onto the stone with pencil. Then we used knives, spoons, and a variety of wooden and metal instruments to carve out the shape and designs we wanted. This took the rest of the day. In all, we were there from 9 a.m. to 4 p.m. The stone got progressively harder as time went on. It was interesting to feel the difference in the texture, and the change in the way the hardening stone reacted to being scraped, cut and molded.

Nola went from person to person, giving a helping hand here and a hint there. Forming, shaping, advising and consoling, plus sweeping away the scrapings and telling us about techniques we might use when we’re further down the sculpting path, she didn’t seem to sit still for an instant. Here’s my sculpure at a fairly early stage, with the trial bar of soap next to it:

What I really enjoyed was the way my design changed and gained its own character as we worked on it. Here’s the end product:

Above: Front and back views of my sculpture. Actual size: 37cm high and 22 cm wide.

There were five of us in the class. Here are my classmates’ sculptures:

Above: Cathy’s sculpture. Stands upright.

Above: Heather’s sculpture. Bowl in left-hand side will contain water and maybe a couple of frogs.

Above: Rachel’s sculpture. Two nooks on top (not shown here) can hold candles.

Above: Mark’s sculpture.

At the end of the day, we were tired and happy. And we got to take the practice bar of soap home too, which was good because I surely felt like I needed it!

Studio details: Nola, Brookvale Ceramic Studio, 11/9 Powells Road, Brookvale, NSW, Australia. Phone: (02) 9905 0264.

Calling all technical writers — are you a wiki hugger already, like me or just getting interested? Let’s get in there and make our voices heard. We’re in the front line, writing technical documentation and pushing it out to readers in far-flung corners of the world. Wiki technology has been around for a while, and many wiki developers are looking for new things to do with their product. New features and innovative mashups appear almost daily. Let’s speak up, tell them what we like, and help make wikis even better.

endithinks commented on my previous post, asking what the challenges are and when it would be inadvisable to use a wiki. And Don pointed out a couple of problems we’ve had to work around, when using a wiki for document management. He also identified the tree in my photo. Thank you, guys.

So, what does a wiki not do very well? Should it be doing those things at all? And what’s happening in that sort of arena?

A wiki is not a document management system. It’s not meant to be. If you need strict version control and records management for purposes of legal or other compliance, then you’d probably stick with a more traditional document management server, such as Documentum, Lotus Notes, SharePoint or what have you. Also, if you have a large existing base of documents in other forms, it would be cumbersome to upload them to the wiki and then ask your readers to view them as attachments to wiki pages. Instead, you might use a wiki as a knowledge management system running alongside your document server.

Keep an eye on the new stuff happening:

• Atlassian and Microsoft have announced a Confluence-to-SharePoint connector. This is exciting for those of us who know and love Microsoft SharePoint. The connector is very new, so it’s a free download while still in beta. If you’re interested, try it out. I think that this is a great time for technical writers and SharePoint power-users to have their say on what the Confluence-SharePoint integration should do. It’s a bit basic right now.
• An intriguing snippet of information in a comment from xaop on a blog post by Craig (2nd comment in the list) mentions integrating their Docbook publishing process from Subversion into their project website, so that customers can link tickets, wiki pages and comments into the docbook. I’d like to know more about that one.

Wikis don’t really do workflow. In most cases, a wiki is for instant gratification — view, edit, save, and bob’s your uncle. But again, things are on the move. Here are some new developments I’ve come across. Let me know if you’ve seen others.

• Comala Tech have written a workflow and approvals plugin for Confluence.
• Atlassian is working towards the launch of JIRA Studio, which will allow people to use Confluence (wiki) and JIRA (project management and issue tracking) on one integrated platform. There will be some interesting source control and review tools in there as well.

Wiki editors are not always easy to use. Many of them rely on wiki markup, and there’s not much standardisation of the markup codes used in different wikis. But things are on the move:

• DITA Storm offers a browser-based DITA XML editor which you can embed in your web application.
• A number of wikis offer WYSIWYG editors.
• I’ve used Confluence and Twiki. I much prefer wiki markup to a WYSIWIG editor. But many of my colleagues swear by the WYSIWYG editor.

I’m a self-professed wiki hugger, and I’m not alone in that. A wiki has a certain charm and gives ‘everyman’ a sense of power (that instant gratification again). And wikis do a lot of things very well indeed. Because wikis are the flavour of the month, even after being around for a few years, they’re growing and changing apace. Now’s the time to have a say in their development.

Let’s make ourselves heard. Download a wiki and try it out. Most wikis let you try one for free, and some offer an ongoing free personal licence.

Make a fuss about the things that wikis are missing (see all the comments on and the votes for this requested Confluence improvement) and pat the developers on the back for the bits they get right. Let them know we ♥.

If you’re interested in more ideas and experiences in using wikis for technical documentation, read some of my other blog posts on wiki docs and watch this space — more coming. Also, wander over to Anne Gentle’s blog and search for other wiki writers’ blogs.

There’s a lot more happening. Let me know what you’ve seen and done.

A wiki is a living organism. Its content is dynamic, continuously updated, commented on, subscribed to and watched by thousands of people all over the world. How does this work with technical documentation that is release-specific? Can you baseline your documentation? What if you are documenting a piece of software or some other product that goes through a regular release cycle, and your customers need to access the documentation which corresponds to their specific version of your product? This is elementary release management, bread and butter to technical writers. But can a wiki do it?

This week I created an archive space on our Confluence documentation wiki, in preparation for an upcoming major release of Atlassian Crowd. So now’s a good time to talk about the way we manage the technical documentation in correlation with our software releases. And to find out how other people are doing it.

Let’s say your wiki pages tell people how to use a toaster. And let’s say the very latest toaster in the product line, due out before Christmas, has a bright new quick-toast button. But there are thousands of customers out there who already have the original product and rely on it heavily - even without the shiny new button. What should your documents say about the button? Even more complicated: What if the toast-insertion mechanism is about to change from the old shove-it-in-by-hand method to a fancy new sliding widget?

There are a few strategies:

• Have separate documents for each version of the toaster.
• Have only one document, describe all features including the newest, and add a note that the quick-toast button is available only on the latest toasters. Also explain how the toast-insertion functionality has been enhanced. You could even hint that your customers should consider upgrading their toaster.
• Ignore older versions of the product, and only give instructions on using the very latest version.
• Any more? Let me know how you’ve done it.

Our choice:

We’ve chosen the first option. The second might result in a long list of notes, tracking a feature’s changes through the various releases of the product. This might become confusing in the long run. (But the second option does have its attractions - it’s a lot simpler, from the point of view of document management.)

We make use of ’spaces’. A space is a sort of wiki-within-a-wiki, and is part of a Confluence wiki. If your wiki doesn’t allow spaces, then you might consider having separate wiki instances for each software release.

Here’s how we do it:

• The ‘main’ documentation space always contains the documentation for the latest release of the software - such as Crowd.
• ‘Archive’ spaces contain the documentation for each previous major release of the software - such as Crowd 1.0.
• We also provide PDF, HTML and XML versions of the documentation - here they are for all the Crowd releases.

The fly in the ointment.

That sounds quite simple, huh. But as usual, there are some idiosyncrasies which need a bit of working around. The tricky bit is in the first bullet point above - the ‘main’ space always contains the documentation for the latest software release.

So we can’t start adding information about the new release until release date. And we can’t archive off the current space or create a new ‘draft’ space which will take its place at release date.

Why not? Two very important reasons:

1. Lots of people all over the world have hyperlinks into the documentation space, and subscribe to RSS feeds from it, and add ‘watches’ to pages on it, and comment on it. So we can’t archive the existing main space - that would break all their links and stuff.
2. The wiki is alive. As well as the technical writers, we have support staff and developers continuously updating the content. If we created a draft space and then later used it to replace the current space, we’d lose all updates made since the draft was created. And if we ‘froze’ the current space, the wiki wouldn’t be alive.

The fly catchers.

How do we solve the problem? Well, it takes a fair bit of organisation, and the help of a couple of tools.

When documenting new features for the upcoming release, we create pages in the wiki and ‘hide’ them from public view using Confluence’s page restriction functionality. And we make a note to ‘unhide’ the page on release date.

When we need to add or change existing pages due to changes in the upcoming release, we can’t make the change until release date. So we make detailed notes about the changes that need to be made.

Some time before release day, we make an archive copy which will become the documentation for the previous release (now still the current release).

On release day, we first update the space description so that it refers to the latest software release. Then we go through our ‘unhide’ and ‘update’ notes, applying the changes to the main space.

Where do we make the notes, you may ask? In a JIRA task, of course.

Summing it up:

Yes, a wiki can handle release-dependent documentation reliably and usefully. It’s pretty similar to using any other documentation system - find the tools that will help, and then make a plan to make them work to your requirements.

Wikis save trees.

Completely off topic but I wanted to add a pretty picture because release-management is a bit of a dry subject. Here’s a gum tree we came across this week, while walking through the Manly Dam parklands. The multi-coloured bark is a lovely sight, and quite common too. Does anyone know the name of this tree?

For some ideas on layout and structure of technical documents on a wiki, you may be interested in an article I wrote for the Atlassian News blog. The article gives some pointers on using Confluence plugins (add-ons to the core Confluence product) to add structure and style to your documents. It includes some pretty pictures too

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