10

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.

6
  • How big is your team?
    – Jeff
    Apr 13, 2011 at 22:04
  • We have 3-4 right now.
    – David
    Apr 13, 2011 at 22:06
  • What version-control are you specifically using. I don't know of a source control where you are tied to using Visual Studio for managing it.
    – Earlz
    Apr 13, 2011 at 22:18
  • Where I work, we use TFS to store code, and SharePoint for documentation, test plans, etc.
    – Job
    Apr 13, 2011 at 23:10
  • 4
    I wouldn't recommend putting documents such as PDFs into VSS. Mind you, I wouldn't really recommend putting source code into VSS, either. Apr 14, 2011 at 6:02

5 Answers 5

3

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

3
  • Our 'wiki' solution is either a link to the network share (or link directly to files on the network. The disadvantage there is there's no version control of that. Or you download/edit/upload the file into the wiki, which is a 10 step process any time you want to edit it to fix a typo.
    – David
    Apr 14, 2011 at 0:41
  • plenty of free sharepoint alternatives (that are better!): try Nuxeo for a simple-to-setup one. Or Alfresco for something with more power, if you need it.
    – gbjbaanb
    Apr 14, 2011 at 10:22
  • Google Search installed on your machine does wonders for locating things.
    – user1249
    Apr 14, 2011 at 11:06
3

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.

1
  • We have tried to use doku-wiki, but it is very tedious to use (try to fix a word doc typo is 10 tedious steps), plus no multi-user support on who is editing what. There were also lots of warnings and limitations about file size and file extension that really just annoyed more than helped. I got no buy-in on using it from the other people in the company. I see great potential, but not for my company unfortunately.
    – David
    Apr 15, 2011 at 21:24
1

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

0

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

0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.