问题
- 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?
回答1:
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.
回答2:
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.
回答3:
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.
回答4:
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.
回答5:
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.
回答6:
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.
回答7:
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.
回答8:
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 />
回答9:
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.
回答10:
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.
回答11:
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.
回答12:
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.
回答13:
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.
回答14:
I'll give you some drawbacks of Wiki's, or where some extra thought maybe required:
- If the technical knowledge/documentation is shared with customers or organisations which do not have access to your Wiki
- 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
回答15:
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.
回答16:
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.
回答17:
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.
回答18:
You can probably take a look at Associativy. It stores pieces of knowledge as nodes of a graph where edges represent associative (in a human sense) connection. The graph is searchable and explorable in multiple ways, given a set of search terms the software is able to "think" about a suitable association.
I's open source and runs on the Orchard CMS, an open source project as well.
This was a shameless plug (Associativy is my project), sorry.
Edit: just recognized how old this question is....
来源：https://stackoverflow.com/questions/178110/what-is-the-best-way-to-remember-technical-knowledge-in-the-organization