This is the second in a series of posts from Atlassian’s Technical Writing Team focusing on using a wiki for technical writing. Last week, Andrew Lui talked about why wikis are ideal for collaborative documentation development. In this post, I’ll be talking about how you can use a wiki to publish documentation, from authoring content through to publishing.
Wikis support structured content!
Many people still think of a wiki as an amorphous collection of pages, where you can only find related pages by clicking links on a page, an index or the results from a built-in search engine. Not all wikis are like this! Good wikis allow you to structure your pages into a hierarchy of ‘parent’ and ‘child’ pages. This allows you to develop content as you would do when writing a book or information manual, consisting of parts, chapters, sub-chapters, sections or sub-sections.
Enterprise wikis, like Confluence, have the concept of ‘spaces’ where each space is a self-contained hierarchy of pages (effectively a miniature website) with its own set of permissions. We use Confluence spaces to house documentation for different products and even different editions/versions of a specific set of documentation. Confluence also allows us to re-use content elegantly across spaces and link pages between spaces.
I’d also like to mention the Confluence Documentation Theme for the presentation of your documentation (see the screenshot below). You can apply this theme to any space in a Confluence site. It provides a customisable ‘online help’ interface that allows your readers to glance through your page hierarchy in a table of contents in the left-hand column of a browser window and view the actual page content on the right. You can even add a search box in the left column that restricts your searches to a hierarchy of pages in your space, so that no other pages in your Confluence site are retrieved in your search results. The documentation theme helps keep your documentation structured and your readers find what they are looking for, fast.
Why are wikis ideal for collaborative documentation?
Wikis allow you to draft page content and have it reviewed amongst specific colleagues, before publishing this content to a wider audience or the general public.
You can apply viewing and editing restrictions to pages so that specific colleagues or different groups of colleagues can view, edit or comment on your drafts. For instance, you might request that your reviewers edit pages directly for minor corrections, or add comments describing any significant changes needed. In Confluence, you can control who can edit pages and who can comment on them. This allows you to get feedback from a wider group via comments, without this group being able to edit your page content.
Each time you save a page, Confluence keeps a record of the changes in that page’s ‘page history’. If you don’t like the changes you’ve made to a page or they are no longer required, you can ‘roll back’ your saved changes by restoring the appropriate earlier version. You can also compare the differences between any two versions in the page’s history, if you’re unsure of what exactly was changed.
To facilitate collaboration throughout the review process you can:
- Elect to receive notifications (via email and/or RSS feeds) when a specific page or any content in a space is modified,
- Follow the activity of other users in your wiki site, so that you can keep track of when specific users add or modify pages or comments in your wiki,
- Update your current status to let others know what you are working on and
- Make your readers feel engaged by allowing them to contribute content through page comments (or even update your documentation if you so wish).
With the ability to structure content like a book or manual and a rich set of collaboration features that make it easy to draft, revise and publish content, wikis are ideal for collaborative documentation!
How would you write, update and publish content in a wiki?
If you were going to write content for a new wiki site or space, you would normally start with a ‘root’ page and add child and descendent pages to build up your documentation set. However, the more common scenario is to update content for new editions/versions of existing documentation.
Update existing content
At Atlassian, we use a public Confluence site to write all of our product documentation, where each major version of our products has its own space in that site. We typically update documentation for new major versions of existing products by drafting these updates in the space of the current ‘live’ product version. Confluence does allow you to copy spaces via the Copy Space plugin, so why don’t we just create a new, hidden copy of the space to work on? The reason is that our documentation is organic and we can maximise its accuracy by allowing other colleagues to tweak bits of content in the current product version’s space. If we updated content in a hidden copy of this space instead, it would be missing out on all these valuable tweaks.
So how do you update content within a live wiki space? There are two types of page content updates — completely new pages and existing pages whose content requires revision. For new pages, we simply add a new page, apply the necessary viewing and editing restrictions to that page and begin adding content to it. For revision pages, we view the page we want to revise and create a copy of that page. This creates a ‘child’ copy of the viewed page, whose content is identical to that of its parent. We then apply the necessary viewing and editing restrictions to the child copy and begin modifying its content.
Publishing your updates
After updating your draft pages (with viewing restrictions) in your live wiki space, you then need to publish them. For new pages, it’s a fairly simple procedure – just remove your viewing restrictions from the page and the page is published! For revision pages, things are a little more complex. We usually copy the updated content from the child page and copy it into the parent page, overwriting it. The child page is no longer required and is deleted. However, there’s a slight catch…
What if you find that someone has updated a page after you took a copy of it for revision? Well, if that person’s update is relevant to your revision, you need to incorporate it into your child copy page before you start publishing the revised page content. If we suspect that a page contains an update which we haven’t captured in our revised child copy, we check the parent’s ‘last edited’ date to make sure it doesn’t postdate the creation date of the revised child page. Fortunately in practice though, we find this doesn’t happen too often.
What’s next?
So now you know how to collaboratively create and publish documentation using a wiki, where to from here? In the next post of this series, Sally Hawse will be talking about how you can structure and re-use content in a wiki to save you time and minimise content inconsistencies. In a subsequent blog, we’ll be showing you how to create archives of your documentation before updating and publishing new versions of it. After all, you’re going to have readers who’ll want to reference older versions of products before they upgrade!
Start using a wiki for technical writing for $10
With perpetual, full-featured licenses starting at $10 for 10 users, Confluence is an ideal solution for your technical documentation needs.
All Confluence licenses allow for unlimited anonymous users.
