Do we actually need several separate documents to present governance to contributors? Have a look at this early review of the MSDN Wiki feaures, which attacks its "tedious four document set of terms for contributions": http://blogs.zdnet.com/Hinchcliffe/?p=48.

Do we actually need several separate documents to present governance to contributors? Have a look at this early review of the MSDN Wiki feaures, which attacks its "tedious four document set of terms for contributions": http://blogs.zdnet.com/Hinchcliffe/?p=48.

--[[User:Willibro|Willibro]]

--[[User:Willibro|Willibro]]

+

+

Here's another thought (or set of them):

+

In trying to help us solve our governance issues by looking at what else is being done by colleagues outside of Cisco, I came across some folks at Sun who have been doing doc wikis for awhile. Here's a presentation they did: https://www.opends.org/wiki//attach/OpenDSPresentations/DeliveringOpenSourceTechDocsViaAWiki.pdf

+

+

Here's the doc wiki they did: https://www.opends.org/wiki. You can sample their work. It's pretty good, has both user and developer docs. Similar to what I'm trying with confluence and a group of developers in Netanya.

+

+

Here's their main policy page, which I think you'll find rather simple: https://www.opends.org/wiki//page/ContributorsAndReusersRightsAndResponsibilities

+

+

ALthough (unlike MSDN and TechNet) you can edit right in the substance of the documentation, the wiki allows no anonymous contributions or editing. That seems to be the case at every corporate-sponsored but-public doc wiki I have found so far. So you must register to edit or add pages, and that requires you to agree to the terms of use, which is the usual legal boilerplate: https://www.opends.org/wiki//page/TermsOfUse

+

+

After that, you have a bunch of links at the side that provide guidelines for your contributions, as well as referencing the page that spells out your original commitment not to be an idiot on the wiki:

+

+

Creating a Page

+

Text Formatting Rules

+

Text Formatting Tips

+

Style Suggestions

+

Wiki Etiquette

+

Contributors' and Reusers' Rights and Responsibilities

+

What is Wiki?

+

JSPWiki.org Sandbox

+

To Do

+

+

I think this is the way we should go. I'm led to suggest this not only by what I'm seeing on other corporate wikis, but also by Ann Gentle's article on Content Wrangler, which I suspect some of you have seen (http://www.thecontentwrangler.com/article_comments/anne_gentle_vs_joann_hackos_is_there_a_documentation_wiki_in_your_future/), especially this bit of Joann Hackos advice she summarizes:

+

"I disagree with the implied connection between Wikipedia’s concerns and the concerns of a wiki for technical publications. I don’t think that tech writers should worry about Wikipedia and the elbowing that goes on behind the scenes there. The types of products we document, mostly software or application programming interfaces, simply do not have the political ramifications and motivations that are part of an encyclopedia’s maintenance. In the interviews and discussions I’ve had with people doing wikis, no one has cited actual malicious intent in any updates made to the pages."

Revision as of 03:33, 24 January 2008

Do we actually need several separate documents to present governance to contributors? Have a look at this early review of the MSDN Wiki feaures, which attacks its "tedious four document set of terms for contributions": http://blogs.zdnet.com/Hinchcliffe/?p=48.
--Willibro

Here's the doc wiki they did: https://www.opends.org/wiki. You can sample their work. It's pretty good, has both user and developer docs. Similar to what I'm trying with confluence and a group of developers in Netanya.

ALthough (unlike MSDN and TechNet) you can edit right in the substance of the documentation, the wiki allows no anonymous contributions or editing. That seems to be the case at every corporate-sponsored but-public doc wiki I have found so far. So you must register to edit or add pages, and that requires you to agree to the terms of use, which is the usual legal boilerplate: https://www.opends.org/wiki//page/TermsOfUse

After that, you have a bunch of links at the side that provide guidelines for your contributions, as well as referencing the page that spells out your original commitment not to be an idiot on the wiki:

I think this is the way we should go. I'm led to suggest this not only by what I'm seeing on other corporate wikis, but also by Ann Gentle's article on Content Wrangler, which I suspect some of you have seen (http://www.thecontentwrangler.com/article_comments/anne_gentle_vs_joann_hackos_is_there_a_documentation_wiki_in_your_future/), especially this bit of Joann Hackos advice she summarizes:
"I disagree with the implied connection between Wikipedia’s concerns and the concerns of a wiki for technical publications. I don’t think that tech writers should worry about Wikipedia and the elbowing that goes on behind the scenes there. The types of products we document, mostly software or application programming interfaces, simply do not have the political ramifications and motivations that are part of an encyclopedia’s maintenance. In the interviews and discussions I’ve had with people doing wikis, no one has cited actual malicious intent in any updates made to the pages."