Replies to This Discussion

Permalink Reply by Richard S. on May 6, 2011 at 5:30pm

XML to Wiki shouln't be hard, certainly no harder than PDF, but before you make that jump, consider whether a wiki is a help or a hindrance. I don't know anything about your setup or your needs, but I do wonder what benefits a wiki actually affords you if you aren't authoring in it. I'm sure you know the origin of the name "wiki." Hawaiian (wiki wiki) meaning quick. That's really the main advantage of a wiki, that everyone (you give permission to) can easily and quickly edit it in-place. If you aren't going to be authoring or maintaining docs in the wiki, then it would seem to add complexity and limitations. 

If I were editing in XML and wanting to get content on the web, I'd publish to HTML instead of wiki. That way you skip the extra (and wholly un-necessary) translation step where the wiki platform converts the wiki markup back to HTML. Also, HTML and CSS2.1 afford you a massively improved markup language relative to wiki text. Compared to current HTML, JS, and CSS, wiki text is like working in a subset of HTML back in 1995. :-)  

In other words: 

a) XML --(transform to wiki)--> Wiki text --(wiki converts to)--> HTML 

b) XML --(transform to HTML)--> HTML

• ▶ Reply

Permalink Reply by Tamsin Douglas on May 6, 2011 at 5:57pm

Richard, you are quite right. We want a searchable, highly usable content solution for our customers and we also want to give our customers an opportunity to interact with us and provide comments. But we aren't ready to jettison our CMS just yet :) We can extract to HTML, but have encountered some publishing issues.

• ▶ Reply

Permalink Reply by Sarah Maddox on May 8, 2011 at 12:27am

Hallo Tamsin

One way to use the wiki would be to allow your customers to add comments to the documentation pages. You could even allow them to create and update pages in part of the wiki, while configuring other parts to be view-only for customers.

Usually, there are two main ways the community can contribute to the wiki. One is by commenting on the wiki pages. The other is by creating and updating pages.

If your wiki is Confluence, the way to do it is using Confluence "spaces" and the Confluence permissions scheme to separate the "official" product documentation from the community-contributed documentation.

The product doc spaces could allow customers to comment on pages, but not add or update pages. This ensures that their contributions are not lost when you update the wiki from the XML source. The comments remain on the pages, but the page content is replaced with the content from the CMS.

The community spaces would be authored and maintained entirely on the wiki, by your own tech writers and the community and/or customers. We find it works really well for the tech writers to set up the structure of the space and to monitor the spaces (via watches or RSS feeds) to check that nothing goes awry. Our community authors are great at contributing good and useful content.

Is your CMS DITA-based? The WebWorks ePublisher tool does a good job of converting content from DITA to Confluence wiki, with fairly sophisticated styling and configuration options, batch processing and scheduling.

It's a good point that Richard makes, about converting from XML to wiki markup. As an FYI, Confluence is moving away from wiki markup towards storing all content in XHTML. That will make the conversion to and from XML even easier. :)

There's an open source tool for converting from DITA to wiki format, called DITA2wiki. It's a stand-alone tool that converts DITA XML documents to wiki format and uploads them into the wiki via a set of Ant commands.

• ▶ Reply

Permalink Reply by Tamsin Douglas on May 8, 2011 at 7:29am

Sarah, thanks for your thoughtful response. Indeed, we are interested in separating official product documentation from community-contributed content. This is very helpful and gives us much to think about and explore. I am sure this is not the end of this topic.

• ▶ Reply

Permalink Reply by Eddie VanArsdall on May 8, 2011 at 1:18pm

Hi Sarah,

Let me first say that I'm a fan of your blog and really appreciate your voice on the web. You always liven up a discussion.

