Where to put what when using CVS, Wiki, document management?

Question

Hi,

In our company we are currently using CVS for project documents, status reports etc, shared folder for installables/product documentation etc and some teams use Wiki (I don't know for what?). Now, I am confused as to where to put what. It would be great if could describe what tools you use in your setup and for what purpose.

EDIT: This is what I get from your answers, please correct if I am wrong.

Use version control system for source code (mostly), for everything else use Wiki.

Where would you keep the installables for tools and utilities, dependent software packages etc? Do you have a separate document/content management system or you keep that in wiki too (since wikis support uploading of documents/images/any kind of files).

Answer 1

consider that:

• CVS (or any Source Control Management system):
  Coherent set of file you need to have a stable state (label) or several parralel versions (branch)

• Wiki: dynamic documentation (can be changed by many authors), usually comes with its own historization system

According to those criteria, you can sort your various files out between those two referentials.

For instance, if a status report is not linked to the lifecycle of the development of a project (which is managed by CVS), but to the one of the release into production, Wiki is better suited to display it, since the production is very sequential (at one time, you have only one prod running, no branch necessary).

If your tools and utilities are part of the same deployment process than the deliveries build from your source control-code, I would also put them in the SCM tool, not in the wiki:

• they need to have a global label to manage your all application (source + needed shared tools/utilities)
• they may exist in several versions, managed in their own branch.

I would suggest to put them in the same SCM than your code, but some prefer using a third referential(!, after SCM and Wiki), with a maven repository...

Answer 2

I'd say the main advantage of storing documentation in a source control system instead of a wiki would be if you have multiple versions of the same docs like for example for development and release branches of a project. There you could use merging and such.

Otherwise I'd recommend a wiki as they usually already have history/diffs to correct mistakes. Think about it this way: it's already hard to make people keep documents up to date. You want to make it as easy as possible for people to nourish the docs. Having incorrect or outdated docs can be more frustrating than having none.

It's not that it's hard to keep docs in proper version control. It's just that wikis make it easier.

Answer 3

You should also think about the target audience whenever you store project-related stuff: Who gets what: Project Manager, Developer, Tester, End user, ...

Since my approach is to have online help for web apps in a wiki as well, you end up with 2 wikis: one for developer documentation, one for online help.

As for your edited question regarding installables: they should be in the VCS too. Developers should have any libraries etc their projects depend on in the VCS. For installation purposes, executables and dependencies are kept in a separate repository.

I miss bug tracking here: if a project gets a specification of a new feature, this spec also goes into bug tracking. Any development "issues" (enhancements, fixes, etc) will be stored as dependent bugs. Later its clear what steps have been taken to implement the feature. By appropriately tagging the feature bugs, you can easily query which features are already implemented (and marked "closed", "verified" etc) and which aren't.

Answer 4

Use version control system for all source code, and anything that needs to be controlled.

• All Source of every kind. Everything that is required to build the application. Plus all the unit tests. Plus all the configuration files required to install and manage. Even our Apache app.conf files are here.
• Requirements Documents. We use RST markup, so our docs are plain text. We don't keep these in the wiki because these are controlled documents that set scope for other work.
• Installers for all open-source components and dependent software packages. These are big and binary, but they never get updated. The next version always has a different file name. Since there are no changes, there's no change comparison or change log. (Proprietary installers are often too big and complex, and license restrictions sometimes prevent this.)

For everything else, your document/content management system is the Wiki.

• Project plans. Backlogs. Other management information. These are working documents and change all the time.
• Design Documents. Text plus UML diagrams. These are working documents that evolve and grow.
• Other architecture and implementation notes. These are working documents that are focused on a specific release.