Tuesday, April 01, 2008

Frustrated with "How to: Move Your Team Foundation Server from One Hardware Configuration to Another"

Nothing frustrates me more than when documentation is wrong or misleading. Case in point: The document "How to: Move Your Team Foundation Server from One Hardware Configuration to Another" explaining how to move TFS from hardware to hardware is probably one of the worst written documents I've ever read. Here are just a few of my observations.

- We've bombed out at "To rename the Team Foundation data-tier server". The first issue was that a small, yet critical, detail is left out of the document. It's missing the statement explaining before running TfsAdminUtil RenameDT you must modify the Service's web.config, making sure the connection string on the new server is referencing the old server. The Community Content says this at the bottom and also the "Microsoft Visual Studio 2005/.NET Framework 2.0" says it. So why doesn't the master document for TFS 2008 say this? If you fail to do the rename, the command comes back and says "data tier name not changed."

- Even after getting past this, we are still stuck though. According the support, we actually should do the "Rename the Team Foundation Data-Tier Server and Activate the Team Foundation Application-Tier Server" and "Move User and Service Accounts" AFTER we do other things like "Restore and Test SQL Report Server, Reporting Services, and Default Reports" which is two sections BELOW "Move User and...". What? If this is true, which we're verifying with our field rep, why does the document have them out of order? How can someone expect to know this?

- Lastly, the support rep (who was actually very helpful by the way), said that you basically have to disconnect the old TFS server when you do the migration. Meaning, you basically can't do a test restore on some QA hardware before you have to come in on a weekend to do the same steps on a live PROD system. We're checking with our field rep to make sure this is accurate, but if it is, which I'm praying it's not, where in this document does it state that you must disconnect the old system before doing the restore based move?

Sorry for my rant. I just get so frustrated when documentation is wrong or misleading.


Allen Clark, Programming Writer, Team System said...

Sorry about this Mac. We know of this problem and are working to correct it. The doc was correct at one time, but tools changed and the doc wasn’t updated. We're working to make sure this doesn’t happen again.
We’re working on providing an updated procedure as soon as possible. We’ll post it on the Visual Studio Team System User Education blog (http://blogs.msdn.com/vstsue/default.aspx) in a week or two, and we’ll update MSDN at the next opportunity, probably a few months from now.


Tony Edwards said...

Moreover, I'm a member of the development team that changed the behavior of renamedt. We did a poor job of communicating these changes to the writing team. I would like to apologize both to the users who are experiencing this issue and to our writing team for the omission.

Mac Noland said...

Thanks Tony and Allen for the feedback!

Being we're under a tight deadline, we actually opened a support call to help us. Do you think they'll be getting the updated instructions early next week so we can continue on with the test restore? Maybe they already know about them?

Allen Clark, Programming Writer, Team System said...

We're still working out the steps that will work reliably. As soon as we have them, we'll post them. We'll also send support the updated procedure. Sorry this is taking so long.