Found a list of tech writer blogs

Here’s a directory of blogs by technical writers.

Wikis, indexing of

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:

1. Use keywords (metadata, tags, labels – whatever terminology your wiki uses) to indicate the main point(s) of your page.
2. Encourage other people to add their own keywords too – especially if they change the content of the page.
3. 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.
4. 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.

APEC and security (off-topic)

I’m thinking I might phone the National Security hotline and tell them about the rumours that someone is planning to erect a 5km-long, 3m-high metal fence in Sydney CBD. That’s gotta be a threat to public health and safety?

Found the ‘Web Developer’ add-on for Firefox

Web Developer is an awesome Firefox add-on by Chris Pederick. Here’s what the toolbar looks like:

With just two clicks, you can resize your window to 800×600. Or you can choose a custom size. This is a must for conscientious web content writers – after all, we may be working in warpsize screen resolutions, but we still need to cater for people on stone-age systems.

Other useful features in Web Developer:

• Make the browser draw an outline around various page elements, like frames or headings.
• View a document outline – a sort of hierarchical list of headings and things, much like you can do with Microsoft Word.
• Look at the stylesheets.
• Show image information right on the page.
• And so on – there’s something for everyone.

Thanks Chris – great stuff.

Back to my little trees

(See my previous blog post.) Hey, the trees are the same age as this blog! My blog is two weeks old today. That’s gotta mean something. Every so often, I’ll compare the blog’s progress with the trees.

We’ve just been out and planted the trees. It’s pouring torrents here in Sydney, so we got drenched. Here are some photos of the baby trees before planting:

	Prickly Paperbark – the baby tree with a peg to show relative size.
	Prickly Paperbark – close-up of the trunk. It’s pretty even now. When the tree grows, the bark will be silver and very flaky.
	Saw Banksia, a keystone source of nectar for birds and animals here in Sydney.

A way into a wiki, plus two trees

This week I finished writing a new administrator’s guide for Atlassian’s Confluence Hosted.

Check it out. It’s a cool green colour, with lots of pretty pictures and helpful words. In fact, it should have the words ‘Don’t Panic’ printed on the front cover. I’m quite proud of it.

When you’ve finished admiring the doco, you’ll probably start wondering what a ‘Confluence Hosted‘ is, and why you might want one. Well, it’s an easy way into a wiki. Instead of downloading and installing the wiki software, you can use the one on Atlassian‘s servers.

Continuing with the green theme: I’ve just bought two new trees: a prickly paperbark and a saw banksia. They’re both native Ozzie trees. Both very small right now – evidently the technical term is a ‘tube’, but basically they’re baby trees. The banksia will attract birds, like the colourful lorikeets that zoom around here. The paperbark will strew its bark all over the garden.

Going planting ♥