Our Wiki Quest
May 26, 2010My team is currently investigating a switch from AuthorIT to a wiki of some sort. In the running are Confluence (from Atlassian), and Mediawiki (the wiki that powers the ubiquitous Wikipedia). As I Google and tweet and pore through blog posts, I’ve been collecting a bunch of questions to answer.
Since I began Write Trends some months back, my focus has been on Thinking Outside the Book, which nobody reads anyway (sigh). In theory, a wiki seems like a great way to provide critical customer information that’s no longer married to the software release schedule. With content developed and published online, we can keep information fresh and accurate without having to wait for the next dot release.
But in practice, I’m finding it difficult to shift paradigms. There are certain features we need and without a solid understanding of the ways wikis work, I don’t know how to find the equivalent of those features in the wikis we’re evaluating.
- Version Control – Versioning seems to mean different things to different systems. We’re documenting software. Software is released in periodic increments, each release offering new features or improvements to existing ones. I want to be able to single-source topics that apply to several software releases and write new ones only where needed. I’ve figured out how to share topics in Confluence but the procedure requires that we now devise some sort of topic, or page, naming convention to distinguish topics that are universal from those that are release-specific.
- Context-Sensitive Help – We link the code directly to the appropriate HTML topic that describes a particular task, screen, or field level control. I’ve no idea how or if this can be done with a Wiki.
- Topic Status – I want two levels of access: internal and external. Internal access means everyone on my project team can collaborate on a particular topic but the general public sees none of that effort. When the topic’s been blessed by all stakeholders, I want to flip a switch and have it visible outside our firewall. I haven’t yet found this feature in our test wikis.
- PDF-ability – Shifting all documentation online has to be done in stages. We do have a customer demand for PDF versions of our guides. So far, it seems exporting the contents of our wiki to PDF is possible only with extensive CSS knowledge. Looks like I’m going back to school *grins*.
Those are the main areas of concern. We also wonder how to localize wiki topics, how to organize our wiki (by product, by release, or by manual?), how to produce PDF and XML versions of a manual without tons of extra tools and archiving (for legal purposes, we take a snapshot of the doc as it was delivered at product release).
If you have experience working in a wiki environment, I’d love to hear from you. I’ll post updates to this as we nail down some of the answers to these questions.
Write Trends 
Why are you moving away from Author-it??
We use it to publish direct to our community website (which was largely setup for that specific reason). We can publish what we want, when we want.
Yes, Wikis will allow other people to add content but there does need to be clear demarcation of “official” vs “consumer created” content, how will you handle that?
Interesting stuff though, isn’t it.
Well, we’re not sure we are moving away just yet. We’ve been asked to investigate methods to support Agile and the wiki is one. Our current process is quite linear and we’d hoped that a wiki would simplify things a bit. Jury still out on that…
For me (and I wrote about this on my blog) the topic focus that Author-it has better matches Agile development, whilst still allowing tech writers to focus on the content in a timely manner.
Well, there’s two types of content I have to deal with around here: internal and external. You’re talking about using a wiki to expose to your clients. I deployed a Trac wiki about two years ago in my company – primarily as a means of collecting content from developers. It’s for Engineering only. (The TechPubs department – meaning me – is part of Engineering). They took to it immediately, and began using it as a means of keeping their own instructions organized. Essentially, we use it like a giant bulletin board for collecting thoughts. Before the wiki, we had only Sharepoint, and the developers refused to use it. Why? They didn’t like it because it was too complicated, I think, and they really weren’t interested in learning how to use it.
Sharepoint is great for the front end, and Marketing uses it to expose content to the outside. It’s great for Marketing, because it looks good right out of the box, and you can control exposing portions of it to the outside. But for development, it was a poor solution, primarily because they WOULDN’T USE IT.
Currently, I use WebWorks Publisher to generate my content. It does export to Media Wiki, but I’ve never been able to get it to work effectively, and actually I prefer the standard HTML Help output because the search works better and it looks cleaner. This is what I ship. In Framemaker, I have full control of my conditional content for both PDF and online help generation. For the help systems embedded in the applications, I use .chm files. And for the content that needs to be accessed via web, I used HTML output. This works perfectly for me, but I’ve been doing it for over ten years. I’m only one person, and I handle about thirty manuals that have to be updated with each release (with more being added as other products are developed). I don’t have time to screw around. This is the solution that works for me.
The thought of creating a wiki and exposing it to customers is interesting, but they’ve already got PDF and online help versions of the manuals. The wiki would let them make comments and add suggestions, but the Support team has a forum for that. It seems unnecessary, and yet another thing I would have to generate with each release. Plus, I’d lose the comments each time I generated a new wiki output (using my current tools anyway). Weighing the benefits and cost, I just can’t see it as something I’d want to do. But I’m sure your situation is different. (We all have different publication needs). So I wish you the best of luck.
Thanks for your post. We have SharePoint, too, and it’s not working. All it lets you do is post documents, not actually author. We’re trying to eliminate the hands-off points in our current process: develop, review, incorporate changes, review again, approve, translate, publish and post.
There is also a drive to make information more searchable (think SEO) via Google et al, by removing it from books and posting as HTML. Right now, that’s a second publish process.
I see. Yes, on various occasions I’ve drafted in the wiki and had developers edit the content. From there I can upload it into FM and do whatever I want with it. I can also export to PDF from the wiki, but it screws up the formatting and looks pretty bad. Also, I’ve had trouble getting the engineers to use the appropriate paragraph tags. They seem to like to apply character formatting only. %@#$@!!
It sounds like TWiki would work really well for you. It allows for fine-grained permissions. It allows you to mark a certain version as “current” so it displays by default when a user visits a page even if there are newer versions. That means you can have an official version that everyone sees by default, but that the newest version is still available even before it’s been checked. It allows for single sourcing by using tags to bring in parts of different pages dynamically on page load. If you haven’t looked at it yet, I highly recommend it.
http://twiki.org/
Hm. OK. We’ll add it to our list. Thanks for the suggestion.
Hallo Patty
I’ll have a go at answering your questions. 🙂
Version control. We use spaces to manage the different versions of the documentation corresponding to the different software versions. I wrote a blog post about it, that may be helpful:
Like you, we found that we wanted to apply a naming convention to mark those pages that contain re-usable content. We decided to put an underscore at the beginning of the page titles. We also decided to keep all such pages in a location at the “root” of the space, so that they don’t by default appear in the left-hand table of contents. Here’s a post about it:
Context-Sensitive Help. We do link directly to wiki pages for our context-sensitive help. Each wiki page has a unique URL, making this easy. If you decide to use spaces in the same way that we do, and if you’d like to make your help links configurable, then you may find this post useful:
http://blogs.atlassian.com/news/2007/12/using_a_wiki_fo.html
Topic Status. We use wiki permissions to “hide” a page from external readers. We set the page permissions so that only a specific group (in our case, “atlassian-staff”) can view the page. When the page has been through review, we remove the restriction and in that way publish the page. An alternative is the “Ad Hoc Workflow” plugin, developed and written by Comalatech. A lot of people use it for exactly the purpose you’re describing. Here’s the link:
https://plugins.atlassian.com/plugin/details/142
PDF-ability. I’m guessing, from your comment about CSS, that you’ve already found Confluence’s PDF export. Confluence can export a page, a space or a selection of pages to PDF. And yes, if you need to customise the PDF file significantly, then you’ll need to use CSS.
http://confluence.atlassian.com/display/DOC/Confluence+to+PDF
There’s another plugin, called Scroll Wiki Exporter, that’s worth a look. It provides an alternative means of exporting to PDF, with a different way of customising the output:
https://plugins.atlassian.com/plugin/details/7019
I wrote a couple of posts about it too:
Other concerns. We haven’t paid much attention to localising our documentation. We organise our wiki by product, by release and by manual. So we have separate spaces for each major release of each product. Within the space, we have separate page trees for the user guide, admin guide, installation guide, etc. The Scroll Wiki Exporter plugin can help with exporting your documentation to DocBook XML.
More tips. Our “Tips of the Trade” page may have some helpful links:
http://confluence.atlassian.com/display/DOC/Tips+of+the+Trade
Please give me a shout if you’d like some more pointers. I hope all the above is helpful. 🙂
Cheers
Sarah
Sarah, thanks for your response. This is a great help!
Hi Patty,
Great to see that you are looking to use a wiki for your documentation needs.
Sarah has already covered your questions but I thought I would let you know that you can take an interactive tour of using Confluence for Technical Documentation on the Confluence sandbox here – http://atlss.in/TechDoc
You will be walked through a typical workflow that a technical writer may follow when publishing documentation on a wiki:
* Creating Drafts
* Reviewing
* Publishing
* Export
I hope this helps, Patty.
Cheers,
Matt