Team Foundation Server (TFS) is the core of Visual Studio Team System (VSTS), an Application Lifecycle Management (ALM) platform from Microsoft. TFS offers integrated team portal, version control, work-item tracking, build management, process guidance and business intelligence functionality. TFS provides interactive online documentation based on Microsoft Solutions Framework (MSF), a proven methodology for planning, designing, implementing and deploying information systems and solutions.
Out of the box, TFS 2008 comes with two varieties of process guidance: MSF for Agile Software Development and MSF for CMMI Process Improvement. MSF Agile process was designed for smaller teams and teams that use agile development practices, while MSF CMMI process was designed for larger organizations, particularly those using CMMI (Capability Maturity Model Integration) approach, teams that require a higher degree of control and visibility over their projects.
You can learn more about MSF Agile and MSF CMMI by reading the process guidance that comes with TFS. If you don’t have access to a TFS project with the process flavor you are interested in, you can download it from MSDN using the links below. Simply open ProcessGuidance.html located in the Windows SharePoint Services\Process Guidance folder in the location where you extracted the project template files.
MSF Process Guidance is Only a Template
While MSF Agile and MSF CMMI templates can serve as good starting points for many organizations, there is rarely a perfect fit. The Agile template fits well most of the small- to mid-size IT organizations, however it uses terminology that is too specific to agile software development. Its term Scenario represents what is commonly referred as Service Request or Change Request; the term Bug refers to what is commonly known as Trouble Ticket or Defect Report. The CMMI template uses more appropriate terminology, but due to the large number of work-item types and roles, it is simply an overkill for most organizations.
Today, a typical MIS department usually has a small number of roles (such as Business Analyst, Project Manager, Developer, Database Administrator, Help Desk Technician) established and follows an existing process for managing the change requests and trouble tickets. This process may be based on paper or electronic forms, it may not be perfect, but it is already working. When this organization adopts TFS to improve their process, should they go ahead and adopt MSF Agile or MSF CMMI?
Adopting a new process approach (what you do) at the same time as adopting a new process management tool (how you do it) is a risky proposition. People are creatures of habit and require time to change either the process they follow or the tools they use. Imagine if all cars in a country had to be changed to use voice control instead of traditional steering (change what you do) and that people had to speak to their cars in Esperanto (change how you do it). In the resulting chaos, we can be certain that both the congressman who proposed this improvement and the president who didn’t veto the proposal will not be as popular anymore.
When adopting TFS, unless your IT organization is following the MSF Agile or the MSF CMMI process to the letter, it is much safer to start by customizing the TFS process to match your own. Once your organization is comfortable using TFS as the new process management tool, you can begin adjusting the process itself using TFS. Microsoft provided extensive documentation (see links below) on how to customize the workflows, work items, reports and other features of TFS. However, customization of the process guidance received relatively little attention. Yet in the process of adopting TFS, providing matching guidance for a customized process is very important to ensure the overall success. Outdated guidance will cause confusion, mistakes, delays and frustration for the MIS department and its business partners. So how do we change it?
VSTS Process Guidance Generator
Microsoft used the Guidance Generator to produce MSF Agile and MSF CMMI guidance for TFS 2008. This tool replaced MSFWinBuild which was used to produce the guidance in TFS 2005. Unlike its predecessor, it uses plain XML file to define contents of the guidance and T4 templates to generate the actual collection of HTML files, included in TFS project templates as process guidance. The remainder of this article will show a typical set of steps you would need to perform to customize guidance for your TFS project.
Installing Guidance Generator
- Download latest version of the Guidance Generator (188.8.131.52 at the time of this writing) to your local hard drive.
- Unblock the ZIP archive you downloaded as shown on the right. This will ensure that the application will not run into any unexpected security errors.
- Extract files from the unblocked archive to your hard drive.
If you are running a 64-bit version of windows, you will need to use the CorFlags command line tool to make sure that the generator runs in 32-bit mode. This will help you to avoid errors that occur when the generator attempts to load 32-bit-only assemblies it requires.
- Use Command Prompt window to execute the following command in the bin\bin sub-folder at the location you extracted the files.
C:\GuidanceGenerator\bin\bin>corflags TextTemplatingMultiprocessor.exe /32BIT+ Microsoft (R) .NET Framework CorFlags Conversion Tool. Version 3.5.21022.8 Copyright (c) Microsoft Corporation. All rights reserved. C:\GuidanceGenerator\bin\bin>
Once you have the Guidance Generator installed, your first task is to pick a template (Agile or CMMI) that you will be using as a starting point in your customization. If you are customizing guidance for an existing TFS project, you will want to minimize the amount of editing, so pick the template that matches matches your project.
- Double-click the Run Tool.cmd file in root folder at the location you extracted the files to start the generator.
- In the TemplateProcessor window, enter the following parameter values.
Source DSL File: agile-guidance.guidance
Template Directory: HTML_Templates
Target Directory: agile-Generated\Process Guidance\Supporting Files
The source file provides content of the guidance. In this example, we are generating process guidance from the source file called agile-guidance.guidance to the output directory called agile-Generated. To generate CMMI guidance, we would need to change these values to cmmi-guidance.guidance and cmmi-Generated respectively.
- Click the Go button.
The generator runs for a while and you should see the a log displayed in its output window with information about the number of files that were generated. Once you see “Done”, you can open the generated guidance by double-clicking the ProcessGuidance.html located in the agile-Generated\Process Guidance folder. The actual output files are generated in the agile-Generated\Process Guidance\Supporting Files folder.
Customizing Guidance Content
The guidance content is located in the .guidance files - agile-guidance.guidance and cmmi-guidance.guidance. These are rather large XML files that define topics describing team member roles, work streams, activities, work products, work items, reports, glossary entries and more.
Limited information about the structure of this file can be found in the UserGuide - Guidance Generator.pdf located in the root folder where you extracted the Guidance Generator files downloaded from CodePlex. This information is by no means complete nor, due to its volume, would not be practical to describe in a single article. In one sentence, this structure can be summarized as this. There is a one-to-one relationship between the major xml elements and the generated HTML files, for example, BusinessAnalyst.htm file is generated from the XML element <Role Key=”BusinessAnalyst”>. If you want to change content for particular HTML file, find the XML element with matching Key and change its contents.
Editing such a large and complex XML file is challenging. It was not meant to be edited by hand and the internal tool Microsoft created for editing it was not released to public. You may be tempted to use the XML schema file, GuidanceModelSchema.xsd, to enable IntelliSense and enhance your editing experience in Visual Studio, but unfortunately, it appears to be outdated and doesn’t match the supplied .guidance files.
Instead, you will need to frequently re-run the generator to verify that content you are modifying produces the HTML you expect. You can reduce the amount of time it takes to regenerate output by setting Template Files parameter to regenerate only a the particular type of file you are working on. For example, Business Analyst.htm is generated by the T4 template called Role.htm and you can regenerate only role files like so.
Customizing Guidance Output
Guidance Generator uses T4 templates located in the HTML_Templates directory to generate output HTML files (in the Supporting Files directory). There is one template file for each major type of XML element in the .guidance file (<Role>/Role.htm, <Activity>/Activity.htm). As you can see, the T4 template files are saved with .htm extension which might be confusing at first.
To change look and feel of the generated HTML, you can start by changing the CSS\msf.css style-sheet or changing the image files to display your company’s logo. However, if you need more substantial changes, you may have to modify the T4 templates that generate the HTML. For detailed information about T4, please see my previous article, Text Template Transformation Toolkit.
Publishing New Guidance
Once you finish changing the guidance, you can package it in a TFS process template, or simply upload it to the Process Guidance folder on your team portal.
TFS is a powerful collaboration platform for IT organizations. Although TFS comes with two pre-packaged process templates (MSF Agile and MSF CMMI), it is often beneficial to customize them to better fit the process already used by your organization. It is also important to keep documentation in sync with the process you are using and minimize confusion among the members of the immediate IT team as well as the business users. Guidance Generator is a powerful tool for customizing the built-in process guidance that comes with TFS. Although the Guidance Generator is not very easy to use, the interactive documentation system it produces is well designed, easy to use and would be challenging to replicate in hand-crafted HTML or Word files. In most cases you will want to start with an existing process guidance that most closely matches your current process and customizing it, hopefully by simply removing the MSF concepts you currently don’t use.
- MSF for Agile Software Development (TFS Project Template)
- MSF CMMI Process Improvement (TFS Project Template)
- How To: Customize a Process Template in Visual Studio Team Foundation Server
- Team Development with Visual Studio Team Foundation Server
- VSTS Process Guidance Generator
- Text Template Transformation Toolkit
- Team Foundation Administrators: Customizing Process Templates