A wiki is a page or collection of Web pages designed to enable anyone who accesses it to contribute or modify content, using a simplified markup language. Wikis are often used to create collaborative websites and to power community websites, usually as a very simple form of content management.
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.
Alan Porter’s Wiki: Grow Your Own for Fun and Profit, published by XML Press in October 2010, provides an excellent introduction to wikis. This is a short, easy-to-read book spanning about 150 pages. Porter has a keen sense of organization and liveliness in his writing. He carries the gardening metaphor throughout the book, ending with five solid case studies and an extended response to common criticisms against wikis.
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.
Wikis are a great way to create and publish documentation online, but there are many wikis that haven’t worked. They comprise just a few pages of incomplete, out of date information. Why is that? Why do some wikis work and others just fail? Here are six key reasons.
Social technology has risen to meet this challenge over the last few years. And while there are a lot of social tools to choose from, one type stands out for this type of collaboration: the wiki. The unique communication model inherent in the wiki makes it ideal for becoming a central business tool for your entire team. The following is an overview of using wiki software for small business.
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.
An interview done by Scott Nesbitt of DMN Communications. Nesbitt talks with Stewart Mader, author of the book WikiPatterns. In the interview, Nesbitt and Mader discuss adopting wikis, how best to use them in an organization, building communities around wikis, and why Mader is so passionate about wikis.
Wiki technology creates opportunities for students in technical communication courses to gain experience with web design, writing for the web, and open-ended projects. As tools for collaborative learning, they also develop students’ project management skills and teamwork abilities. This article discusses the affordances, pedagogical foundations, and practical benefits of teaching with wikis, and suggests ways that technical communication instructors might incorporate this technology into their courses.
Craft it with care. Review it with your Subject Matter Experts. Keep it in a central location and regularly maintain and update it. Re-use it as required. This is the third of a series of posts from Atlassian's Technical Writing Team focusing on using a wiki for technical writing. The second post in this series discussed how many people still think of a wiki as an unstructured collection of pages, but in fact wikis do support structured content. In this post, I'll be talking about how to leverage that structure in support of content re-use.
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.
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.
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.
The net effect of social networking is the increasing availability of fine-grained information about locales. This information is both interesting and valuable. It is sought after by people living in these places and by advertisers who are trying to reach these people. A handful of startups are recognizing the big potential of local information - relevance. In this post we look at different aspects of the hyperlocality, from satellites to local blogs, and ponder how this information will be organized and monetized.
The notes for a presentation (titled Thinking Outside the Book: Wikis for Writing and Delivering Documentation, that discusses the whys, the tools, and the techniques of using wikis for documentation.
In the absence of safety concerns, I think that accuracy must win. Thus, as the information curator, you have a responsibility to correct inaccurate information. If the inaccuracy is truly dangerous, you may need to edit the post directly. Make sure that you disclosure what you've done with brackets.
This project began as a course project at Michigan State University for WRA 420: Content Management for Professional Writers. The aim of the project is to build a compendium of threats to the sustainability of organizational content strategies by offering an analysis that comes from our own research, and also from reviewing literature in the field of technical communication on content management. The intended audience for this project are fellow content strategists, students, teachers and research specialists who may find themselves in a position to make recommendations for improving the content strategy of organizations.
Let’s say that you’re reading a news story about a particular area of geographic conflict and you decide to investigate further. Without an encyclopedia available, as fewer and fewer of us seem to have them on hand these days, you quickly check out your handy online references. To your surprise, the article on this disputed feature seems to be an amalgamation of strongly differing opinions and ideologies, to the point where the article has been locked down from further editing. Such is the nature of the brave new world of user-generated content, where a content publisher forges a careful alliance of sorts with a wide range of contributors across very diverse locales and cultures. Depending on the intended purpose of the provided content, the end result can take on a life of its own, as it becomes the focal point for a silent yet fervent battle over “fact” and “truth” from divergent viewpoints.
We explain why we chose a wiki-based content management system (CMS) as the basis for the portal for KeyContent.org. We compare various tools and discuss other sites that have implemented similar software for collaborative solutions.
Is it possible to use a wiki for technical documentation? Yes, most definitely. I started working on a wiki two years ago, with no prior experience of wikis (apart from the occasional encounter with Wikipedia) but with plentiful experience of technical writing. I’ve learned a lot and I’d like to pass on some tips to you too.
Academic writers are used to having their ideas encapsulated and enshrined in printed text (e.g., a journal article or a book), but publishing them in a wiki strips them of this protection. What happens when strangers change our writing? Since the traditional academic publishing paradigm has not caught up with the open-editing, peer-to-peer model, are we equipped to deal with the paradigm shift that wikis represent? These are issues we consider in this short piece.