Will Wikis make the traditional forms of documentation obsolete?

Hie People, 

I have started working on wiki lately and have fallen in love with it. My organization has made a collective decision of moving all end-user documentation on wiki. While we haven't yet stopped sending the PDF's we have certainly stopped making framemaker books. The content available on wiki is everything. While it has certainly helped us get the user/client comments and feedback faster than earlier versions in frame books, I am not really certain if we will stop using the earlier formats altogether.

Do you believe that moving to wiki will make the traditional formats of user documentation obsolete?

Views: 1335

Reply to This

Replies to This Discussion

I  think not. Documantation "on paper" is a document, that application works "in this way". If it doesn't,  customer can report a bug. If we have an online (so easy to change on software producer side) documentation, there is no point to say "it works wrong", becouse producer can change documentation to be the same  to an application, not the other way around.


I don't understand your statement. A documentation can always be wrong without the product having any bugs. The product is developed first, then the manual. The benefit of online documentations suchs as wikis is that it allows updating the technical documentation very easily and quickly. You can get feedback by other users/authors who have access to the wiki.

Don't get me wrong, I don't think that a wiki can replace FrameMaker documents. But going with the new media is definitely something one should consider additionally to traditional publishing.  There are online help formats such as Reverb where you can take your FrameMaker or Word files and put them into a user- and mobile-friendly layout. Users can give their feedback directly to the authors to help improve the documentation and/or product. Same with Adobe AIR Help.

I think a wiki is a nice way to exchange and store information, for example it is a great tool to review and collectively edit the technical documentation before putting it to its final format.

Wikis aren't exactly new. I first used one for work in 2000, and they were around before I started using them. If you examine the history of them, they came about at a time when lots of folks were beginning to use the web to share documents. In those days, getting soemthing on the web (especially in a corporate environment) often meant that the user wrote html pages and used an ftp client to put pages a server's htdoc root. This meant that folks had to know a little HTML, and they needed machine/NIS accounts to ftp things over. 

Wikis were an answer to both of these problems at the time. They gave a simpler (or at least reduced) markup language than HTML, and wikis could give users app-level accounts instead of machine/NIS accounts, which was a big upgrade to security. 

More than a decade later, wikis still usefully satisfy that basic need of giving  folks a place to maintain simple, multi-author documents. I would argue that blogging platforms have done more to change the way folks write than wikis have, but they serve a slightly different usage model.  

So... are wikis a game changer? No, not really. They're a useful tool on the path of evolution of tools. I use a wiki every day for work, and while I like much of what it offers, I hope the evolution continues, and that authoring tools continue to get better; a lot better.  

I'd also make the claim that wiki isn't a "form of documentation" at all. It's a tool authors use to create a form of documentation. In other words, you may write in wiki markup, but the tool translates that to an output medium for you. For most wikis, the primary output is HTML. And to the browser, it's just html. The browser doesn't care what middleware was involved to get it to HTML.

Last thought... way back in the day, wiki was created to be a simpler markup that provided a subset of what HTML was capable of. The general idea was to keep hypertext aspects of the web, but make authoring and linking "quicker" for authors (wiki being the Hawaiian word for quick). Authoring platforms, whether they call themselves wikis or not, have generally found better ways than wiki markup to provide ease of authoring and linking. So while the idea of a wiki lives on in many products, the wiki markup aspect of wikis is headed for extinction.   

If then, what wikis provide is an easy means of authoring and linking, the lines between wiki platforms, blogging platforms, doc management platforms, and collaboration platforms are quite blurred. The next big winner will probably be the one that makes an in-browser rich text editor that's really good. Sharepoint 2011 is getting there, but it's still fairly limited for average users, and highly limited for doc professionals.   

Do you mean strictly within the software realm or are you asking with regard to any kind of user documentation?

Hey Milan, I work in IT, so I am referring to the documentation in IT. I do not things wikis will work for a hardware selling company, or a manufacturing industry or something like that. I mean documentation in the software realm :)

I believe that standalone topics richly linked to ancillary resources are a more natural form for providing technical help than a long-form narrative book. We now have the meant to produce and deliver such topics effectively, so I expect the migration to topics to continue. Whether wikis are going to prove to be the best form for creating a collection of richly linked standalone topics, though, is very much something that remains to be seen.

