Alan Porter’s presentation at the Central Texas DITA User Group meeting talked about Quadralay’s use of wikis internally and their external wiki at wiki.webworks.com.
They have four wikis in operation right now, with one more to come. Back in 2003, they started their first wiki for the development team. Their company is a small one, based in Austin, and they now have absolutely every employee (with the exception of one person) having contributed to the wiki at some point or another. Currently, with their staff of 15 people, half of them contribute several times a week.
They held a brown bag training session for the whole company when a wiki for the company came out, to help people get comfortable with editing.
At their WebWorks RoundUp user forum last year, they demonstrated a proof of concept that they could take a mix of FrameMaker, DITA-XML and Word source and turn it into wiki text. I was at the demo and it has such a nice “cool” factor even if it was a simple Proof of Concept (PoC).
Another case study - they use their wiki to communicate with clients and customers on the bid and contract process, and people say it makes things go so smoothly with great communication. They use the very secure MoinMoin wiki engine and it is locked down with tight controls.
The WebWorks Services wiki:
used to create and track task tickets
offers single point of contact
facilitates interaction between customers and engineers
gives a timeline for edits on a page
gives them milestones and percent completion
In the next six months or so, they’re planning on a new doc site, docs.webworks.com (not yet live) to be authored in DITA using structured FrameMaker, then published to wikitext using WebWorks.
Lisa Dyer and Alan Porter presented at last week’s DITA Central Texas User Group meeting, and both told tales of end-user doc written and sourced in DITA, with wikitext in mind as an output. About 20 people attended and we all enjoyed the show. I wanted to post my notes to follow up, and I’ll post a link to slide shows as well.
This post covers Lisa Dyer’s presentation on a wiki sourced with DITA topics. I’ll write another post to cover Alan’s presentation.
Although, actually, first, Bob Beims shared Meet Charlie, a description of Enterprise 2.0. Seems very appropriate for the discussions we’ve had at recent Central Texas DITA User Group meetings talking about wikis and RSS subscriptions and web-based documentation.
Lisa has made her presentation available online. My notes are below the slideshow.
DITA source to wiki output case study
Lisa Dyer walked us through her DITA to wiki project. Their high level vision and business goals merged with a wiki as one solution, and Lombardi has customers who had requested a wiki. Lombardi’s wiki is available to customers that have a support login, so I won’t link to it, but she was able to demo the system they’ve had in place since July 2007.
What wiki toolset - open source or entprise wiki engine?
On the question of choosing an open source or enterprise wiki engine, Lisa said to ask questions while evaluating, such as where do you want the intellectual property to develop? Will you pay for support? Who are your key resources internally, and do you need to supplement resources with external help? They found it faster to get up and running and supported with an enterprise engine and chose Confluence, but she also noted that you “vote” for updates and enhancements with dollars rather than, say, community influence. (Editorial note - I’m opining on whether you get updates to open source wiki engines through community influence. I’m certain you can pay for support and enhancements to open source efforts with dollars.)
Run a pilot wiki project
She recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. While Michele Guthrie from Cisco couldn’t present on the panel at the last minute, she also has found that internal-only wikis helped them understand the best practices for wiki documentation.
Meet customer needs - or decipher what they want and need
Lisa said that customers wanted immediate updates, knowledge of what’s new with the product and doc (800 pages worth), and wanted to tell others what they had learned. She found that all of these customer requests could be met with a wiki engine - RSS feeds, immediate updates, and the ability to share lessons learned. At her workplace, customers work extensively with the services people and document the implementation specifically, and that information could be scrubbed of customer-specific info. They found that rating and voting features give good content more exposure. Also, by putting the information into wikis, they found that there were fewer “I can’t find this information” complaints.
Intelligent wiki definition and separate audiences for each wiki
They have two wikis - one is for end-user documentation, one is for Services information. In the screens she showed us, Wiki was the tab label for the Services wiki, Documentation was the tab label for the doc wiki. The Documentation wiki does not allow anyone but the technical writers to edit content, but people can comment on the content and attach their own documents or images. The Services wiki allows for edits, comments, and attachments. The customers and services people wanted a way to share their unsanctioned knowledge such as samples, tips, and tricks, and the wiki lets them do that. The Services wiki has all the necessary disclaimers of a community-based wiki, such as “use this info at your own risk” type of disclaimers. Edited to add: The search feature lets users search both wikis, though.
Getting DITA to talk wiki
There are definite rules they’ve had to follow to get DITA to “talk wiki” and to ensure that Confluence knows what the intent is for the DITA content. For one, when they want to use different commands for UNIX and Windows steps in an installation or configuration task, they would use ditaval metadata around in the command line text (using the “platform” property) and use conditional processing for that topic. However, because of the Confluence engine’s limitation of one unique name for each wiki article, they had to create separate Spaces for each condition of the deliverable (UNIX Admin guide or Windows Admin guide, for example). This limit results in something like 12 Spaces, but considering it’s output for several books for separate platforms, 32 individual books in all, that number of Spaces didn’t seem daunting to me. She uses a set of properties files during the build process to tell Confluence what file set to use, and what ditavals they’re seeking, and then passes the properties to the ant build task. The additional wiki Spaces does mean that your URLs aren’t as simple as they could be - but in my estimation, they’re not completely awful either.
While I was researching this blog post further, Lisa also added these details about the Spaces and their individual SKU’s (Stock Keeping Unit, or individual deliverable). “Building on this baseline set of spaces, each new SKU would add 1 to 7 spaces hosting 3 to 21 deliverables, depending on the complexity of the ditaval rules and the product. Obviously, the long pole in this system is ditaval. A more ideal implementation would probably be to render the correct content based on user preferences (or some other mechanism to pass the user’s context to the engine for runtime rendition). Or, a ditaslice approach where you describe what you need, and the ditaslice is presented with the right content. Certainly innovation to be done there.“
Creating a wiki table of contents from a DITA map
She creates a static view of the TOC from the DITA map as the “home page” of the wiki. She currently uses the Sort ID assignment a DITA map XSLT transform to generate the TOC. She said they implemented a dynamic TOC based on the logical order of the ditamap by dynamically adding a piece of metadata to each topic – a sort id using a {set-sort-id} Confluence macro. The IDs are used to populate a page tree macro (the engine involved is Direct Web Remoting, or DWR… an Ajax technology). Currently, their dynamic TOC is broken due to a DWR engine conflict, which should be fixed in the next release. In the meantime, they are auto-generating a more static but fully hyperlinked TOC page on the home page of each Space. A functional solution, not great for back and forth navigation, but it shows the logical order which is pretty critical for a decent starting point.
DITA conref element becoming a transcluded wiki article
Another innovation she wanted to demonstrate was the use of DITA conrefs output as translusions in the Confluence wiki engine, so that in the wiki, the transcluded content can’t be edited inside of an article that transcludes the content. I don’t think it quite behaved the way she wanted it to, but knowing it’s a possibility is exciting. Edited to add: This innovation really does work, Lisa simply was looking at the wrong content (she admits, red-faced.)
Burst the enthusiasm bubble, there are limitations and considerations
One limitation that I observed is that when you transform the DITA source to Confluence wikitext, there are macros embedded, so when someone clicks the edit tab in the wiki, they must edit in wikitext, not the rich-text editor, to make sure the macros are preserved. In the case of the Documentation wiki, they can instruct their writers to always use the wikitext editor. But, for the Services wiki, one attendee asked if users prefer the wikitext editor, and Lisa believes they do. Someone running MoinMoin at their office said they finally just disabled the rich text editor because they didn’t want to risk losing the “cool” things that they could do with wiki text. The problem at the heart of this issue is that if users really like the wikitext editor and do a lot of “fancy” wiki text markup (like macros), then another wiki user using the rich-text editor can break the macros by saving over in rich text. Edited to add: Lisa wrote me with these additional details which are very helpful - “actually, the macros are preserved when in Rich Text Editor (RTE) mode. the problem is that it looks ugly as heck – and if the user is not techie, potentially confusing. the RTE does add all kinds of espace characters to the content– in a seeming random way - and can negatively impact the formatting in general when viewing, but it doesn’t seem to affect our macros. However, if a user wants to use macros to spiffy up the content, then wiki markup mode is definitely recommended.”
We tackled this question and then some at the January Central Texas DITA User Group meeting. I’m a little tardy in writing up my notes and thoughts about the presentation but it went really well and I appreciate all the attendee’s participation as well. We had a high school teacher in the audience and I applaud him for wanting to learn more about DITA to pass that knowledge on to high school students.
I brought along my XO laptop since I was talking about my work with wiki.laptop.org and Floss Manuals and found some more Austin-based XO fans, so that was a great side benefit to me as well.
One of Ben’s answers to the question “What does DITA have to do with wiki?” is “Maybe nothing.” Love it!
Ben introduced another the triangle of choices - you have likely heard of “cheap/good/fast, pick two.” How about “knowledge/reuse/structure, pick one.”
I have to do some thinking about that one and his perception of the limitations and tradeoffs offered by those choices or priorities. Reuse and structure are particularly difficult to pair but also give you the most payoff. Structure and knowledge are another likely pair, but it could be difficult to find subject matter experts who are also able to organize their writing in a very structured manner, and finding writers who know DITA really well and also have specific content knowledge may also be difficult to obtain. His workaround for the difficulty you’d face while trying to come up with a structured wiki is a sluice box - where raw, unstructured data is the top input, some sort of raw wiki is the next filter, and the final tightest filter of all is a topic-oriented wiki.
My take on the question is that there are three potential hybrid DITA wiki combinations, and Chris Almond at this presentation introduced the fourth that I have seen, using DITA as an intermediate storage device, interestingly.
The three DITA-wiki combination concepts I’ve seen are:
Wikislices - using a DITA map to keep up with wiki “topic” (article) changes. Michael Priestly is working on this for the One Laptop Per Child Project (OLPC.)
DITA Storm – web-enabled DITA editor, but not very wiki-like. However, with just the addition of a History/Revision and Discussion tab, and an RSS feed, you could get some nice wiki features going with that product. Don Day had an interesting observation that sometimes when you add in too many wiki features on a web page you can hardly tell what’s content and where to edit it. I’d agree with that assessment.
DITA to wikitext XSLT transform- but no round trip, have writers determine what content goes back to DITA source. Lisa Dyer will describe this content flow in the February session.
The slides are available on slideshare.net. Here are the slides that Ben Allums, Ragan Haggard, and I used.
The January panel will talk about models for information development in a wiki framework – a couple of case studies with a demo of each system to illustrate use cases/workflow/high-level architecture. We’ll have a discussion of how these models might empower our professional community.
The February panel has some experience implementing a wiki framework for DITA and also single sourcing wikis – so they can offer a from-the-trenches look at the building blocks (transforms, feature and process requirements, lessons learned from running the project).
Ragan Haggard presented Delivering Open Source Technical Documentation via a Wiki at the San Antonio STC chapter this month, and his slides are available for download. My favorite slide is number 17 - and I have his permission to quote it verbatim here.
Why not resist this fad?
• Removing barriers to input from SMEs greatly
improves the documentation.
• These docs will get even better with feedback and
input from real users.
• We writers have no less control over the content
than before.
• A wiki has as much or as little structure as you
impose on it, the same as a book.
• I don’t think this level of collaboration is a fad.
We should have a lot to talk about and perhaps even a homework assignment between the two sessions.
Content is king. Your source content can be Word, Frame, or DITA. You can even import convert other formats such as RoboHelp to Word or Frame and go from there.
Formats are separate from content and can be customized.
Combining content is allowed and even encouraged. Mixed content is just fine.
There are great demos (over an hour’s worth) on the Quadralay web site.
ePublisher has an extendable XML adapter. This extensibility means that no matter what XML you’re putting in, ePublisher can be extended to understand it.
You can automate the dickens out of your output build processes and integrate with development’s version control systems and build with the Auto-mapper.
The WebWorks Wiki (uses MoinMoin engine if you’re wondering) has lots of information and they encourage people to contribute to it.
More note taking at sessions at the Quadralay WebWorks Publisher RoundUp. This session is with Stephanie Cottrell Bryant, author of Videoblogging for Dummies. She’s an ePublisher user who embeds video demonstrations of software within online help.
Customers love video embedded in the online help. Time saving for them, and no need to attend a training class. Her customers love it, love it, love it.
Tool kit she uses - Camtasia studio, Framemaker, and WebWorks ePublisher.
Need a script - but you might already have it, like a list of steps in a task.
Annoyance - don’t take your whole desktop while capturing screencasts. “Your desktop icons are like seeing your underwear on a clothesline.”
Also, don’t show the time of the day (like 4:00 AM) that you captured the screens, it’s sort of too much information.
Sizing of about 320 by 240 is about the right size for YouTube. Or 480×360 if you need something slight larger. If you’re delivering the video on a hard drive (installed as part of your product), you can make it even bigger. But for Internet or CHM deployment, keep it small.
Record audio first, then replay the audio while you record the video - the timing will be easier to get synched up.
She likes to use a “highlight click” feature that shows a subtle red circle showing where you click on the screen. She also modifies the cursor so that it’s larger and a yellow color while capturing the screencast.
She “cropped” out the first part of the video where she moved the screen around to the optimal location.
She recommends Flash for video output (.swf file). But if you know people are using Windows, you can make Windows Media files. If you know they’ll only be played back on an iPod, make a QuickTime file. If you want to send these video files to someone else and they don’t have Camtasia, save them as AVI - they’ll be larger files but the recipient will be able to compress them as needed and make another format. Also, any video editing software can edit AVI files.
If you want to use embedded video within an HTML file, don’t use Flash, however.
Goes into Frame, creates relative path to the movies (which is in Files folder within the ePublisher directory system), then generates the HTML using ePublisher.
She uploaded javascript to the WebWorks wiki that writes the embedded video code in on the fly, so that Internet Explorer doesn’t put a popup in front of the user, complaining about the embedded object.
In the javascript call to the video file, she’s adding an extra 10-20 pixels to the height dimension so that the player bar shows up at the bottom.
She uses conditional text in FrameMaker called “Passthrough” for all her javascript code so she can put it right into her FrameMaker file.
I’m attending as many sessions as I can at the Quadralay WebWorks User Conference - called the WebWorks RoundUp. Right now I’m listening to a great demo using WebWorks to publish Word or Frame source files to wikitext.
Start with WIF
The WebWorks wiki defines WIF as WebWorks Intermediate Format - basically their Document Type Definition. Serendipitous search engine love for WebWorks. I hadn’t realized that when you Google “WIF” you’ll find there is a lot of academic call for the Wiki Interchange Format - a lowest common denominator of wiki content exchange. WIF defines a subset of XHTML as an over-the-wire format for wiki content exchange.
Keep it simple
He’s demonstrating the concept with headings and paragraphs only, but I would imagine that ordered and unordered lists would be simple, even nested indented lists are simple enough to mark up.
No tables, and I’ll admit, they’re a nightmare to markup in wikitext, so I sure wouldn’t tackle writing the XSLT to create tables from XML to wikitext.
Graphics you could create the wikitext for the file reference, as long as you take the time to upload the graphics to the location where the wiki is expecting them.
Generate the wikitext
He’s generating wiki markup using XSLT transforms that he has already set up.
Wikitext markup is really simple, using ASCII characters such as == heading text == to mark up a heading. In this example markup, more equals signs surrounding the heading indicate a deeper nesting of headings. Two equals signs indicate a heading 2, three === indicates a heading 3. Paragraphs are often not marked up at all, making them the simplest output of all. Refer to the wikimatrix.org’s markup comparison tool for more examples.
I would have liked to see examples of links and image references created, but this was an hour demo after all.
Put wikitext into your wiki
Finally, he’s copying and pasting the marked up wikitext into his wiki. For a long article where one page is one article, this approach makes a lot of sense. I could use a tool like this for the One Laptop Per Child project, where we have a Simplified user guide all in one wiki page. Each section is editable just because the wikitext is marked up using ==section name==, which is the markup for that particular wiki (MediaWiki).
And in his keynote the following day, Ben Allums demonstrated that he could publish to the wiki itself. Now THAT is an exciting development. I’ll dig deeper into the guts of that and report back.
Scenarios for converting to wikitext
I can think of plenty of scenarios for using this conversion process. Let’s say you need a hundred page user manual put into wiki format. This type of conversion would give you a huge leg up on the pre-population of a wiki with a user guide that is already in FrameMaker or Word. I would imagine you could somehow automate the webform population. For example, use IBM’s freely available CoScriptor to record the process where you create a new wiki page, then just run the CoScriptor script and paste when needed, then run another script that renames the new wiki page.
Because you can also publish directly to the wiki, but it seems to be in a way that doesn’t touch what’s already there, this method is a great way to continually update your wiki with fresh content.
Another great use of creating wikis with a conversion process would be for API documentation, especially if you already had a large body of work in a wiki. Let’s say you’re using DITA as your source file for your API, convert new portions to wikitext.
I’ve been diving deeper into social media and its use to make connections via email and also in real life. For example, I had a great lunch conversation with Alan Porter at Quadralay a few weeks back. We made the connection thanks to a comment conversation on Tom Johnson’s blog, I’d rather be writing. I had asked Alan how Quadralay responded to some constructive criticism about their product wiki, and he said he talked to the blogger at the next conference they both attended and had a really nice conversation, clearing up the confusion. That interpersonal approach works well because it forges the relationship rather than simply connecting blog posts. It’s using social media to make that next connection meaningful.
My next question was, why don’t you have a corporate blog where you could respond to the blogger via comment on the very blog post that could be interpreted as critical, therefore using the blog medium that the blogger was using? Then, when my search about WebWorks wiki came across this post, I could have had Quadralay’s response to read along with the post.
My theory is that the Adobe Technical Communication blog has been set up for this very purpose. In my opinion it’s an effective Public Relations move, because you are creating the record that you want to be available for years to come when the search term is found again. But I’m sure Adobe’s team has to prove that the time spent blogging and the money spent on the blog infrastructure and tools was money well spent.
Effectively, any blogger must prove that there would eventually be a return on that investment of time and money. I think that the return could occur months or years later when someone like me is researching their next toolset. It’s the influence that the bloggers can wield, which then translates to investment, which I discussed in my prevous post about the Reach and Influence of blogging.
Currently, I get paid with a pseudo-currency of community connections more than any actual currency payoff with my blog, and I like it that way. My blog is driving the boringness out.
I’ve been researching an article for STC Intercom about wikis and technical documentation as discussed in my previous post. In about two years of my interest in the topic, I have only discovered a handful of examples of wikis used for end-user documentation for a technical product. And sometimes I even stretched the term “technical product” to include all of eBay. Heh.
If you’re also interested in wiki research, I have also been compiling bookmarks of blogs or websites that comment on wiki use on del.icio.us too at http://del.icio.us/annegentle/wiki.
Anyway, here’s a list of the ones I’ve found as good examples so far, but my criteria are loose and fast, such as recognizable products or geeky products. I’m sure there are more, and this list of the top 57 wikis based on popularity offers an even longer list.
But instead of soliciting more examples, I want to ask a few more questions myself. How many of these wikis would I use to get an answer to a question? Probably all of them. Now, how many wikis have I contributed to? How about you? If you haven’t ever contributed to a wiki, why not? If you have, tell us which one, and what motivated you to contribute?
Anne is a senior technical writer at Advanced Solutions International. Read 
