ffeathers — a technical writer’s blog

Happy holidays everyone, and het allerbeste voor een fantastisch 2008. My father made this candlestick and sent it all the way from Cape Town.

Online help — it’s a technical writer’s dream. We all want to design and write online help systems, and we all know that context-sensitive help is the way to go. Can you do it on a wiki?

Yes I wrote an article on the Atlassian News site this week, illustrating how we’ve used our Confluence wiki to provide context-sensitive help in the latest FishEye and Crucible software releases. Have a read. It’s got some pretty pictures as well as the technical stuff

Clarifying my terminology: By ‘context-sensitive help’, I mean that when you click a help link on an application screen, you get the instructions directly related to that particular screen. Also at a deeper level, when you click a help icon next to a field you get help on that specific field. We’ve provided both these levels of help, as described in the above article. Another type of contextual help is when you hover your mouse over a field and a short description pops up in a kind of bubble. That’s usually called a ‘tool tip’, and is not what I mean here.

I’ve written a number of online help systems for various companies, using a variety of tools. My favourites were Help and Manual and RoboHelp. I’ve also dabbled with HDK (the precursor to XDK) and with Microsoft’s ‘raw’ HTML Help editor. And now I’m using Confluence wiki.

What’s the difference between a wiki and a help authoring tool? Well, there’s a big difference, of course. A wiki is essentially a collaboration platform — your online documents become a place where everyone goes to find information, share their own tips with others, and pick up the latest updates. A help authoring tool is tailored towards building a documentation set which is essentially static (even if you update it every day, it’s still not a discussion platform) but which has all the bells and whistles of an integrated online help system.

Most help authoring tools provide the following functions. You’ll probably have trouble finding a wiki which supplies these functions to the same degree:

• Fully customisable table of contents, where you can put topics in the order you want, omit topics, or make a single topic appear more than once.
• Integrated keyword index.
• Integrated glossary.
• Navigational tools to make topic browsing easier, such as the ‘browse sequences’ provided by RoboHelp.
• Topic linkage tools, such as the ‘next topic’, ‘previous topic’ and ‘related topics’ tools which are built into some help authoring tools.
• Generation of HTML Help (.chm) and WinHelp output files.
• Workflow support (draft, review, publish).
• Integration with a source control tool such as VSS, or RoboHelp’s inbuilt check-in check-out manager.
• Automatic generation of topic IDs, which you can hand over to a developer for plugging into the code to generate context-sensitive help links.
• Sophisticated topic templates.

That’s a long list. So what does a wiki provide, in terms of usefulness for online help?

• A wiki page is just a URL — so you can link to the page directly from your application screen. (Read my Atlassian News blog to see how we’re doing it with Confluence.)
• Wiki pages are continuously being updated and enhanced by technical writers, support staff and even customers who have useful tips to share. So when someone clicks the help link, they get the most up-to-the minute information possible.
• Wikis allow you to embed multimedia goodies such as images and Flash movies.
• You should be able to generate PDF, HTML and XML versions of your wiki pages.
• A good wiki has a good search engine.
• Some wikis provide version control — all changes are tracked, and you can see who made each change or even revert to a previous version of a page.
• A wiki often provides tools for runtime integration with other software — many wikis allow you to install plugins or addons which display information directly from another platform. For example, a wiki page can show a list of bug fixes drawn dynamically from an issue tracking system like JIRA.
• Some wikis allow blogging as part of the wiki platform. So your documentation page can embed a list of the latest blog posts related to the topic of the page. The blog posts will always be the most recent as at the time the user views the wiki page.
• Your wiki is sure to have a number of other interesting features which you can use to work around some of the shortfalls listed above. If you’re interested, take a look at my previous posts on using wikis for technical documentation.

In short, wikis are different. They’re not necessarily better or worse — it depends what you need for your documentation system. Wikis are fairly new, so they’re developing all the time. I’m having fun riding the wave

Some words are captivating. Here are a few I’ve come across lately. They’re all related to linguistics. Maybe that’s why they appeal to me. Or maybe it’s just the way they sound. I’d be interested to know if you think these words are cute, and whether it’s because you’re a linguaphile too?

