Where should I store documents in Team System?
A common point of confusion with Team System is that it provides three possible places to store documents on a Team Project:
1. On the Sharepoint website within a Document Library.
2. In a Work Item as a File Attachment
3. In Source Explorer as a versioned changeset.
So which of these is the appropriate place to store project documents? Well, that depends on the document.
Obviously, attaching documents to a work item scopes them very closely to that bit of work. I'd only put documents here that are intended to "live" as long as the work item itself. For example, one obvious use is screenshots of a bug. Once the bug is fixed and closed, the screenshots don't need to be carried forward; they're a part of the historical record for that work item. And attaching a document isn't your only option. You could just as easily link that same work item to documents under source control, link it via hyperlinks to documents in the Sharepoint site.
As for whether or not to put documents in Sharepoint or under source control, it depends on the intended audience for the document. Generally only developers want or need access to source control. Also, bear in mind that the Team Project permissions, and the Team Project Sharepoint Team Portal permissions, are two different lists. This is one of the few times that distinction works in our favor. It's usually appropriate to make the Sharepoint site "more public" and put documents there that are intended for wider dissemination, such as program managers, business analysts, customers, and other not-so-technical team members.
To identify the audience for a document, I find that asking these two basic scoping questions helps a lot:
- Will this person ever have Work Items assigned to them?
- Is this person a software developer?
Jason Barile has some additional thoughts on where documents should go in Partitioning: Sharepoint vs. Version Control.
In general, I think about the Team Portal as a place to store anything you want to have very high visibility across all roles ;in the project. For example, process guidance, best practices documents, schedules, contact lists... - stuff that applies to everyone involved in the project. I think of Version Control as the best place to store items directly related to building the product (e.g. source code, test code, tools, etc.). Typically, developers and maybe testers will be the primary people who use version control. So my suggestion is to use the Team Portal for everything else so you don't have to train business analysts and project managers how to use Verison Control (not that they can't learn, of course :)). Another benefit of Version Control is the ability to view differences between versions of artifacts. But several file types such as Word documents already have an internal change tracking mechanism [and Sharepoint itself has basic versioning as well], so [formal] Version Control isn't buying you much here.
I do like the idea of bundling all specs & documentation together with source code when the project ends though. Depending on your definition of "end", you might be putting the project on ice forever, handing it off to a support team, or moving on to the next round of feature updates in your "always live" website type project if you're following more of a "real time" product cycle than a typical application product cycle. You might consider taking a snapshot of the pertinent Team Portal documentation and checking it into your Version Control repository at major milestones.
It's definitely something to consider before embarking on your next Team Project.