tags:

views:

2065

answers:

30

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?

+25  A: 

That 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.

Justin Bozonier
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 and it made a world of difference. Now it is the most useful place for most things.
lillq
+4  A: 

We think it is and have plans to do the same thing with customer visibility to serve as a knowledge base for our products.

Software Monkey
+3  A: 

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.

  • No diffing (in any reasonable way, the diff that is there is impossible to figure out)
  • No ability to see what users have edited
  • search and recent changes (at least for us) is extremely slow)
  • annoying UI (to me) - double click to edit
  • no categories

As for why it doesn't work so much for us:

  • I think part of it is we don't like the software
  • difficult to find stuff, no organized structure

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.

Tom Ritter
I don't know about FlexWiki but I'd basically disagree with imposing structure on things from the outset. Let it grow organically and if you feel that things have gone in the wrong direction you can modify them afterwards.
Onorio Catenacci
I understand the argument, but I found that you add a page to the wiki, email it to the people you're working on, you update it for a bit, then it grows stale, and noone knows about it. Categories and index pages make sure everyone else can find it, and that will keep it up to date.
Tom Ritter
+2  A: 

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.

Elie
+5  A: 

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

Marc Bollinger
+9  A: 

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 ;)

Rob Prouse
This is true. One way to keep it up to date is to assign tasks specifically to update documentation in the Wiki. It has had success at my workplace.
Zack Mulgrew
And a google search box!!
Kieveli
2Kieveli: you mean adding Google search to my internal Wiki? How?
z-boss
I think he meant add Google search so that they could start their web browsing from the wiki and replace google with it. Might be a good idea.
Justin Bozonier
Last workplace Wiki I used had very little in it that needed to be kept up to date with the real code base. We had other tools for code documentation. What it was useful (and used) for was docs in progress with a lot of collaboration, "how to" info for tools, "who's got what hardware" lists, etc.
Steve Jessop
Great idea about the common homepage for developers - I'm going to suggest that at my workplace :)
James Allen
+1  A: 

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...

Fry
+1  A: 

I've implemented JSPWiki http://jspwiki.org with great success. It makes automatic backups and is really easy to setup.

Eric Wendelin
+1  A: 

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.

Brian Carlton
+5  A: 

Yes, I did just this with Screw-Turn Wiki, which was the project Jeff donated to but then as it turns out didn't need the money.

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.

Schnapple
+3  A: 

We use one, it is invaluable.

Wush.net set us up with a copy of MediaWiki 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).

Jason
+1 because MediaWiki is the way to go IMO.Although rather than setting it up online, I would probably put it some some sort of internal webserver.
Dalin Seivewright
I know nothing of Linux - we are a Microsoft shop... and it worked out for us because our team is dispersed. However, I do this because a client of mine does it, and they set it up internally. Works fantastic. If you host, go with wush.net, it is pennies and well worth it.
Jason
You can prevent anonymous users from viewing the contents of your Wiki by adding the following commands in LocalSettings.php$wgGroupPermissions['*']['edit'] = false;$wgGroupPermissions['*']['read'] = false;$wgGroupPermissions['*']['createaccount'] = false;
JcMaco
Awesome, thank you... I will try that.However, I believe that because it is written in PHP, it is not very secure (is that right?) and customer trade secrets should probably be behind a more secure wall.
Jason
+3  A: 

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. 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.

pc1oad1etter
+2  A: 

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 (PHP based) and that's what I'm using at my current company as well. Another good wiki I hear about is ScrewTurn (ASP.NET 2.0) wiki.

Todd Smith
DekiWiki has plugins for tying in source control.
pc1oad1etter
+2  A: 

It 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 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.

MikeJ
+2  A: 

Yes, and for simplicity of setup/maintenance we like to use Dokuwiki.

It requires no database and uses PHP as the language.

Turnkey
+2  A: 

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 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.

Ken Gentle
+24  A: 

As everyone else has already said, yes, this is a great idea.

We use FogBugz 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 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:

  • System Requirements
  • Functional Specifications
  • Meeting Minutes
  • Associated Development Cases
  • Q/A Related Cases
  • Beta implementation information

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!

Mat Nadrofsky
I agree. We use ScrewTurn wiki (despite having FogBugz) and it's a little slow due to slightly awkward design. Learning wiki markup isn't a bad thing though, and can help encourage use of look and feel standards.
Neil Barnwell
I find the FogBugz wiki somewhat limited, at least it doesn't match my mindset. We'er using Foswiki.org with much success though.
torbengb
+4  A: 

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.

Ali A
Enforce a process? That's kind of defeating the main advantage of a wiki--that it's so simple that no one has any excuse for not using it. Making a wiki yet another source of bureaucracy is sort of defeating the point.
Onorio Catenacci
Things don't get used if you don't enforce them (I find in my experience).
Ali A
I agree, setting up the Wiki is easy. Getting people to use it, that's another story. Case in point, we have one. I dunno where the hell it is. So I dont use it, and no one complains.
D.S.
Upvoted just for D Scott's comment. lol
Kevin Fairchild
+2  A: 

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!

+1  A: 

You don't specify your platform but this is a combination that I found quite good on Windows:

MediaWiki sitting on XAMPP.

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.

Onorio Catenacci
+2  A: 

More lightweight than a wiki, I use Google Docs 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.

PabloG
Thank you for mentioning it. It's always good to consider the alternatives as well.
z-boss
+1  A: 

My 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 and MediaWiki.

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.

rmeador
+3  A: 

We 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.

PowerfulMojo
+18  A: 

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.

grieve
Yup. 100% agree on this one. That person is me. Go figure. ;)
Mat Nadrofsky
If you use a wiki that implements tags or labels it helps with this problem a lot.
lillq
Every wiki needs a "gardener", someone who is unofficially like an admin and a librarian. Keeping the pages neat(er), helping people with making links, and generally promoting the wiki way and "how to wiki".
torbengb
Rule: if you don't know; look in the wiki. If it's not in the wiki; ask and then PUT it in the wiki. This actually works! But again, it mostly benefits the newer people. The newer people often like the wiki more because they need the info while the older ones already know and therefore don't care.
torbengb
+7  A: 

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.

Robert Rossney
+1 for the pro tip.
torbengb
+2  A: 

Absolutely, yes, and I recommend MediaWiki, hands down.

skiphoppy
+1  A: 

If 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 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.

CrashCodes
+2  A: 

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 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.

lillq
A: 

I 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.

Nippysaurus
A: 

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 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 install you must in essence backup three different components: 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 of plugins that made it ideal for my application.


Wiki Network Appliance

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

AndyL