Our web development group is using an internal wiki, powered by MediaWiki, to build our internal documentation on applications, coding standards, etc. As I've had the most experience working with and in a wiki, due to the 5+ years I was an active Wikipedia editor before I stepped down in August 2010, I was tasked with writing and conducting some trainings on using our wiki. I conducted the first one this week, doing an over view and some basic stuff, and thought it might be useful to others to post the first bit, on what a wiki is and why it should be used here. Later, I may post some of the intro stuff (navigating a wiki and basic wiki syntax), if it seems like there is interest.
So, What is a Wiki, Anyway?
The first wiki was unleashed on the world in 1995 when Ward Cunningham and Bo Leuf released WikiWikiWeb. According to Cunningham, a wiki is “The simplest online database that could possibly work”, which has to be the worse definition of it I have ever heard. If you've ever looked at a wiki's database, it isn't simple by a long shot. In reality, a “wiki” is a content management system, just like most web site management applications, such as blog software, CMS applications, etc. A wiki's defining characteristic is that it enables multiple users to work collaboratively on the individual pieces of content in the site to create what is, in essence, an online book.
How does it compare to, say, a blog, though? Well, a blog is more of an online journal of sorts, where content is generally posted by one author or a small set of authors, and then left as is. Once its posted its posted and other than commented on, rarely changed. On a wiki, the same page may be edited many times to add new information, update information, or even remove the page. A blog is also generally a place for posting ones' general, personal opinions, while a wiki generally is a collaborative environment whose pages represent the consensus of those who edit it. While a wiki is a content management system, it differs from the traditional CMS in that “CMS” generally refers only to the web application software running the site, while the term wiki refers to both the software and the actual resultant output.
So Why Use a Wiki?
The wiki is a great way to work collaboratively, particularly on reference type materials, online books, etc. It is becoming increasingly common to see software documentation and knowledge bases made available through a wiki, where the community of users and developers can help maintain the content in a fairly easy fashion.
Most wiki's use simplified text syntax for performing common stylistic functions, so users do not have to learn HTML of any kind to get started. They simplify site organization by making it easy to search and link content while typing. It is easy to create and update pages on a wiki, and to rename them without breaking anything. Almost all wiki software packages include automatic versioning of every page, with every change made recorded in the page's history. This enables you to compare past versions of documents with themselves or the current document, see exactly what changes someone before you made, and even undo undesired changes days, weeks, months, even years after the fact.
Of course, the most well known wiki would have to be Wikipedia, in its many language variants, which allows anyone on the planet with an Internet connection to contribute to a living encyclopedia of (mostly) notable topics. There is also:
- Wiktionary, a wiki that functions as a world-wide dictionary
- The Commons, a repository of media freely available under the Creative Commons Attribution/Share-Alike license
- Wikia, the wiki of wikis that mostly consist of fan sites and other stuff not desirable on Wikipedia
- WikiCity, covering every city in the US
- WikiHow, a global how to manual for just about anything and everything
- Citizendium, the director competitor of Wikipedia with greater restrictions
Why is Our Developers Group Using a Wiki?
In short, documentation, documentation, and more documentation! This has traditionally been one the greatest weaknesses of our work group: documenting our processes, procedures, application information, etc. Far too many times, to answer what should be a basic question on an app, such as “what's its purpose and who is the client” has required convoluted email searching (with Groupwise, all searching is convoluted). Or one developer would tell the others about a nifty global function they added to our library, but then when the others go to use it they have to waste time reviewing the code to figure out how to use it. Our consensus on various issues is the worse, as sometimes its in email, sometimes IM, sometimes convos in the hall. If it were all documented in a central respository, it would be far more useful.
So our internal wiki, the SDG Wiki, was launched to be that central repository for the collective knowledge our group members have. It is already making it much easier for us to document work related information. I also think it will prove highly useful in the future should new developers come on board, or we get questions from the state auditors and the like. We now have pages on every application we currently have that is live, designed to act as profile pages containing the application'ss history is, who the key players are for it, who developed it, what language and DB it uses, if it uses any of our global functions (with auto categorization), when it launched, what its current version number is, etc. It links off to its ERD, SVN links, and any related documents like meeting notes. For larger apps, it also links to an on-wiki version release log. We also have pages documenting the contents of our global libraries, our coding standards, and for sharing snippets of code that may be useful to others.
What About Security?
To ensure such info stays secure, the wiki is set up as a truly internal app, accessibly only to those who have access to our internal network (itself inside a larger network), and only if you have the appropriate configuration in your hosts file to get to it. For a shop our size where all of our staff is local and literally office neighbors to one another, and where we can all get to the server and set up the hosts, this works well for us. If you decide to go with the wiki, but can't go so internal, I'd recommend locking it down so it can only be viewed by logged in users, and putting it on an SSL connect, just to be extra safe. If you can, use an htaccess (or the IIS equivalent) to lock access to only the user's IP addresses as well. Better safe than sorry.