DocWiki talk:About

From DocWiki

Revision as of 05:56, 26 January 2008 by MeetingPlace Moderator (Talk | contribs)
Jump to: navigation, search

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": --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:

Here's the doc wiki they did: 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:

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:

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 (e.g, Creating a Page, Text Formatting Rules, Text Formatting Tips, Style Suggestions, Wiki Etiquette, What is Wiki?, etc.)

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 (, 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."

Worth considering, I think. --Willibro 22:33, 23 January 2008 (EST)

About title collisions...

Unless people import pages, there's not really any way they can "collide" with existing titles; they have to create a link first, then click the link to add content to the page -- but if the page already exists, the link will take them to the existing page...

However, consistency in titles will be helpful.

I chose the "Product Family, Release Number -- Article Subject" naming convention for several reasons, which I will detail in my write-up of my doc Wikification experiences...

Personal tools