<?xml version="1.0" encoding="UTF-8"?><rss version="2.0"
	xmlns:content="http://purl.org/rss/1.0/modules/content/"
	xmlns:dc="http://purl.org/dc/elements/1.1/"
	xmlns:atom="http://www.w3.org/2005/Atom"
	xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
		>
<channel>
	<title>Comments on: Contributing to wikis as a technical writer</title>
	<atom:link href="http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/feed/" rel="self" type="application/rss+xml" />
	<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/</link>
	<description>Documentation as conversation</description>
	<lastBuildDate>Thu, 11 Mar 2010 04:44:21 +0000</lastBuildDate>
	<generator>http://wordpress.org/?v=2.9</generator>
	<sy:updatePeriod>hourly</sy:updatePeriod>
	<sy:updateFrequency>1</sy:updateFrequency>
		<item>
		<title>By: The Content Wrangler &#187; Blog Archive &#187; Anne Gentle vs JoAnn Hackos: Is There a Documentation Wiki In Your Future?</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-35644</link>
		<dc:creator>The Content Wrangler &#187; Blog Archive &#187; Anne Gentle vs JoAnn Hackos: Is There a Documentation Wiki In Your Future?</dc:creator>
		<pubDate>Mon, 14 Sep 2009 12:46:00 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-35644</guid>
		<description>[...] know what they decided, but I do know this: wikis are not too far in the future for many of us, as this list shows&#8212;they are here [...]</description>
		<content:encoded><![CDATA[<p>[...] know what they decided, but I do know this: wikis are not too far in the future for many of us, as this list shows&#8212;they are here [...]</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: annegentle</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-33</link>
		<dc:creator>annegentle</dc:creator>
		<pubDate>Thu, 06 Sep 2007 14:46:16 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-33</guid>
		<description>Scott, I love the &quot;content manufacturing process&quot; description.

Shannon and Scott both, I&#039;m reminded of a visual image of a crowded, loud newsroom where the journalists are writing their stories under the pressure of hitting their deadlines and also pitching stories to the editor for inclusion, and the jostling for the front page story. While that&#039;s an old media description, its useful for describing the evolution that Shannon has witnessed. Unfortunately the wiki community can&#039;t fire the editor or editors like a newspaper could.

You&#039;ve both hit on a crucial aspect of wikis - I believe the successful wikis are managed by an editor or editorial board who maintains the voice for all the submitted articles - much like a successful newspaper&#039;s editor ensures their journalists&#039; submissions are keeping with the paper&#039;s voice. However, the balancing act lies with the community&#039;s success, not the editor&#039;s, necessarily. Fascinating.

Exciting times, these. Thanks so much for commenting.</description>
		<content:encoded><![CDATA[<p>Scott, I love the &#8220;content manufacturing process&#8221; description.</p>
<p>Shannon and Scott both, I&#8217;m reminded of a visual image of a crowded, loud newsroom where the journalists are writing their stories under the pressure of hitting their deadlines and also pitching stories to the editor for inclusion, and the jostling for the front page story. While that&#8217;s an old media description, its useful for describing the evolution that Shannon has witnessed. Unfortunately the wiki community can&#8217;t fire the editor or editors like a newspaper could.</p>
<p>You&#8217;ve both hit on a crucial aspect of wikis &#8211; I believe the successful wikis are managed by an editor or editorial board who maintains the voice for all the submitted articles &#8211; much like a successful newspaper&#8217;s editor ensures their journalists&#8217; submissions are keeping with the paper&#8217;s voice. However, the balancing act lies with the community&#8217;s success, not the editor&#8217;s, necessarily. Fascinating.</p>
<p>Exciting times, these. Thanks so much for commenting.</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: Shannon Greywalker</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-35</link>
		<dc:creator>Shannon Greywalker</dc:creator>
		<pubDate>Tue, 04 Sep 2007 15:43:06 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-35</guid>
		<description>I&#039;d also like to point out that over time, wikis tend to evolve a rather harsh and ruthless zeitgeist. Many wikis include a disclaimer on their edit pages that essentially says &quot;do not submit your contribution unless you are prepared to have it ruthlessly edited&quot;.

What tends to happen over time is that the regular community of &quot;editors&quot; (the people who feel some sense of ownership for the wiki content and who frequently contribute or revise articles) become quite harsh and abrasive.  Talk pages become filled with tersh, harsh, abrasive language that often belittles contributers.

As a result, wikis seem prone to developing an exclusive &quot;in-crowd&quot; who begin to shape the wiki for better or worse, and who drive away newcomer contributers who aren&#039;t capable of fitting in with the zeitgeist.</description>
		<content:encoded><![CDATA[<p>I&#8217;d also like to point out that over time, wikis tend to evolve a rather harsh and ruthless zeitgeist. Many wikis include a disclaimer on their edit pages that essentially says &#8220;do not submit your contribution unless you are prepared to have it ruthlessly edited&#8221;.</p>
<p>What tends to happen over time is that the regular community of &#8220;editors&#8221; (the people who feel some sense of ownership for the wiki content and who frequently contribute or revise articles) become quite harsh and abrasive.  Talk pages become filled with tersh, harsh, abrasive language that often belittles contributers.</p>
<p>As a result, wikis seem prone to developing an exclusive &#8220;in-crowd&#8221; who begin to shape the wiki for better or worse, and who drive away newcomer contributers who aren&#8217;t capable of fitting in with the zeitgeist.</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: Shannon Greywalker</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-34</link>
		<dc:creator>Shannon Greywalker</dc:creator>
		<pubDate>Tue, 04 Sep 2007 15:28:55 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-34</guid>
		<description>I have contributed to many wikis of the WikiMedia and Drupal variety.  Some of those wikis comprise millions of users.  Some of them have formal editorial oversight and formal written arbitration policies and some are completely free-for-all with no oversight whatsoever.

I have witnessed some serious &quot;revision wars&quot; where matters of ownership and disagreements over correct content have occurred.  I have also witnessed many well-meaning revisions by contributors who frankly have no business attempting to write content for a wiki, because they either cannot write well or because they are entirely incorrect.  I have seen well-written, concise articles turned upside down by a single well-meaning contributer who thought they were improving the article but instead they were making it literally 500% longer and full of extraneous detail that had no place in the context being discussed in the original article.

I have seen the corporate owners of a wiki absolutely refuse to get involved in editorial disputes, saying &quot;you work it out amongst yourselves&quot; and refusing to ban aggressive contributers who stubbornly put orginal bad content back when it is revised to be less bad.

My view of wikis these days, especially when used in a corporate context, is that if the wiki does not have formal oversight mechanisms in place, the wiki is essentially corrupt, untrustworthy, and not worth my time as a user nor as a contributor.  To be successful, a wiki must have the following attributes:

* A formal written set of policies about ettiqutte and arbitration.
* A formal arbitration committee who is given the time needed to perform arbitration duities.
* Active moderators who will quickly ban problem contributors on the say-so of the arbitration committee (if they don&#039;t actually give the arbitration committee such powers to begin with).</description>
		<content:encoded><![CDATA[<p>I have contributed to many wikis of the WikiMedia and Drupal variety.  Some of those wikis comprise millions of users.  Some of them have formal editorial oversight and formal written arbitration policies and some are completely free-for-all with no oversight whatsoever.</p>
<p>I have witnessed some serious &#8220;revision wars&#8221; where matters of ownership and disagreements over correct content have occurred.  I have also witnessed many well-meaning revisions by contributors who frankly have no business attempting to write content for a wiki, because they either cannot write well or because they are entirely incorrect.  I have seen well-written, concise articles turned upside down by a single well-meaning contributer who thought they were improving the article but instead they were making it literally 500% longer and full of extraneous detail that had no place in the context being discussed in the original article.</p>
<p>I have seen the corporate owners of a wiki absolutely refuse to get involved in editorial disputes, saying &#8220;you work it out amongst yourselves&#8221; and refusing to ban aggressive contributers who stubbornly put orginal bad content back when it is revised to be less bad.</p>
<p>My view of wikis these days, especially when used in a corporate context, is that if the wiki does not have formal oversight mechanisms in place, the wiki is essentially corrupt, untrustworthy, and not worth my time as a user nor as a contributor.  To be successful, a wiki must have the following attributes:</p>
<p>* A formal written set of policies about ettiqutte and arbitration.<br />
* A formal arbitration committee who is given the time needed to perform arbitration duities.<br />
* Active moderators who will quickly ban problem contributors on the say-so of the arbitration committee (if they don&#8217;t actually give the arbitration committee such powers to begin with).</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: Scott Abel</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-32</link>
		<dc:creator>Scott Abel</dc:creator>
		<pubDate>Sat, 01 Sep 2007 14:36:50 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-32</guid>
		<description>I don&#039;t contribute often to wikis, but I would if I had something valuable to add or if I had a business reason for doing so. That said, I use wikis often and find them very valuable, thanks to those who do contribute content.

From my vantage point, it is important to note that many of the so-called &quot;problems&quot; with wikis are not problems with the wiki technology, but instead are problems with leadership and governance during this time of change.

For instance, it is simply not true that anyone can edit a wiki -- yet many believe so. Today&#039;s second-generation wikis provide various levels of access control, so we can create different levels of editing permission and assign each user with appropriate permissions (some users will be able to edit, but their edits will not go live until a user with approval permissions approves the content). So, what&#039;s the real problem?

The problem I see as most important to recognize is that knowledge workers have yet to understand their place in the content management life cycle. And, they often have a surprising view of who &quot;owns&quot; the content. For instance, regardless of whether you are using a wiki or not, you likely don&#039;t &quot;own the content&quot; you are creating, even if you are using MS Word and storing your files in a folder called &quot;My Documents&quot;. Your role is not one of artist (although many writers see themselves that way). Instead, you are part of a content manufacturing process, that, chances are, don&#039;t work very efficiently, regardless of what software tools are employed. If efficiency and business value were at the center of our decision-making, we simply wouldn&#039;t be in the situation we are today - struggling to admit our content has value and therefore should be managed as a business asset.

I could certainly write a book about these issues, but suffice it to say that our primary obstacle is not the wiki. It&#039;s the changes content creators must make in their attitudes and the way in which they work.  Change is difficult for most, but not impossible. I think we are in the midst of a major shift in the way writers work. The tools we use will change and help us to become more efficient.

It should be interesting to see what happens over the next few years. I see a wiki in my future. What about you?</description>
		<content:encoded><![CDATA[<p>I don&#8217;t contribute often to wikis, but I would if I had something valuable to add or if I had a business reason for doing so. That said, I use wikis often and find them very valuable, thanks to those who do contribute content.</p>
<p>From my vantage point, it is important to note that many of the so-called &#8220;problems&#8221; with wikis are not problems with the wiki technology, but instead are problems with leadership and governance during this time of change.</p>
<p>For instance, it is simply not true that anyone can edit a wiki &#8212; yet many believe so. Today&#8217;s second-generation wikis provide various levels of access control, so we can create different levels of editing permission and assign each user with appropriate permissions (some users will be able to edit, but their edits will not go live until a user with approval permissions approves the content). So, what&#8217;s the real problem?</p>
<p>The problem I see as most important to recognize is that knowledge workers have yet to understand their place in the content management life cycle. And, they often have a surprising view of who &#8220;owns&#8221; the content. For instance, regardless of whether you are using a wiki or not, you likely don&#8217;t &#8220;own the content&#8221; you are creating, even if you are using MS Word and storing your files in a folder called &#8220;My Documents&#8221;. Your role is not one of artist (although many writers see themselves that way). Instead, you are part of a content manufacturing process, that, chances are, don&#8217;t work very efficiently, regardless of what software tools are employed. If efficiency and business value were at the center of our decision-making, we simply wouldn&#8217;t be in the situation we are today &#8211; struggling to admit our content has value and therefore should be managed as a business asset.</p>
<p>I could certainly write a book about these issues, but suffice it to say that our primary obstacle is not the wiki. It&#8217;s the changes content creators must make in their attitudes and the way in which they work.  Change is difficult for most, but not impossible. I think we are in the midst of a major shift in the way writers work. The tools we use will change and help us to become more efficient.</p>
<p>It should be interesting to see what happens over the next few years. I see a wiki in my future. What about you?</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: avi</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-31</link>
		<dc:creator>avi</dc:creator>
		<pubDate>Mon, 09 Jul 2007 05:35:50 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-31</guid>
		<description>By &quot;Structured&quot; I mean &quot;reasonably searchable and linked&quot;. That is, if I write a use-case based user guide, I would like my wiki to be able to link the tpoics the way a user guide does.
Again, the problem could be with my legacy point of view, as &quot;tagged&quot; or &quot;easily searchable&quot; may replace &quot;structured into a table of contents&quot; and &quot;indexed&quot;.</description>
		<content:encoded><![CDATA[<p>By &#8220;Structured&#8221; I mean &#8220;reasonably searchable and linked&#8221;. That is, if I write a use-case based user guide, I would like my wiki to be able to link the tpoics the way a user guide does.<br />
Again, the problem could be with my legacy point of view, as &#8220;tagged&#8221; or &#8220;easily searchable&#8221; may replace &#8220;structured into a table of contents&#8221; and &#8220;indexed&#8221;.</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: Steve Carl</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-30</link>
		<dc:creator>Steve Carl</dc:creator>
		<pubDate>Sat, 07 Jul 2007 19:25:18 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-30</guid>
		<description>PS: The hard thing to deal with on a Wiki is the feeling that everyone has that they can contribute, that what they have to write is useful and relevant, and the biggie: Document ownership.

On a Wiki, no one &quot;owns&quot; the content. That is what makes them work. But first one has to get past the idea that only the creator can update the document. It is a stubborn thought paradigm, but it is utterly critical to do it.

Technical writers might, at least in a serial fashion, feel less of this than the average population: At the very least, ownership moves around as re-orgs and new assignements happen.

For technical writing from non-writers, the feeling of territory is strong. There may also be an aspect of &quot;I didn&#039;t want to correct their mistakes because I did not want them to be mad at me&quot; in there someplace.

There is an unleveraged power here. Once the technical people get past this document ownership issue, if you can then put a technical writer into the mix...</description>
		<content:encoded><![CDATA[<p>PS: The hard thing to deal with on a Wiki is the feeling that everyone has that they can contribute, that what they have to write is useful and relevant, and the biggie: Document ownership.</p>
<p>On a Wiki, no one &#8220;owns&#8221; the content. That is what makes them work. But first one has to get past the idea that only the creator can update the document. It is a stubborn thought paradigm, but it is utterly critical to do it.</p>
<p>Technical writers might, at least in a serial fashion, feel less of this than the average population: At the very least, ownership moves around as re-orgs and new assignements happen.</p>
<p>For technical writing from non-writers, the feeling of territory is strong. There may also be an aspect of &#8220;I didn&#8217;t want to correct their mistakes because I did not want them to be mad at me&#8221; in there someplace.</p>
<p>There is an unleveraged power here. Once the technical people get past this document ownership issue, if you can then put a technical writer into the mix&#8230;</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: Steve Carl</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-29</link>
		<dc:creator>Steve Carl</dc:creator>
		<pubDate>Sat, 07 Jul 2007 19:18:40 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-29</guid>
		<description>Hi Anne

As you know, we use MediaWiki inside BMC, and we use it pretty much strictly for technical documentation. This has several dimensions:

1) The people that have the knowledge are not technical writers, but they are the keepers of the knowledge. The advantage of aWiki is that once knowledge is up in place, other can help with the technical aspects of the writing.

2) Google has proven that content is useless unless you can find it. The advantage of a Wiki like MediaWiki (the one we use) is that behind the scenes all content is kept in MySQl. That means the search function is highly usable. Search results are highly relevant. And therefore usage increases of the resource. And in out case, more people want to contribute *because it just works* (tm).

3) The problem with some forms of traditional documentation is that they are in propritary formats where &quot;tribal knowledge&quot; is required to know where the useful content is.</description>
		<content:encoded><![CDATA[<p>Hi Anne</p>
<p>As you know, we use MediaWiki inside BMC, and we use it pretty much strictly for technical documentation. This has several dimensions:</p>
<p>1) The people that have the knowledge are not technical writers, but they are the keepers of the knowledge. The advantage of aWiki is that once knowledge is up in place, other can help with the technical aspects of the writing.</p>
<p>2) Google has proven that content is useless unless you can find it. The advantage of a Wiki like MediaWiki (the one we use) is that behind the scenes all content is kept in MySQl. That means the search function is highly usable. Search results are highly relevant. And therefore usage increases of the resource. And in out case, more people want to contribute *because it just works* &#8482;.</p>
<p>3) The problem with some forms of traditional documentation is that they are in propritary formats where &#8220;tribal knowledge&#8221; is required to know where the useful content is.</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: annegentle</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-28</link>
		<dc:creator>annegentle</dc:creator>
		<pubDate>Fri, 06 Jul 2007 15:02:54 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-28</guid>
		<description>It&#039;s interesting that you associate wikis with structure, because most people wouldn&#039;t. What makes you think it&#039;s structured? The input you have to enter in forms? Wikitext? I&#039;m curious. I thought that mostly writers find that it&#039;s a bit too freeing and unstructured.

I did find that many writers are like you, saying, how do I get my preferred output formats from a wiki? The Confluence Wiki that Dee Elling mentioned in a comment here: http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-wiki#comments has PDF export capability. See http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home.

But you&#039;re right, it doesn&#039;t necessarily make sense to move legacy content to a wiki when other formats are serving the users well.</description>
		<content:encoded><![CDATA[<p>It&#8217;s interesting that you associate wikis with structure, because most people wouldn&#8217;t. What makes you think it&#8217;s structured? The input you have to enter in forms? Wikitext? I&#8217;m curious. I thought that mostly writers find that it&#8217;s a bit too freeing and unstructured.</p>
<p>I did find that many writers are like you, saying, how do I get my preferred output formats from a wiki? The Confluence Wiki that Dee Elling mentioned in a comment here: <a href="http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-wiki#comments" rel="nofollow">http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-wiki#comments</a> has PDF export capability. See <a href="http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home" rel="nofollow">http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home</a>.</p>
<p>But you&#8217;re right, it doesn&#8217;t necessarily make sense to move legacy content to a wiki when other formats are serving the users well.</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: avi</title>
		<link>http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/comment-page-1/#comment-27</link>
		<dc:creator>avi</dc:creator>
		<pubDate>Thu, 05 Jul 2007 16:34:54 +0000</pubDate>
		<guid isPermaLink="false">http://justwriteclick.com/2007/07/04/contributing-to-wikis-as-a-technical-writer/#comment-27</guid>
		<description>Wikis are great for producing large amounts of structured text from bottom up (that is, structure while you write).
However, no wiki system offer a way to deliver the produced content as PDF/CHM, hence legacy writers (all of us?) find out that moving to wiki means forgetting everything we&#039;re doing today.</description>
		<content:encoded><![CDATA[<p>Wikis are great for producing large amounts of structured text from bottom up (that is, structure while you write).<br />
However, no wiki system offer a way to deliver the produced content as PDF/CHM, hence legacy writers (all of us?) find out that moving to wiki means forgetting everything we&#8217;re doing today.</p>
]]></content:encoded>
	</item>
</channel>
</rss>
