Comments on: Are structured authoring and wiki opposing forces?

By: Odds and Ends | Idiotprogrammer

Odds and Ends | Idiotprogrammer — Sat, 27 Oct 2007 21:45:34 +0000

[...] technical writer who runs the Just Write Click blog (clever title by the way). Here’s her interview about using wikis for documentation. (Here’s another thoughpiece about wiki documentation and a link to a Harvard Business school [...]

By: annegentle

annegentle — Tue, 16 Oct 2007 01:23:22 +0000

Great comments, all. I am especially intrigued by the wiki2dita button – that seems like a good direction to go, capture the difficult to get info, but then clean, index, and semantically tag it to make it DITA-worthy.

Gordon, I’m not sure if a layered approach is the preferred method, but it might be the only way to get otherwise reluctant non-tech writer contributors to put their thoughts or ideas into a wiki. I guess that the content is king, after all, it’s just us tech writers that want to take the content to the next level and protect it as a business asset and tag it and get it into other formats (like print.)

And Avi, great point about how the added-value we writers bring is that we can write, and write well. Lately I’ve been lamenting my fading CSS skills, but I can still write.

By: ghkrause

ghkrause — Mon, 15 Oct 2007 21:35:15 +0000

I come from an engineering background with a drive to raise my voice and tell others what I know and think. But there are many engineers I know that prefer to sit on their knowledge. Some get tempted to write a Wiki article but it’s a pain to let the words go off into corporate playground. For those who like wiki but will not be technical writers we added a wiki2dita button to the system and wait for some articles to become mature enough to be transfered to the technical documentation domain. The import needs cleaning, indexing and tagging. If everything is fine the wiki article gets replaced by a link to the DITA CMS.
This approach seems to be the opposite direction but it seens to serves as information development tool …

By: avi

avi — Mon, 15 Oct 2007 09:07:22 +0000

Wiki articles can be easily structured (see Wikipedia, for example). The greater problem, IMHO, is that you just can’t assign a writing task to someone that is not a writer. Our entire profession is based on the fact that people don’t like to write. (enough people to make a business case for us, writers.) There has to be a way to attract techical people to write, but asigning them with tasks has never worked for me.

By: ffeathers

ffeathers — Sat, 13 Oct 2007 03:11:38 +0000

Hi Anne, Very interesting ideas. I particularly like the idea of putting a DITA structure behind a wiki – though for most users it would have to be hidden (scary). So we’d have a sort of object-oriented wiki page.

And it gets even more interesting when combined with your use-case: asking field-operators to add scenarios which can then be collated into some sort of ‘book’ or other compilation.

Some wikis allow you to create a template for a page. Wikipatterns.com has a very simple one – when you add a page, the new page starts out with default content which you can choose to adapt or delete.

If the scenario-authors followed the template, and if DITA or an XSLT conversion engine lurked in the background, we’d probably end up with some good building blocks.

I’ve recently started using a wiki for technical documentation, and I’m really enjoying the wiki’s plus points as well as the challenge of finding work-arounds for its less techpub-friendly characteristics.

Great post!
Sarah

By: one man writes » Recently Read

one man writes » Recently Read — Fri, 12 Oct 2007 10:20:44 +0000

[...] fascinating post and has certainly got “ideas popping and synapses firing” in my brain. Are structured authoring and wiki opposing forces? is a question which is going to keep me occupied for a [...]

By: Gordon

Gordon — Thu, 11 Oct 2007 20:03:53 +0000

So, just so I can continue to boggle my head with his, a layered approach to authoring would be the preferred route?

I agree about the two main types of author, and your diagram neatly fits the point I was going to make, namely that an individual will slide to and fro along the scale, depending on what they are working on, why they are doing it and so on.

And I’ll need coffee before I come back to this..

By: danortega

danortega — Thu, 11 Oct 2007 16:19:56 +0000

It’s an interesting little conundrum, isn’t it? I think part of the reason we’ve been pushing this concept as something that could show a quick value to the wiki sponsor is the operating context. The example of a field service technician is someone adding specific information on a transactional event that is already part of a producion workflow. This is not the traditional free-flowing wiki paradigm that most people are used to. If the authoring context is tightly contained (say what you want, as long as it’s about this specific topic), this should work. If authors have the ability to choose topic references when they create the content (maybe as part of a pull-down menu), the content becomes self-categorized. It would still need to go through an approval cycle, but having the contextual framework would make that process a lot easier and faster.