Bahuvrihi — a compound word like ‘lowlife’ or ’sabertooth’, where the meaning of the word is not a type defined by one of its parts. A ’sabertooth’ is a type of tiger, not a type of tooth. A ‘lowlife’ is a type of person, not a type of life. This property is significant, because it affects how we use the word in a sentence. For example, when talking about more than one of these things, we automatically use the regular plural rather than the irregular. So we say ‘I went back in time and saw a lot of sabertooths’ — not ’saberteeth’. And we say ‘lowlifes’, not ‘lowlives’. Compare ‘workman’ (not a bahuvrihi, because a workman is a type of man) with ‘walkman’ (a bahuvrihi). We talk about many ‘workmen’. Can we say, ‘how many walkmen do you have’?

Dvandva – a compound word made of two equally-weighted nouns, like ‘girlfriend’ and ’singer-songwriter’. These words have a similarly intriguing effect on our internal language generator, but let’s not go there

Synechdoche – that’s when you use part of something to refer to its whole. ‘I got me a new set of wheels’ means I bought a car, not just the wheels. When you ‘count heads’, you are counting the number of people, not just their heads.

And my favourite: hapax legomenon — a word or term which is used only once in a particular body of text.

This weekend I’ve been writing some Christmas cards, and struggling as usual to find the right words. Maybe I’ll drop in the odd hapax legomenon to spice things up

Thank you to Kate for lending me Words and Rules, the book in which I found these words. And to Steven Pinker for writing it.

Some tree news:

Here’s a tree recovering from a fire in the Manly Dam reserve:

And here’s a grass tree (Xanthorrhoea) which survived the fire altogether:

One of the best things about technical writing is the variety it offers: who you work with; the style of writing required; the type of products you document; your input into and impact upon the products themselves; the medium you use, and so on. One of the products I work on is highly technical, and the documentation is funky that way too. The product is Crowd. If you find authentication, authorisation, single sign-on and user management sexy, then Crowd is for you. And the documentation would be your choice of bed-time reading.

This week we released Crowd 1.2, a major release with lots of new features. So we published many new and revised documents too.

Documenting this type of product is interesting. On the one hand, you get a kind of glow from belonging to the elite group of people who understand words like ‘Acegi’ and ‘OpenId’. You have the chance to indulge your natural inclination for long words and other esoterica. You may notice one or two creeping into this blog post On the other hand, in the documents themselves the trick is to know when to explain something and when not. After all, we have a savvy readership. I try to keep explanations short. Often all you need is a link to an authoritative website and an expansion of an acronym on first use.

Gourmet’s guide to a technical document: Mix the dry ingredients. Sprinkle in the acronyms. Pour the open source over the top.

Another interesting thing about this type of documentation is that the developers write much of the content themselves. As technical writer, I guide and tweak the content. When I can, I’m keen to jump in and test-drive the integrations myself before documenting them. But sometimes that’s not practical or efficient.

Wikis are great for collaborating like this. I might kick off a document by creating the skeleton structure. Then the developer writes the first draft. I jump in and tweak some things. The development lead and another technical writer do an in-depth review. And there you have it, a document to suit the epicurean taste.
Sometimes, you can even make the document look pretty:

Ain’t that just copacetic?

Have you noticed that your brain starts shooting off at a tangent when you’re writing dry technical kind of stuff? I had to explain ‘Acegi’ in the Crowd release notes:

Crowd 1.2 provides a built-in application connector for Acegi, a security solution with a particular emphasis on Spring Java/JEE applications.

Here’s what my gray matter kept insisting was relevant:

Spring has sprung, da grass is riz

I wonder where da boidies iz

Da boidies is on da wing

Don’t be absoid

Da wings is on da boid

That’s a jingle that my dad recited to me when I was just a kid. It’s spoken with a cockney or Bronx accent. Evidently the verse’s origins are obscure, though it’s often quoted, and sometimes cited as an anonymous work called ‘The Budding Bronx’. Isn’t it weird how such things stick in your head? A blog is a great place to get rid of such insistent promptings from the subconscious. The jingle would probably, though not indubitably, be considered out of place in the Crowd docs.