As to your question about wiki documentation, I began writing for wikis when I was a contractor at the National Cancer Institute Center for Biomedical Informatics and Information Technology (NCICBIIT, how's that for a name?) from 2006 through early 2010. I worked primarily with the Enterprise Vocabulary Services (EVS) group, staffed by medical terminology specialists who developed the ontologies used in the NCI Thesaurus and Metathesaurus. I wrote documentation to support their work and to train new contractors. 

When I started at the NCI, we were using primarily FrameMaker and Quadralay ePublisher. I was the gatekeeper of the Frame templates. At some point, the EVS set up a wiki to encourage medical terminology experts to contribute to the development of a new terminology called BiomedGT. The wiki enabled users to search through the vocabulary and recommend changes using an online proposal submission process. The platform was MediaWiki, and the group asked me to reorganize the main pages and develop help content for users. During the process, I learned as much about MediaWiki as I could. I quickly adapted to the medium and found that it liberated me from focusing on tools and enabled me to focus more on content and organization. I wanted to set up standardized content for reuse, so I used what MediaWiki calls transclusion (basically referencing templates in a change-once/surface content approach).

At that same point, the NCICBIIT adopted Confluence as the official wiki platform for the entire organization. All of the project teams began to use Confluence for project documentation and collaboration. At the time, I was developing MadCap Flare templates for the center, so I started a Flare Knowledge Base on the Confluence wiki.

I'm no longer on the NCICBIIT contract, but I keep up with their activities. The Technical Writing team has now bypassed both FrameMaker and Flare (as far as I know) and have ported all of their documentation the Confluence wiki. I realize that I'm writing to an Atlassian employee, but I can say in all sincerity that I found Confluence robust and fun to use.

I believe that wikis are well suited to topic-based writing. They're great for collaboration and content reviews. They also provide mechanisms for content reuse. The initial challenge is learning the markup, which isn't difficult. At one point I was working on both MediaWiki and Confluence, and I had no trouble switching back and forth. (Well, maybe occasionally...) 

Cheers,

Eddie

• ▶ Reply

Permalink Reply by Sarah Maddox on May 10, 2011 at 11:22pm

Hallo Eddie,

Thank you for all that great information. Wow, you've packed a lot of experience into those times with NCICBIIT: ePublisher, FrameMaker, MediaWiki, Confluence and Flare! I envy you the experience with MediaWiki in particular. I've read up about transclusion and other extended functionality that MediaWiki provides, such as import/export for various formats. But it's not until you get down to using the features that you really know how they work and how well they work.

It sounds as if the NCICBIIT (I do love that acronym) community were keen to adopt the wiki. I know that some organisations have trouble with getting people to contribute content to the wiki, at least at first. Did the medical terminology specialists show a lot of enthusiasm for the wiki way of working, and did you have to encourage them at first?

• ▶ Reply

Permalink Reply by Eddie VanArsdall on May 12, 2011 at 5:50am

Hi Sarah,

Sorry for my belated reply. I do value those years at NCICBIIT, and I miss the dynamic learning environment. I had great experiences there. Since my initial experience with MediaWiki, I have long intended to install a MediaWiki on my server and get to know it from the ground up. I just haven't had the time.

The internal terminology specialists embraced the idea of working with the wiki, but the ramp-up time was a bit slow. Wikis were just starting to catch on, and the engineers running the wiki were still figuring things out. They gave me permission to access the main style sheet, and I was able to tweak the site's appearance. I didn't make any major modifications; I made only slight changes and spacing adjustments.

Another interesting aspect (and somewhat of a complication) was that the team was soliciting participation from outside terminology experts, who had to submit credentials before being accepted as reviewers. Some of them were a bit scared off by using the wiki. Another internal team was using the wiki for a separate terminology project, and they were the testers for the proposal system for new terminology. Let's just say that they required a lot of guidance. ;-)

• ▶ Reply

Permalink Reply by Kathleen McNiff on May 12, 2011 at 8:59pm

Hi Eddie, thanks for all this great info. It looks like you've already pioneered the path from traditional online help to wiki-based social documentation - now the rest of us have to catch up! Now, another question - some of our users need off-line help (they aren't always connected to the Internet) - can you output from Confluence to something like a .chm? 

• ▶ Reply

Permalink Reply by Richard S. on May 12, 2011 at 10:41pm

Confluence can export to .doc or PDF. Confluence does PDF export in a way that permits you to export pages as PDFs or an arbitrary group of pages (up to the whole space) as a single PDF if you want. Confluence generates PDFs of each page on save, so generating a single PDF of the whole space doesn't tax the server very hard. It also allows you to customize PDF export stylesheets, so our PDF exports look like actual company branded docs, with copyright notices, title pages, page numbers, etc.  It's a pretty good setup. I know that a lot of other tools allow PDF export. It's a pretty common feature, but I don't have as much experience with this feature of other tools.

• ▶ Reply

Permalink Reply by Janet Swisher on May 9, 2011 at 10:20am

Hi Sarah,

 

I think whether to use a customer-editable wiki for documentation depends very much on your business goals. For most companies, what's more important is the statement it makes about the kind of relationship you want to have with your customers, rather than the actual impact of outside content contributions, which tend to be fairly small. You still need tech writers to write specific topics on specific deadlines, and manage the overall architecture and structure. But the fact that customers could contribute sends a message, regardless of how much they actually do.

 

I work for an open source company (Mozilla), so using wikis for documentation is a no-brainer choice. Our attitude is that Mozilla is a community, where some members happen to get paid to work on it full time. But we try to treat all members equally. We try to do everything as openly as possible, because that's part of our mission. That doesn't mean there aren't controls. For example, changes on our end-user support wiki go through a review process before they go live, because they are seen by millions of users and they must be correct. On the developer wiki, which is what I'm paid to work on, change go live immediately, on the assumption that the developers can deal with occasional messiness.

 

• ▶ Reply

Permalink Reply by Sarah Maddox on May 10, 2011 at 11:42pm

Hallo Janet

What a great reply! I agree with every point you've raised. In particular, the need for structure, review and correctness makes the role of technical writer indispensable even on a wiki. We also monitor all updates in the product documentation spaces, so that we can correct any mistakes someone else may make.

Like you, we find that not many people outside the organisation actually make updates to the content. Almost always, the updates they do make are very valuable. And the relationships this kind of collaboration builds are invaluable.

What's more, it's fun and rewarding for the technical writers. Although we're not as good as developers at tolerating the occasional messiness. ;)

One thing I'd add is that we've learned a lot from external contributors, whether they're updating the content or just adding comments to the pages. They correct our mistakes, and even more importantly they show us ways of using our products that we had never thought of!

• ▶ Reply

Permalink Reply by Gareth Lewis on May 17, 2011 at 3:18am

Hi Sarah et al,

 

We have a slightly different approach. Our documentation is on an externally facing wiki but we provide no ability for customer update. This gives us all the advantage of using a wiki to develop and maintain our documentation but without the hassles of allowing customers to contribute (directly).

 

The other unique feature we provide is the ability for our customers to publish their own Word version using their own branded template. We provide them a Word template with our macros, they (or we) modify the Word styles to their brand, they click a button, select the articles of interest to them and hey presto - a complete user guide in their own brand for them to distribute to their users.

 

For each new release of our software and documentation, they can easily create a new version of their user guides, FAQ, etc.

 

Thanks for the topic.

 

Gareth

• ▶ Reply

• ‹ Previous
• 1
• 2
• 3
• 4
• 5
• …
• 7
• Next ›
• Page