Re: Wiki for Customer Facing documentation?
What are your thoughts on using a wiki over a HAT or vice versa [for user documentation]?
Conclusion:
A HAT is not a Wiki and a Wiki is not a HAT, and they're not interchangeable. They each have their most excellent place, but I don't recommend a Wiki for end user docs that should be nicely navigable and maintainable.
Background and Details:
A client recently had me use TiddlyWiki to create a doc for their users. There are several issues that would be issues regardless of the wiki used:
* It's very hard to localize wiki content (at least as it is in this particular wiki). Although there are certainly localization tools that can handle content chunks in many files (I'm thinking traditional RoboHelp-style help), in the wiki it seems more difficult to isolate the applicable content from the wiki's own style sheets.
* Said style sheets *could* certainly be well-coded HTML and enable proper accessibility features, but you'll be unlikely to find them already done that way. All the ones I found had all kinds of hard-coding for everything, with the result that what I did looks fine on my monitor resolution in the browsers I happened to check, but I know full well that if someone simply increases the font size in their browser, the alignment falls to pieces in some sections.
* If the wiki you choose has style sheets, templates, and navigation aids that you like, great, but thatâs not likely. So you'll likely end up spending a lot of time with CSS and learning the nitty gritty of the wiki itself.
* If it's a good full-featured wiki, it will probably come with sufficient building blocks to provide the expected contents, index, content, search, navigation controls, etc. sections. But I had to go looking through many user groups and find plug-ins for pretty much everything beyond a basic text window display for the content.
* Unless you're deliberately making it so that users can revise the content (possibly as a shared forum with other customers), make sure that you can lock down the content -- and easily unlock it! It was easy in TiddlyWiki to hide the controls that allow editing the wiki, but then of course the editor couldn't revise it until I wrote up a cheat sheet on how to edit the wiki in a text editor to unhide the controls.
* Wikis are great at serving as a collaboration focal point, but after my experiments with creating a useful user doc, I'd say that a Wiki is most definitely not a suitable replacement for a HAT. Not that it cannot be done, but I didn't see any benefit at all. Well, that's from the content development and user usability viewpoints. The reason that the client wanted this approach are still valid:
** They wanted to make it easy for their developers to make small doc changes without having to learn how to properly use the typical tech writer authoring tools.
** They wanted a process out of their normal workflow, which involves a ton of time for even the smallest of changes because they have a multi-level writer/editor/production process.
** They wanted to be able to deliver a single HTML file that can be linked to from the SaaS app.
** They wanted something "cool", different, and innovative.
So although I liked the time I spend on this project because I got to learn much more CSS and basically play with code for a while, the result was not as effective (user friendly and maintainable) as if we'd gone with other approaches.
-Monique
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com
To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.
Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
Follow-Ups:
- Re: Wiki for Customer Facing documentation?, Tony Chung
References:
Wiki for Customer Facing documentation?: From: Matt Moore
Previous by Author:
Structured FM versus Arbortext Editor
Next by Author:
Re: Advice on software testing?
Previous by Thread:
Wiki for Customer Facing documentation?
Next by Thread:
Re: Wiki for Customer Facing documentation?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads