A few thoughts on writing with a wiki

A few weeks ago, I decided to try using a wiki to work on a couple of personal writing projects. Normally, I’d use a tool like Google Docs or Writeboard, but this time around I wanted to use something that was under my control. On top of that, I needed better linking capabilities than those that Google Docs or Writeboard provide.

So, I installed DokuWiki on my personal Web site and got to work. Some of what I learned (both by trial and error and from reading WikiPatterns and this excellent resource) can be carried over to a documentation department that wants to use a wiki, or to an enterprise that’s adopting a wiki.

Curious? Then read on.

Structure, structure

One of the keys to good documentation, and good non-fiction writing in general, is solid structure and organization. And I shouldn’t have to explain to you why Structure becomes very important if your documentation will be published in another format.

The easiest way to impose structure on a wiki is to have the wiki document follow the same flow of styles that you’d find in your other documents. So:

  • Use structural markup — for example, don’t use bold text to indicate a heading.
  • Mark up headings properly, and in a logical flow. Don’t go from heading one to heading three; remember to put a heading two in there as well.
  • Break things up using bullets, tables, and the like.
  • Chunk the information, which leads us to ..

Sections on their own pages

This is actually something that I learned writing for the Web. Don’t you hate Web pages that go on for ever. Even if they’re properly structured with headings, subheadings, lists, and the like, long pages become tiring to read. There’s no reason this should be the case with documentation (or any other writing) on a wiki.

One way that I do this is to start a chapter or section on its own page, with a topic map linking to each section or subsection. The first link would, obviously, be the introductory section/topic, followed by the subsequent sections and subsections.

Linking in a wiki is easy, and you can add jumps between topics where necessary.

WYSIWYG or not?

I prefer not. I’ve set up my wiki so that I can use Markdown and Textile for add formatting. Other people are comfortable with WikiText. That said, a lot of people prefer using a point-ad-click environment to add formatting to a wiki page. In that latter case, many wikis had add-ons that give the wiki rich editing capabilities.

The best thing to do here is to take a survey — see who wants to use WYSIWYG and who wants to use WikiText. Run a trial of each for a couple of weeks, then go with the one that’s most popular. In many cases, you might find that WikiText is the surprise winner.

Getting things out of the wiki

This can be the fun part. Some wikis have plugins that enable you to export wiki content to XML, HTML, PDF, or even OpenDocument Format. Some wikis, on the other hand, don’t have this ability.

So, what do you do if you’re using one of the wikis that doesn’t support export to another format? You can save wiki pages as HTML from within your browser by selecting File > Save Page As from the File menu. If the page has a printer-friendly view, then save that instead; it strips out most of the navigation.

I’ve also been playing with a tool called Deplate which can convert pages containing wiki markup to HTML, LaTeX, or DocBook. Deplate’s not perfect, but it does do a decent job.

The main concern here is whether what’s output retains the structure of the document and the styles that have been applied to various elements in the documentation. When you move from a markup language to another format — like RTF — you often wind up with a document that uses the equivalent of manually-applied formatting rather than actual styles.  

Anything more?

Probably a lot. I’ll learn or come up with more ideas and guidelines as this experiment progresses. Keep watching this space for updates.

This work is licensed under a Creative Commons Attribution 4.0 International License.

  • http://ffeathers.wordpress.com Sarah Maddox

    Hallo Scott

    Very interesting! I started using a wiki about ten months ago, and your reactions are very similar to mine. My first impression was ‘wow — this is such fun’. Just as you said above, the fun part is getting things out of the wiki.

    I think a lot of it is because wikis tend to attract enthusiastic developer communities, who keep adding new plugins all the time. As well as the formatting and export side of things, you can often use a plugin to integrate another product or application into your wiki. So with just a little bit of wiki markup, you can display a dynamic list of news items from an RSS feed — your readers will see whatever is latest when they view your page; or you can display a list of issues from your bug tracker; or whatever — new things keep popping up.

    The effect is that you often find yourself re-thinking the very nature of a technical document. It becomes a “live” thing. And that takes some managing too :)

    Do let us know how the experiment progresses ;)

  • Pingback: Documenting the Atlassian IDE Plugin on a wiki « ffeathers — a technical writer’s blog()