views:

740

answers:

17
  • Do we use a company wiki?
  • how about you save the technical documents as part of source control and then have links to them from various source files (to understand how this works see article ... in directory...)

what are the pros and cons of these and other methods? any good tools for this purpose?

If you recommend a wiki, what Wikis would you recommend to use? internal? hosted? free? paid?

+5  A: 

If you can muster the support, a social medium that has reputation (like this very site) can work extremely well on an intranet. People need a bit of an incentive to feed the knowledge base.

James A. Rosen
If you don't want to implement _Stack Overflow_ then you could use a wiki and have a "top contributors" page simply counting number of edits or such. - not perfect, but a good incentive if you're in a hurry.
AJ
+15  A: 

I'd recommend using a wiki. It works extremely well as a central documentation source and has built-in revision control. Also you can reference the docs in the code via URLs.

David Arno
We use TWiki in my company hosted on our server. It works great but it can be messy if it is not well-organized.
madgnome
I'd say, wiki works only until your organization has not reached certain size.
Alex B
I work for one of the largest software companies in the world and we still use wikis. Finding the right wiki can be challenging, though.
David G
madgnome, I'd agree that a wiki can be messy. Layout and formatting styles need to defined and ideally some people should act as editors, tidying up others' efforts when they are messy.
David Arno
@Checkers, sorry to criticise your grammar, but I'm unclear whether you say an organisation has to be a certain size for a Wiki to work; or that it doesn't work with too large an organisation. I'm seen a Wiki work well for a group of 4 developers and for a group of 60 developers.
David Arno
@David, you could've just asked the clarification and not mentioned grammar, because it's confusing only, not wrong. He means wikis won't work in a big organization. (In addition it's I've seen, not I'm seen).
Vinko Vrsalovic
@Vinko, you are right and I apologise for mentioning grammar as it is bad form to criticise another in that way (and I'm liable to get egg on my face next time I mess up my grammar :)
David Arno
+1  A: 

I've used both methods in the past, and found the wiki format to be the most readily accepted. Storing documents in source control can have impacts around merging versions (obviously dependent upon the source control software in use and methodologies applied). The same is true of wiki-based solutions, but for some reason it has never seemed to present a massive problem in the implementations I've used.

The searchability of major wikis is another major factor for its success. It is far easier to look up a search term in a wiki than it is to find a reference to a document in a potentially unrelated piece of code.

<2c />

ZombieSheep
+1  A: 

I like wikis. I even use them for my own hobby projects, documenting how I got around nasty problems I don't want to have to deal with again, or maintaining a list of references to relavant resources.

Having many people contribute to such a wiki is even more powerful, however a possibility for discussion is also very important.

Rik
A: 

I've actually begun a side project that addresses it. It's still in the planning phases, but I've identified a few areas where technical knowledge is kept in organizations. Now, this this doesn't apply to every organization, but every organization uses at least one of these.

  • People
  • Static Web (Internet and Intranet) Sites
  • Books (a company library)
  • Books (an individual's books)
  • Dynamic Web (Internet and Intranet) Sites
  • Databases and Repositories

Exactly how you utilize each of these is different, but a key is to get the People to use Static and/or Dynamic Web Sites to capture information, or at least identify where it is in books and repositories. If the people aren't feeding the knowledge houses, then it doesn't matter what technology you use. The knowledge must be current, accurate, and in-depth or it's futile, from what I've been able to gather.

Another key concept that is important, as Vinko Vrsalovic pointed out, is the ability to link the data/information/knowledge back to it's reasoning. A common practice in requirements analysis is the ability to trace the requirement to its source. The same should be said for knowledge. Everyone in the organization can know everything in the world. However, if no one knows WHY that knowledge is useful or WHERE/WHEN to use that knowledge, it's wasted.

If I'm missing any, feel free to edit this post or reply as a comment. I think this question will help my project efforts.

EDIT 1: Added Vinko Vrsalovic that it's not just about the knowledge, but linking the data back to the production issues that the knowledge pertains to.

Thomas Owens
I'd consider the ability to link the knowledge to actual production issues. In software, to the issue (bug) tracker, in other domains to whatever maps correctly. Easily navigable meta knowledge is very valuable
Vinko Vrsalovic
I would agree with that. I'll append that to the original posting.
Thomas Owens
A: 

Definitely a wiki. We use TWiki and make use of some excellent plugins.

Edit: I forgot to add that you might like to consult the answers for this question on documents and version control.

Rob Wells
+2  A: 

Wiki's work well, but we supplement the Wiki with Ignite and Camtasia screencasts. These save time when depicting configuration, etc. Screencasts are easy to do, quick, and you don't have to worry whether you have captured the right detail for your audience in that they rewind / replay the sections that they need to review.

We've tried knowledge base articles and it makes people lazy - "I don't understand this section" means you'll rewriting a whole bunch. Give a person a screencast and they can make their own notes.

David Robbins
+4  A: 

People are the most effective knowledge container in your company. And the most effective way to transfer knowledge is from people to people. Wiki's and documentation are useful too but unless your employees are great technical writers written documentation is a terrible way to transfer all but the most trivial knowledge. Writers take years to write a book so you can't expect developers to write quality documentation in a couple of hours.

The best way to keep knowledge in your organization is to have people work together. Make sure no one works alone. Have people pair-program and review each others code. Organize technical sessions etc.

If you really want to store the knowledge somewhere try to enrich the data. Make it easy to add pictures of whiteboards etc to the wiki. Another problem with written documentation is that people seem to think long winded abstract text is 'professional'. Make sure you keep documentation short, clear and to the point so people will actually read it.

Mendelt
+1  A: 

The single most important thing about retaining knowledge in a company, regardless of solution, is to enforce people use the system. Wikis are my favorite, but without enforcement from management or team leaders, its hard to maintain that level of useful knowledge -- people hate documenting it seems, especially when it makes them easily replaced.

Russell Myers
+3  A: 

I would recommend the MindTouch Deki. It's far more than a wiki, with integrations into a number of other sources, including the ability to integrate it into custom data sources in your organization.

Thomas Owens
A: 

Use a wiki, but ensure that someone has editorial ownership of what goes in. That person needs to ensure naming standards and document herarchy are adhered to - it's very easy for a company wiki to become a sprawling mess.

Jon Topper
A: 

I'll give you some drawbacks of Wiki's, or where some extra thought maybe required:

  1. If the technical knowledge/documentation is shared with customers or organisations which do not have access to your Wiki
  2. Documentation associated with a particular version of software often lives better with the source associated with the release. Often Wiki's contain the most up to date information but it might be hard (depending on the care of editors) to map documentation to older releases
tonylo
A: 

I think, the tool you use is not so important. The real important thing is, that all members on your team aggree upon one way and one place for the documentation.

You can use a wiki or a notes database or a self-brew application.

I personally prefer that all things are in one place. So for technical documentation, the source control system will be the right place. For documentation, which is used by non developers, source control is definitly the wrong place. For accross-the-board docs, maybe a sharepoint server is the tool you should use. It has some kind of version control and is accessible without special client-applications.

Jan
A: 

Wikis are good, but one of their biggest advantages hasn't been mentioned yet. Very often the flaws in documentation are not found by the person who wrote it, because the author doesn't need or read the documentation. Flaws are found when the author is on vacation or out sick, and someone else tries to follow the documentation and part of it doesn't work. Using a Wiki, whatever poor fellow ends up discovering the flaw in the docs can correct it immediately, rather than having to email the author, where it gets buried in the other thousand emails the author got while on vacation, or trying to remember to tell the author after the author gets back.

Also, make sure that at least two people know how to do everything, and maintain staffing levels. When someone leaves, it can be very tempting to not replace them if you already have other people who can do everything that they did, but if you now have multiple pieces of infrastructure or code that are each only understood by one person then you are vulnerable. Knowledge transfer from one person to another takes time and hands on work. It isn't easy, but it is infinitely easier than trying to learn an infrastructure or code base from docs alone.

Glomek
A: 

We use a combination of project blog and wiki.

I think people felt a bit put off by a wiki - that they felt they needed to enter a few paragraphs at the least to justify the entry - so we started a blog which is useful for capturing little things or things that happen in real-time, e.g, 'I changed column field length from 40 to 50' or 'purged audit table data older than last week'.

I expect (hope) that some blog entries will become the source material for longer wiki entries as the project progresses.

Rik Garner
A: 

As an alternative to a wiki, consider using SharePoint. It allows you to handle events (like meetings), tasks, and documents. It works very will with the non-technical crowd, which may allow technical writers and managers to take a look at what's going on. It's also part of Windows 2003, so you may not need an additional license for it.

On the downside, I can almost guarantee that there will be a luddite who blames you for every minor UI quibble. The higher-ups will probably love it though.

Dan Goldstein
+1  A: 

I've seen that a lot of knowledge discussions happen within email within an organization. This knowledge stays within the email for long and eventually get lost and is not accessible to others who were not part of the original discussion.

Using tools like http://grexit.com can help you move these knowledge out of you inbox to a coomon shared repository within your organization. Currently this works only for Gooogle Apps but its worth the try.

Nands