Does it make sense to set up a wiki at the workplace?I'm thinking of a place where we would put some documents for developers, like coding and naming conventions, build environment set-up, productivity tricks, office books and who has them, etc.
Is wiki a good format for this kind of thing? Can you suggest a particular engine?
ACCEPTED]
As everyone else has already said, yes, this is a great idea.
We use FogBugz [1] and it has an excellent integrated Wiki component with a WYSIWYG editor that spares you having to throw tags in manually to manipulate formatting etc.
I use the Wikis [2] to share everything with my team and department. Everything from internal procedures to documentation templates and project information.
Each project we setup includes a main Wiki that houses links to additional Wikis for:
The main Wiki provides a "one-stop-shop" for anyone working on the project to get any sort of information they might require.
Furthermore (thanks to Joel and his team at FogCreek), the Wikis are all fully indexed and searchable. That means if you get an issue on the help desk, and you want to look up if a similar issue had already been logged or any possible resolutions, you'd also have a handy spot to look up any relevant documentation as provided by the search engine. Neato.
I also agree, the best way to get "buy-in" from the rest of the team is to just start using it yourself. If it's easy to use, provides value and provides benefit, eventually other people will start to see it.
If they don't, hey at least the next guy that comes along will appreciate your efforts and ask them why they didn't also use one!
[1] http://www.fogbugz.comThat is the perfect place for them. There are many different wikis but choosing the right one isn't nearly as important as just choosing one and getting it up and running.
Good job taking the initiative on that.
I think a company wiki is only a good idea if there is some way to enforce style and organization. We use a wiki where I currently work (and my previous workplace), and they were both extremely useful and extremely frustrating.
Useful, because as others have already posted it is a quick and easy way to share information.
Frustrating, because if unorganized (and these were) finding anything is extremely difficult unless you have a direct link to it.
Here is a typical conversation in both of my jobs.
Me: Can you tell me where to find Topic X.
Other Developer: Yes, it is on the wiki?
Me: OK. Thanks. Can you send me the link?
Other Developer: It is on the wiki. Just search for it.
It is like me asking for my keys, and the response is that they are in the ocean.
Basically don't assume people will properly annotate and organize the wiki. There needs to be a person or team who ensures that all content on the wiki is organized and accessible. Without this organization the wiki can quickly grow cumbersome and useless filled with outdated, redundant, and hard to find information.
I have tried setting up Wikis for an development team several times at several different companies and I have found that they get little or no use by developers. If you can get everyone to keep it up to date as code changes, it can be an excellent tool, but I have found it tends to be forgotten and left unedited as code changes.
One idea that will help keep it present in developer's minds is to have it set as the homepage for all of your developers. Add in a few links on the front page to useful sites like this one, and they might not resent it so much ;)
I would no more start a project without a wiki than I'd start one without source control or defect tracking.
I can't recommend FogBugz highly enough. Having the wiki integrated with defect tracking is big; searching both the defect database and the wiki in a single query is huge.
Protip: use your wiki during meetings. It eliminates the scourge of follow-up email.
Yes, absolutely yes. At my current job, they'd set up a wiki a year or so prior, and have been pretty diligent with maintaining it. All current, past, and future projects, meeting minutes/notes, procedures, build environments, etc. go up on it. It's been absolutely invaluable for me as a new worker to not have to bug everyone else on the team when I'm wondering "how would they want me to do this?"
We use Trac [1], which is integrated in with ticketing and SVN, so when you check in code, you just reference a ticket, and it appears in the ticket's wiki, in addition to the updates being emailed to those relevant to it.
[1] http://trac.edgewall.org/Yes, I did just this with Screw-Turn Wiki [1], which was the project Jeff donated to [2] but then as it turns out didn't need the money [3].
It took a while for people to start using it but after answering each question with "it's on the WIKI" for several months, people started to get the hang of it.
Then one of my coworkers upgraded it to the latest version, gave it a CSS makeover, and is using it for internal documentation.
So yeah, it makes sense and takes a while to get people using it but once they get over that hump they're golden.
[1] http://www.screwturn.eu/Default.aspx?AspxAutoDetectCookieSupport=1We think it is and have plans to do the same thing with customer visibility to serve as a knowledge base for our products.
Setting up the wiki is just one part of it (the structure). You will need to enforce a process for using it, a system within which it is used, and disseminate information on how to use it.
We use one, it is invaluable.
Wush.net [1] set us up with a copy of MediaWiki [2] and we were able to password protect the hosted site, so it is used only by our employees. The only drawback is that you have to login twice if you want to edit (one to logon to see WikiMedia, because it has no built in security for this, and another time to edit a page).
[1] http://wush.netWe use Confluence (not free, but works for us). I'd highly recommend it, but I would caution against the idea of storing "Documents" there. If you're attaching files to wiki pages, you're probably doing it wrong. Just document the important info in wikitext so everyone can see, search, and edit it.
A word on security: In my experience wikis work best when they're entirely open for any person to contribute in any area. This is politically unpalatable in some organizations, but fight the urge to "secure" everything from editing.
You still want to be careful in choosing. We chose the Microsoft SharePoint wiki, and this was terrible. After convincing them that it was the wiki that was the problem, we switched to Confluence [1] and it made a world of difference. Now it is the most useful place for most things.
As with any new tool buy in by a good number of people is needed. Wikis need to be maintained, trimmed, and organized. All of these things require your wiki user base to be using it often. Confluence as a wiki solution helps with all of these aspects. It has very good reporting to the conversations taking place on a wiki without having to actively seek out change.
[1] http://www.atlassian.com/software/confluence/It's a good idea. A lot of times it just doesn't work though. And I recommend against FlexWiki.
FlexWiki is very minimal, and doesn't have options I'd like.
As for why it doesn't work so much for us:
So, my recommendation is to use something better than FlexWiki, and to outline some structure for the wiki in the beginning organizing everything. If your teams changes it, fine, so long as it's consistent. Don't throw the pasta at the wall and see what sticks.
Yes - but you will have to work to create the culture of using it, and to keep it from getting disorderly.
Check out MindTouch DekiWiki [1]. It is very extensible if you want to develop your own new features (but there are lots of features and extensions included). Adopted now by the Mozilla Developer Center [2].
[1] http://www.mindtouch.com/Wikis are great for communication and recording stuff you don't want to lose about your project/product. Everything from development environment setup to test plans.
Confluence [1] is a great commercial Wiki, I'd recommend it over other wikis I've used if commercial is an option. Atlassian also has free open source project licenses if you can prove you have an OS project setup.
[1] http://www.atlassian.com/software/confluence/Yes, it's very helpful. We've had this at the last few places I've worked, and it has been a great resource. A few things to remember:
Take the time to convert your existing documentation to wiki, if possible. Don't just link to it, because then it can't be updated. Nobody will use a brand new wiki if it's empty.
At first, people won't be in the habit of using it. When someone sends out a useful email, take a few minutes to paste it into the wiki for them and reformat it, and reply that you've added it. Soon, people will start doing this themselves.
Assign a wiki "editor", who will spend 2-3 days a month reorganizing the content. Or rotate this responsibility among your developers. Don't go overboard but these turn into spaghetti very quickly. A technical writer is great if you have one, otherwise any willing volunteer can do it.
I don't have any recommendation for which wiki to use. I would suggest letting whomever has to admin it get to decide that. Don't write your own in-house one (it happens!).
Good luck!
Absolutely, yes, and I recommend MediaWiki, hands down.
Where I work, we have one set up so that teams can share knowledge easily, and when you need an answer when you get a support call, you can see what happened in the past, and add information about your experience to the wiki. It's become quite popular among all the teams here.
Yes! Wiki's are very helpful for development and build notes and product release time lines, group listings, etc. Everything you want to share with a moderate to large group. Be wary that it is kept up though, nobody uses wiki's with old outdated information. That happened our first round with the company wiki...
I've implemented JSPWiki http://jspwiki.org with great success. It makes automatic backups and is really easy to setup.
Yes. I post tips and tricks using the tools. But the key is to have people post and use it. If there isn't content, no one looks there. They have put all the intranet content (company policy, etc.) there too.
We use source control for documents but then I have them checked out into a publicly shared read-only folder so that non-developers can have access to them. From there you can link your wiki to your documents.
I'm not aware of a wiki with SVN integration but that would be interesting. Not sure I would want management and non-techies to have to deal with SVN.
At my previous company we grew from 10 people to over 100 pretty quickly. A wiki was setup early on and it became THE place for information. Almost everything was tracked via the wiki from releases, to office layout diagrams, network diagrams, contact info, coding documents, how-to's for new developers, etc. New developers would come in and we'd have them spend their first week just reading the wiki while they got comfortable with the environemnt.
We used MediaWiki [1] ( PHP [2] based) and that's what I'm using at my current company as well. Another good wiki I hear about is ScrewTurn [3] ( ASP.NET [4] 2.0) wiki.
[1] http://en.wikipedia.org/wiki/MediaWikiIt completely makes sense. Our company set one up about 2 years ago and it has become the way the team tracks information on projects - all procedures for builds, machine setups, configurations are on our TWiki [1] so that if people are moved or new people are added they have a resource to work from.
One thing to do is to make sure you give some thoughts to organization and convention. Wiki can do anything, but structuring things for things, say DevTools, and then any articles under DevTools get a name like DevToolsBuildScripts, DevToolsVisualStudio etc. so that you can infer the parent from the name. Maybe not for you but it has helped us tremendously.
Best of Luck with your effort.
[1] http://en.wikipedia.org/wiki/TWikiYes, and for simplicity of setup/maintenance we like to use Dokuwiki [1].
It requires no database and uses PHP as the language.
[1] http://www.dokuwiki.org/dokuwikiYou don't specify your platform but this is a combination that I found quite good on Windows:
MediaWiki [1] sitting on XAMPP [2].
Lightweight--easy to configure and test. Good for a "proof of concept".
I started an internal wiki a few years ago and there was some resistance at first. But once people started getting used to me saying "It's on the wiki--take a look" it gained momentum and others started adding good content. A good wiki makes an excellent knowledge base for developers.
[1] http://www.mediawiki.org/wiki/MediaWikiMore lightweight than a wiki, I use Google Docs [1] to share information between project members.
This way I get an extremely easy way to concurrently access and update relevant data without almost any administrative overhead. When any member of the group updates the information (a spreadsheet or a document, in my case), the rest of the group receive an update notification:
See the changes in your Google Document "<My document>": Click here
member25 made changes from 11/6/08 10:21 PM to 10:23 PM
Values changed (7)
Values deleted
You can create folders to organize the files, you can search for files (it's Google, after all :) ). I think it worth to mention it as an excellent alternative to an internal wiki.
[1] http://en.wikipedia.org/wiki/Google%5FDocsMy company has several wikis. They're invaluable for documenting exactly the sort of things that you're talking about. Some of our wikis are even accessible to our customers. We use TikiWiki [1] and MediaWiki [2].
I absolutely hate TikiWiki and I don't know anyone who likes it. It's really slow, really ugly, really buggy. Typical enterprise application (which is odd considering it's open source and highly rated).
Nearly everyone loves MediaWiki. It's clean, it's fast, it's really easy to set up, and it's really simple syntax to edit articles. Also, everyone recognizes it (even the non-tech-savvy customers) because it looks just like Wikipedia.
[1] http://en.wikipedia.org/wiki/TikiWikiIf you want to mess around with a small area to get a feel for what it would be like to use a wiki, try TiddlyWiki [1] and then upgrade to one of the other systems discussed when you decide to green light the whole deal.
If you put this on a shared drive somewhere for others to use too you may want to install the TiddlyLock plugin [2].
[1] http://tiddlywiki.com/I set up a wiki for my laboratory with great success. Some things to keep in mind when choosing a wiki:
Ease of Installation
Choose a wiki that is not hard to install. I know a number of labs that have tried to install a wiki only to give up part way through. If you have dedicated hardware I found TurnKey's Mediawiki appliance [1] to be easier than others.
Backups
If your content is worth putting on a wiki, then it is worth backing up. Most wikis do NOT provide an easy-to-use backup functionality. For example, to backup a Mediawiki [2] install you must in essence backup three different components [3]: the MySQL database, the PHP settings information and also all of the images and media files. You can google around, but you will likely need to write your own backup script.
Restore
A backup is only good if you can restore. Mediawiki, for example, allows you to do XML dumps of the site, but these are non-trivial to restore from. Make sure your restore functionality is working properly. In some cases this may mean setting up two machines to test restoring from one or the other.
Community Resources
Make sure you wiki has the tools and resources necessary for your user base. Some of our wiki users are not comfortable with Wiki Markup. Fortunately Mediawiki has plugins such as the FCKeditor that provide WYSWIG functionality. Also, some of my users require advance math editing capabalities and of coures Mediawiki has excellent Latex integration. Ultimately Mediawiki has an exhaustive list [4] of plugins that made it ideal for my application.
After writing a point-and-click backup/restore system for Mediawiki and bundling a number of plugins and tools, my friend and I received lots of requests from colleagues to set up wikis for their labs. So my friend and I are now selling pre-configured instant-setup Mediawiki network server appliances for $599 at http://innoboxdevices.com
All of the source is AGPL'd available at http://github.com/innobox
[1] http://www.turnkeylinux.org/mediawikiI think they are a great idea ... but like everything else in the workplace it needs to have procedures as to what can go there and how it should be structured.
