What's the best way to store documentation associated with a code project?

Question

We have a lot of documents associated with our software development. These include things like requirements, design documents, external PDFs, customer files, testing instructions, etc. Currently, these documents are scattered all over the place (wiki, "some place on the network", a local developers hard drive(!), and even worse places).

What's the best way to keep track of them? Since we use visual studio (2010) for our development, and we don't really have any non-developers on the project, I thought it'd be a great idea to store them within the VS "solution", which would allow them to be source controlled, and universally accessible by all the developers.

However, VS really doesn't seem to be built to do this. If you edit any document file, even one that is setup with the build properties "None", "Do not copy", VS must will rebuild the software before it will run again. There is no way to create a "Documentation Project" within the solution. (We use an Empty C# project for this). Visual Studio and Word/Excel flat do not do source control well. You can't view a checked-in file, and then decide to make a change without first closing the file, going to the project, and manually checking it out before making the change. It's slow and tedious at best.

Anyway this is the best our team has come up with, but I really wish I had a better (free) solution.

Answer 1

I'm not sure if there's a single "best way", but from your description, it sounds like every developer is doing his/her own way of storing documentation. Get a buy-in from everyone on a single method of storing documentation, and it'll be a lot easier to keep it organized.

Besides the "find the best way for you" answer, I'd say to at least look for a solution that makes it easy to search for documents. At one company, I set up a wiki that contained links to files thrown all about serverland, which suddenly made it much easier to search for and locate documents no matter where they were. Once other users started using the wiki to find documents, they also started updating it to either link new documents, or by just creating a wiki entry as the document.

I'd love to hear from anyone else if they know about free version control systems that work well with documents. The only thing that comes off the top of my head is Sharepoint, which isn't exactly free. I've seen unofficial versioning systems where people have an "Archive" folder, and simply put past revisions of a file in that folder, with the newest revision being in the same folder level as "Archive".

Answer 2

The solution that worked out the best at my company was to set up a wiki (we use mediawiki). It gets used in many ways, from the traditional wiki entries to a simple "This is a..." plus a Word document. It is very easy to search. We're gradually building up a very useful repository of information.

Answer 3

In VS 2008 at least, you can set a C++ project's configuration type (under project properties->general->project defaults) to Utility, in which case VS doesn't do anything with it.

Have you tried to use such a project in your C#-based solution? (Maybe a C#-project has something similar?)

Answer 4

I definitely agreee there isn't a single bestest solution here. But version control != included in solution; most systems can handle things beyond the IDE. So one can keep the docs close but nota within in most cases.

Now, getting past annoying habits of word to change files whenever they are opened is a different problem . . .

Answer 5

No, Visual Studio (well, C# and Vb.net) projects have a brain-dead approach to the solution explorer. The VC++ one is MUCH better as you can create virtual folders that are not tied to the disk layout, and put all kinds of stuff in there too. Silly Microsoft broke it by trying to make it 'easier to understand'.

You can still put itin a 'solution folder' but its still not as flexible as you'll probably want. That means you have to find an alternative and my recommended alternatvies are web tools. If you don't want to try a project portal (such as Redmine) where you can store documents and have a wiki, bug tracker, etc etc then go for a document management tool. Something like Nuxeo or Owl would do you well. Once its one the web, you have a central location so people know where to look for these things - that's probably the most important part of document management. If you tie it to a version control system like subversion (go on, you won't regret it after VSS!) then you'll still be able to link the documents to the web tools and version control them too.

Subversion even has the ability to expose the repository as webdav folder - ie a network folder - so youcoudl put them on a 'network drive' yet still have them version controlled automatically.

I'd still go for Redmine as my personal preference.