Baselining Documentation on a Wiki

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.

DMN Communications (2008). Articles>Documentation>Technical Writing>Wikis

Can Lightweight Markup Languages Be Used for Documentation?

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.

DMN Communications (2008). Articles>Documentation>Programming>Wikis

Is a Documentation Wiki in your Future?

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?

Hackos, JoAnn T. Center for Information-Development Management (2007). Articles>Documentation>Content Management>Wikis

Musings on User-Generated Documentation

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.

DMN Communications (2008). Articles>Documentation>Technical Writing>Wikis

Wiki-fying Docs: Is Using Customer-Accessible Wikis for End-User Documentation Gaining Momentum?

While the effort to provide more interactivity and power to the end-user seems to suggest that we open up a wiki to allow them to add and edit content, the basic idea of a set of edited documentation is now challenged with a social network of participating customers, all of whom may now edit, add, and delete content. How social can you go? This article is an attempt to look at the process of evaluating the use of a wiki for end-user documentation, if such a thing can exist. Are the two types of customer content--wikis and end-user documentation--mutually exclusive?

Albing, Bill. KeyContent.org (2007). Articles>Documentation>Wikis>Social Networking

Wikis for Supporting Distributed Collaborative Writing  

Wikis allow distributed teams to collaboratively write and edit documents through the Internet in a shared online workspace, without the need for special HTML knowledge or tools. The flexibility of wiki technology is a boon for increased cooperative work on large team projects. However, wiki technology also complicates notions of usable design as the information architecture of a wiki site may be created on the fly by all participants rather than by a dedicated technical communicator. This paper describes the basic technology of wikis, some advantages and disadvantages, and areas of concern with regard to information design.

Wei, Carolyn, Brandon Maust, Jennifer Barrick, Elisabeth Cuddihy and Jan H. Spyridakis. STC (2005). Articles>Documentation>Collaboration>Wikis

FLOSSmanuals.net: A New Wiki Help Authoring/Publishing Tool Hybrid

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.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Documentation>Help>Wikis

Building a DITA-Wiki Hybrid  

Learn about theoretical and practical examples of merging DITA (Darwin Information Typing Architecture), a structured authoring methodology, and wiki’s freeform authoring and editing capabilities.

Gentle, Anne and Lisa Dyer. Intercom (2008). Articles>Documentation>Technical Writing>Wikis

The "Quick Web" for Technical Documentation  

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?

Gentle, Anne. Intercom (2007). Articles>Documentation>Technical Writing>Wikis

Going from Word to Wiki

One writer's experiences and thoughts about moving content from Microsoft Word to a wiki.

DMN Communications (2008). Articles>Documentation>Wikis>Case Studies

Why Wikis Won't Kill Technical Writing

Many people have predicted that wikis will replace traditional help in the future. Ok, I can buy that. But I've also heard that technical writers will surrender content control to SMEs and users, and will move into other roles such as merely editing wiki content, or switching to programming, training. Sorry. I just can't see that happening. In the world of wikis, technical writers will still be kings of content.

HelpScribe (2008). Articles>Documentation>Technical Writing>Wikis

Web 2.0, Wikis, and Books    

The founder of FLOSS manuals discusses the intersection of books and Web 2.0 and the continuing evolution of publishing and technology.

Hyde, Adam. Intercom (2009). Articles>Documentation>Content Management>Wikis

Informal Help via Electronic Conversation Can Lack a Certain Professional Quality

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.

Gryphon Mountain (2009). Articles>Documentation>Wikis>Social Networking

Reviewing Wiki Documentation via Crucible

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.

Maddox, Sarah. ffeathers (2009). Articles>Web Design>Documentation>Wikis

Strategies for Driving Down the Cost of Product Documentation: Wikis and DITA  

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.

Info Pros (2007). Articles>Documentation>Wikis>DITA

Wiki-fying Docs: Is Using Customer-Accessible Wikis for End-User Documentation Gaining Momentum?

While the effort to provide more interactivity and power to the end-user seems to suggest that we open up a wiki to allow them to add and edit content, the basic idea of a set of edited documentation is now challenged with a social network of participating customers, all of whom may now edit, add, and delete content. How social can you go? This article is an attempt to look at the process of evaluating the use of a wiki for end-user documentation, if such a thing can exist. Are the two types of customer content — wikis and end-user documentation — mutually exclusive?

Kent, Betsy and Bill Albing. KeyContent.org (2009). Articles>Documentation>Content Management>Wikis

Daisy: WYSIWYG Wiki for PDF Books  

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.

Armstrong, Eric. Sun Microsystems (2008). Articles>Content Management>Documentation>Wikis

The Medium is the Delivery Method

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.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Content Management>Wikis

The Atlassian Contributor License Agreement Comes of Age

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!

Maddox, Sarah. Atlassian Blog, The (2009). Articles>Documentation>Wikis>Case Studies

Care to Write Army Doctrine? With ID, Log On

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.

Cohen, Noam. New York Times, The (2009). Articles>Content Management>Documentation>Wikis

Getting Content Into and Out of Wikis

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?

Maddox, Sarah. ffeathers (2009). Articles>Content Management>Wikis>Documentation

I Got Dragons and Tweets in My Documents

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.

Maddox, Sarah. ffeathers (2009). Articles>Documentation>Wikis>Case Studies

Wiki as Forum, FAQ, HTML Editor, XML Editor, or CMS?

A wiki can be a Frequently Asked Questions repository, much like the knowledge bases in their heyday in the late 80s. My favorite line from the blog entry has to be its closer: 'It's about a different way of thinking around how to interact with the community.' And that is what I have explored with my wiki presentation, about how to build community with a wiki and be an active member of that community. But what are other uses of the wiki?

Gentle, Anne. Just Write Click (2007). Articles>Documentation>Content Management>Wikis

A Few Surprises in Using a Wiki for Documentation

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.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Content Management>Wikis

Consistency and Community-Generated Content

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.

Gentle, Anne and Janet Swisher. Just Write Click (2009). Articles>Documentation>Style Guides>Wikis