Let’s say that the most driven and driving developer on your team, who also happens to be a popular blogger, comes to you and asks why your end-user documentation doesn’t allow comments or ratings. Rather than stammering something about Wikipedia’s latest scandal, or reaching for imperfect responses that sound like lame excuses, do your homework and learn best practices from others who are implementing social web content that is conversational or based on community goals.
In early March we opened up the Atlassian documentation to the wider community. We added a CC-by (Creative Commons Attribution) license to our product documentation. We invited people to contribute to our documentation after signing an Atlassian Contributor License Agreement (ACLA). At that stage, the ACLA was just starting its three-month trial. The trial period has now ended, and we're delighted to say: it's a go!
The dynamic nature of wikis can cause a few headaches when you need to baseline documentation that's on a wiki to correspond with the release of your product. This blog post looks at some ways in which you can try baselining wiki content.
A lightweight markup language uses syntax that is similar to wiki syntax -- keyboard characters are used to define formatting. This blog post argues that if your documentation needs are simple, and you have a low or non-existent budget, then a lightweight markup language might be worth investigating.
In July, in a sharp break from tradition, the Army began encouraging its personnel — from the privates to the generals — to go online and collaboratively rewrite seven of the field manuals that give instructions on all aspects of Army life. The program uses the same software behind the online encyclopedia Wikipedia and could potentially lead to hundreds of Army guides being “wikified.” The goal, say the officers behind the effort, is to tap more experience and advice from battle-tested soldiers rather than relying on the specialists within the Army’s array of colleges and research centers who have traditionally written the manuals.
I’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome.
Offers a strong recommendation to read Anne Gentle’s Conversation and Community: The Social Web for Documentation, which provides tips for incorporating wikislices, screencasts, and comment/feedback systems, into your user assistance.
If you need the collaborative aspects of a Wiki combined with DITA's modular topics and publishing capabilities, then DAISY might just be the system you need--and it's free. DAISY provides WYSIWYG editing for Wiki pages that can be combined to publish books, either in a PDF or as a single HTML page.
Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time.
Flossmanuals.net is a new wiki help authoring/publishing tool hybrid that, as far as I know, is completely unique. The site is more than a wiki. It allows groups of authors to create specific chapters independently. You can then remix the chapters into any arrangement and selection you want through a drag-and-drop interface.
As wikis mature, we’re using them for more complex business cases such as technical documentation, business analysis and project management. It’s becoming more and more interesting, if not essential, for wikis to support the import and export of content to and from other formats. Most wikis allow you to convert their pages at least to PDF and HTML. But what of other formats, and what about tools for getting content into wikis as well as out of them?
There’s a place for a lighter touch in much of the online documentation we write. It’s a delicate balance. On the one hand, it’s important that the writing style does not annoy or offend the reader and does not detract from the content. We also need to be aware of people whose first language is not the one we’re writing in. On the other hand, the occasional touch of humour or personality can focus the reader’s attention onto the page.
Much documentation and training is delivered in one direction—the writer provides content, and the user consumes it. Perhaps this is one reason that technical communicators are looking for ways to create a conversation. It’s easier to address user problems when you can ask follow-up questions and get details. In a one-way delivery, you have to hope that what you provide will cover what’s needed. In a conversation, you can constantly get more information and react accordingly. Still, in an instant message, chat, or forum conversation, it can be hard to be clear.
If we can solicit user participation in a Web 2.0 knowledge community (a volunter wiki documentation, for example), we might have a powerful means for creating high quality content. But how should this process work?
A question that technical communicators frequently ask about wikis is "How do I get the documentation out of a wiki?" A simple answer: "Don’t worry about it." Because the wiki is the delivery method.
User-generated documentation is a big issue in technical communication circles. If properly done, tapping into the knowledge of users can improve the quality and breadth of your documentation.
The importance of single sourcing the long print manual is becoming less of a demand (have you handed someone a 100+page manual lately that someone accepted with eagerness? ) I predict that in several years time, we’ll see a major shift towards web-based tools in tech comm, especially wikis.
So how did the wiki become a seemingly permanent fixture in the landscape of today’s Web? Which wikis have succeeded as technical documentation, and how can we replicate their success?
Previously I thought wikis might be limiting because the formatting options seemed so primitive--either bullets or numbers or headings, and not much else. Now I realize that I have so much to learn. I’m only on stair three of about a hundred stairs.
I have been playing around with Crucible, Atlassian’s peer code review tool. The latest version of Crucible allows you to review Confluence wiki pages. This is a new feature, so I decided to try it out. Also, I was wondering why you might want to use an independent tool to review a wiki page, when you could instead just add comments to the page or update the page directly.
Wikis are becoming entrenched in the documentation world. But there are few books that cover how to use them effectively. If you’re looking for a step-by-step guide to using wikis to create and deliver documentation, Writing in the Open isn’t it. It is, though, an interesting and potentially useful set of best practices.
The process of creating and maintaining product documentation is, like most other business processes, under pressure to reduce costs, reduce cycle times, and support companies as they compete on a more global scale; in general, the need to do more with less. How are companies to address these conflicting needs? The purpose of this white paper is to identify specific processes that can be enhanced to yield meaningful efficiencies and several strategies for attaining such improvements.
This is the fourth in a series of posts from Atlassian's Technical Writing Team focusing on using a wiki for technical writing. Last week, Sally Hawse wrote about time-saving ways to re-use content. In this post, I'll be talking about how to manage the documentation release process using Confluence.