Late last year, Atlassian’s Technical Writing Team published a series of posts about how you can use a wiki for technical writing. Their posts cover the complete process from developing your technical documentation, to collaborating and reviewing drafts, publishing online and options for importing and exporting to different formats, including DITA and XML. Checkout out the posts below and learn how you could use a wiki like Confluence to author, publish, structure and manage your documentation.
Hopefully the members of this community will find this guide useful. We’d love to get your feedback.
Technical Writing in a Wiki: Technical Communicators Explain How & Why
The truth of the matter is that wikis are just as capable of supporting a comprehensive suite of documentation as traditional publishing or CMS tools. A wiki can carry out document versioning, content re-use and structure, release management, single sourcing, publishing and more. These topics in more detail in the following posts, but here are a few of the benefits that we’ve discovered from using a wiki for documentation:
1) It’s good for you (the technical writer)
2) It’s good for your customers
3) It’s good for your company
Technical Writing in a Wiki: From Draft to Published Document
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.
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…
Technical Writing in a Wiki: Content Re-use and Structure
Content used to be king. Now content re-use is king — it’s the ‘killer app’ that saves time and money. Content re-use in a wiki also means you’re still on the same page no matter how individual the contributors, the process or the content.
There are four clear reasons to aim for content reuse. It:
1) saves time
2) saves money
3) provides consistency
4) helps you repurpose and adapt your content to specialised audiences and needs
Technical Writing in a Wiki: Documentation Release Management
The product launch is drawing close. You’ve carefully crafted your new documentation pages and updates. Now comes the task of releasing them in coordination with the release of the product to which they relate.
But first you will need to take care of the versioning.
If you’re documenting a software product, you will typically need to maintain different versions of the documentation: one for each version of the product. So how exactly do you use a wiki to publish multiple sets of documentation for the same product? Confluence can do this wonderfully well. On the Atlassian documentation wiki, for example, you will notice that the dashboard lists a space for each major version of every product…
Technical Writing in a Wiki: Single Source Publishing
As technical writers, we always keep our readers’ and customers’ needs at the forefront of our minds. One of the most basic requirements is that our readers will have access to the documentation. No matter what tool we use to write the documents, we must be able to publish them in various output formats depending on where our readers are and the tools they have at their disposal.
Let’s consider two aspects of single source publishing, or single sourcing as it’s also known:
1) Developing documentation on a wiki and then publishing it in other formats.
2) Using some other tool to develop the documents, then publishing them on the wiki.