TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Wiki for Customer Facing documentation? From:Tony Chung <tonyc -at- tonychung -dot- ca> To:Monique Semp <monique -dot- semp -at- earthlink -dot- net> Date:Wed, 3 Aug 2011 08:59:56 -0700
To add to Monique's illustrations: Any process that involves a wiki
would tend to be controlled more by policy than technology. Where a
HAT implements constraints out of the box, a wiki can only do so by
design.
For instance, Second Life uses MediaWiki to develop their help system.
Their process involves freezing the content manually for translation.
-Tony
On 2011-08-03, at 7:31 AM, Monique Semp <monique -dot- semp -at- earthlink -dot- net> wrote:
>> 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 tonyc -at- tonychung -dot- ca -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/tonyc%40tonychung.ca
>
>
> 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
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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-