In the first stage of a transition to a new form and a new delivery media, people are very much drawn to products with low start-up costs. Wikis fit that bill admirably. Over the long haul, though, the tool with the lowest start-up costs can turn out to have the highest maintenance costs. A few years down the road, wiki shops may feel the need to move to a more structured format with better management potential.

I would expect to see technical communicators serving curatorial functions as wikis--and a number of other new media practices--become increasingly common places for users to turn to for user assistance. Implied in this are two follow-on questions: to what extent will corporations support this shift? And how well-prepared are graduate and undergraduate programs for this shift in function as we train next generation technical communicators? This is certainly a time to be nimble!

I've used wikis a lot in various documentation endeavours. I like what they can offer, but I don't think they will replace other forms. I think they have a lot of potential, especially in internal technical documentation.

We use both, and find advantages and disadvantages to both wikis and hard copy. It's great to update content on the fly with wikis, but you might see "squeaky wheel" scenarios, where a single person's opinion (or often, lack of comprehension) derails the overall effort to present accurate, relevant information. But obviously with hard copy, if one UI update goes under the radar, suddenly your public-facing collateral is inaccurate.

I think we have to recognize that every form of communication comes with an implicit contract between the writer and the reader. Reader and writer have to understand that contract in the same way for any media to be used successfully.

In the case of a book, the contract between reader and writer is that the content in the book has been thoroughly vetted and is authoritative and permanent. Both parites understand this, so all is well.

In the case of a product support forum, the contract between reader and writer is much less strict. An employee posting an off-the-cuff suggestion on the forum is not generally taken to be speaking finally and authoritatively for the entire organization. Rather, they are offering an immediate suggestion in the hope that it will be helpful. Both parties understand this, so all is well.

But with a Wiki, it is not so clear what the contract is between reader and writer. The original wiki concept was actually that of a profoundly different contract which stipulated that everyone was a reader and everyone was a writer, and that anyone could edit or refactor any part of the wiki at any time. Everyone who reads the wiki knows that that is how wikis work, so all is well.

When we talk about using a Wiki for documentation, though, it is not at all clear what contract between writer and reader is implied. There is certainly at tendency among tech writers to assume that every form of communication they work on is issued under the same contract as a book. But is that appropriate? And is that what readers understand when they presented with a documentation Wiki.

I think this is perhaps the biggest issue that groups need to sort out when they decide to use a wiki for documentation. Do they mean a real wiki? Or do they mean a standard book that happened to have been written using a wiki editor? And if the latter, why describe it to the reader as a wiki at all? Isn't that rather like referring to docs written in FrameMaker as FrameMaker docs?


For a company which is setting up a Tech writing Team (say 5-10 writers), what help authoring tools do you suggest(cost included) and why?

Will wiki-based documentation fit the bill?

My central concern about Wikis, a concern reinforced by talking with people who are using Wikis in their documentation infrastructure, is the difficulty of integrating Wiki-based content into a larger content management and re-use strategy.

By enabling a single body of coherently structured and written content to be packaged and delivered in multiple output formats, single-sourcing was and is an important foundational building block of technical communications strategy. As best I can tell, Wikis today remain "a thing apart" in the sense that all variants break, to some greater or lesser extent, the single-sourcing mode of content creation and management.

Some Wikis are better than others at permitting content to be imported and exported. But as best I've been able to learn, ALL Wikis require some non-trivial amount of preparation and workflow design to make them "play well with others", including but not limited to scripting, use of limited-functionality plugins or converters, tagging or re-tagging, and more.

Another potential concern is localization. I'd be very interested in learning what sorts of workflows are required to translate Wiki-based content. Additionally, if one of the objectives of Wikis is to enable user contributions and refinements to be made to content, how are user contributions synchronized between two or more localized Wiki instances?

There's no question that Wikis are useful and important platforms for presenting information that can then benefit from reader-provided commenting and refinement. But my research (which I'm the first one to admit isn't authoritative) leaves me concerned that a great deal of care and effort is required to prevent Wiki-based content from becoming its own separately developed and managed "silo" that creates as many problems as it potentially solves…



© 2017   Created by Arnold Burian.   Powered by

Badges  |  Report an Issue  |  Terms of Service