There are two camps in technical documentation. There’s the “quick web” folks who connect easily and author easily, and then there’s the “structured quality” camp that requires more thoughtful testing and time spent on task analysis and information architecture.
The article alerts technical communicators to wiki technology, an emerging new medium that allows dispersed groups to create shared content via collaborative editing and different-time communication. Wiki-based collaborative content creation enables new communication practices and thereby challenges several assumptions of existing media choice theories.
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.
There are a wide variety of uses for Wikis and a level of interest in using them that’s matched by an extensive range of Wiki software. Wikis introduce to the Internet a collaborative model that not only allows, but explicitly encourages, broad and open participation. The idea that anyone can contribute reflects an assumption that both content quantity and quality will arise out of the ‘wisdom of the crowd.’
Like many companies, CorVu has extensive knowledge of its own products and a desire to make that knowledge available to customers. A major block to achieving that desire has been a lack of people with the time to either record the internal knowledge or to fashion the knowledge into a customer-ready format. We needed to spread the load so that a broad range of developers, tech writers, professional service consultants and others could all contribute what time and knowledge they had to a shared goal. Our hope was that a process built around several Wiki sites would facilitate this collaborative approach.
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.
What are your thoughts on whether wikis could be used for end-user technical documentation? I'd imagine that a more structured wiki based on DITA content (which may have already been created for end-users) might work well for technical documentation. Have you seen any good examples? I'd love to see a well-done example.
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.
Regardless of the overlap problem, combining a forum with a wiki and blog has tangible benefits. It helps solve the participation problem with wikis. Users are more comfortable asking a question in a forum rather than changing the original content of an article. Wiki admins can harvest information from these forum threads to strengthen the information of the wiki. Significant new wiki information should be announced to users on the blog.
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?
Rarely does anyone articulate an actual business reason why the speaker feels that a wiki isn't a worthwhile tool for collaboration in his or her environment, such as a lack of need. When I ask deeper questions, I invariably find that the objection isn't to the wiki technology itself, but instead to the concept of collaborative authoring and a perceived loss of control over the content.
Provides a recap of how the online, wiki-based Carolina Communique evolved and won an Award of Excellence in the Newsletters: Web & Online category of the 2008 APEX Awards for Publication Excellence
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.
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.
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.
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.
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.
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.
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.
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.