Inside TeamSpec
TeamSpec Motivation
After many years of contributing to and running software projects, we realized a few things:
- Many roles in a software teams perceive (and some realize) value in using documents to define and manage project requirements and artifacts.
- Short after starting the project, and especially in large projects, documents become stale and no longer represent the code, which should implement the original requirements. This is the core of the Stale Requirements Document Problem and occurs independent of the methodology used.
- Once the documents become stale, it is very difficult for anyone (usually the Project Manager) to analyze the state of the code and update the document.
In order to visualize the Stale Requirements Document Problem, the figure below shows why the challenge of keeping a document up to date with what the code (in source control) implements is almost impossible. Every time a code change is made (resulting in a changeset) the question that arises is “How does this affect the requirements and goals of the project?” The hope is that the changeset implements a requirement either exactly or partially, but verifying and measuring this is very difficult given the lack of precision. In small teams, this usually results in developers running the value delivered to the customers, which may be acceptable (in teams between one and three people) if the developers are close to the customers. In larger teams, this results in chaos and failed projects.
TeamSpec and TFS Solutions
TeamSpec enables the Business Analyst, Project Managers, and Executive Management to contribute to the Application Lifecycle. The development team continues to work against Tasks and code changesets, which can be rolled up to higher level project artifacts which are also represented as Work Items in TFS. TeamSpec allows team members to
- Create structured documents out of project artifacts (Change Requests, Scenarios, Tasks, among other Work Item Types) using TeamSpec Skins.
- Using existing documents, content can be pushed into Team Foundation Server which can then be used to manage software projects.
As shown in the diagram below, TeamSpec allows users to use Microsoft Word documents to push content into TFS as well as represent TFS artifacts.
TeamSpec Future Vision
TeamSpec can help enact your team’s process by providing a familiar and effective document style interface to TFS Work Item Tracking. Requirements management enables change impact analysis (a part of traceability) which can be managed using TeamSpec on top of TFS Work Item Tracking.
Creating a list of TFS work items in my document
In order to bring TFS work items into your document you need to follow the following steps:
1. Adding a TFS Connection
Before you can start interacting with Team Foundation Server, you have to connect your document to one or many TFS Projects. Click on the
‘Add TFS Connection’ button in the TeamSpec ribbon (shown in Figure 1) to select the project and server. Notice that most of the user controls in the
TeamSpec ribbon are disabled until you connect to TFS. Another interesting thing to notice is that the TeamSpec ribbon is broken up into two groups, the TFS
group and the TeamSpec group. The TFS group enables users to interact with the TFS features (such as Server/Project connection, creating new work items,
managing work item queries, searching for keywords in work items) and the TeamSpec group enables users to interact with TeamSpec specific features (such as
Managing Skins, Managing Document Links, toggling the TeamSpec panel, etc…). Together the TeamSpec ribbon and the TeamSpec panel enables the core
interaction between TFS and the Word document.
Figure 1
2. Finding TFS work items
There are a few different ways to find TFS work items in TeamSpec. The easiest is Quick Search. To find a set of TFS work items based on a
keyword or phrase, type the words into the text box highlighted in Figure 2 and press the binoculars to the right of the Quick Search text box. Since we’re
connected to the ‘reignman’ TFS server and the ‘Beta’ TFS project, the TeamSpec panel has now made itself visible and is opened to the Index tab. We can
hide it by toggling the ‘TeamSpec Panel’ button on the ribbon. The Index tab serves two purposes: organizing the work items and work item fields referenced
in the document and managing the sync state of the work item fields in the document. One of TeamSpec’s core value propositions is the ability to manage the
state of work item fields in the document as they change either in the document or on the server side.
Figure 2
3. Using a TeamSpec Skin to insert the work items into the document.
A set of work items are inserted into the document given a specific layout and formatting by selecting a work item or group of work items and
selecting ‘Skins’ in the context menu. A Skin from the most-recently-used list can be selected to insert work items into your document or you can select
‘Browse For Skin...’ which will allow you to browse to your local disk, a shared location, or a SharePoint site that contains TeamSpec Skins shared by your
team.
TeamSpec Skins specify the formatting and layout used when inserting TFS work items into the document. A group of default TeamSpec Skins are
provided out of the box, however, users can easily create and share TeamSpec skins directly inside Microsoft Word that represent the layout they desire.
We’ll get into how to create a TeamSpec Skin in a future section.
Figure 3
4. Using a TFS work item query to find work items
Since we’re trying to create a Scenarios Document using TeamSpec, we can use the TeamSpec Query Manager to run the Scenarios TFS query and
insert the set of Scenario work items into the document using a Skin. We open the TeamSpec Query Manager by clicking on the ‘Work Item Queries’ button in
the TeamSpec ribbon, we can run the Scenarios query in the ‘Beta’ TFS Project.
Figure 4
Upon selecting the ‘Table Row Item’ Skin, one of the default Skins provided with TeamSpec, the selected group of work items are inserted into a
newly created table. Now that we have work items in the document, clicking on the field name in the Index takes the cursor to the location of that field in
the document. Likewise, clicking on the content corresponding to a field in the document highlights the field name in the Index. As you can see in Figure
5, I clicked on the Title of work item 321.
Since we’re not going through fields with modified values we can minimize the Sync Panel (located at the bottom of the Index tab) and make
more space for the index by toggling the button titled ‘0 Differences.’ The Sync Panel opens up the size it was opened before when you re-toggle the
‘Differences’ button. When field values change in the document, the Differences button will show the number of changes in the document. We’ll cover going
through differences later in the walkthrough.
Figure 5
If instead of a table, I wanted a numbered list, I could have used the ‘Numbered List Item’ Skin as shown in Figure 6. By inserting these
Scenarios into our document and creating a document heading our requirements specification is starting to come together.
Figure 6
Publishing content from a Word document to TFS
There are two ways to create work items from content in the document: using the Associate tab and by dragging content into the Index tree.
Using the Associate tab to create work items from content in the document.
Now that we’ve created a Scenarios list in our document, let’s add more scenarios to it and publish that content to TFS. As shown in Figure 8,
we open the Associate tab and select the item 5 (and it’s child node) in the list. The Associate tab shows that we’ve selected the ‘Title’ and ‘Assigned To’
fields. We then click ‘Lock Template’ so that we’ll be able to use the pattern to associate items 6 through 8 that we just added.
Figure 7
After locking the Template, I select the group of items in the list that match the pattern I locked in the template and click the ‘Apply
Template’ button (as shown in Figure 8). If you have several different sections of your document that you would like to publish to TFS, after applying the
template to your first selection, you can select another group of items and apply the template again. This will create a new selection (in Figure 8 we have
a single select, ‘Selection #1’) named ‘Selection #2’ and so on. By default all fields for this new set of Scenario work items will be checked. You can
uncheck any work item or field to remove them before clicking the ‘Associate’ button at the bottom right. Once we’re ready, we click the ‘Associate’ button
and these work items get added to the index.
Figure 8
Once we click the ‘Associate’ button, TeamSpec directs the user back to the Index panel (as shown in Figure 9). You’ll notice a few things
about Figure 9.
- The content we just added and associated to TFS is now listed in the Index.
- The nodes that were created in the index do not have a work item number (like work items 318-322). Although they have a work item
association, they have not been published to TFS. We’ll do this in the next step.
- The state LEDs next to the field name in the index are grey indicating that there is no status relative to the server. You may have
noticed in previous figures that the state LEDs were green indicating that the field in the document matched the field value on the server. The color yellow
indicates that the value in the document does not match the server value. The color red indicates that the value in the document does not match the server
value and it cannot be synchronized. Two reasons why you have a red LED can be either the value you changed is from a read only work item field or you have
more than one instance of that field in the document with different values. You can use the Sync Panel to resolve the problem and convert the red LED to a
yellow LED.
- The Sync Panel is telling us that there are 6 differences in our document and our cursor is on difference 2 of 6.
In order to resolve these differences, we toggle the Differences button to open the Sync Panel.
Figure 9
After opening the Sync Panel, we can page through the differences by clicking using the pager control. Figure 10 shows the Next button on the
pager control which will allow us to move through each difference and make a decision for each. Since we haven’t published the work items to the TFS yet,
there is no server value shown in the Sync Panel.
As we page through the additions/differences, we notice that TeamSpec has selected the radio button for the value in the document. This is so
that you can sync and publish the values in the document to the server. Later in the walkthrough, we’ll show an example of choosing the server value and
pulling the server value into our document.
Figure 10
Since we’ve selected the document values for all of our differences in the document (the new additions), we can now click on ‘Sync Actions’ and
select ‘Sync’ (as shown in Figure 11).
The ‘Refresh Server Values’ item under ‘Sync’ is used to update the server values used to compare the state of each field. For example, since
the values on the server can change at any time, clicking this item ensures that the values stay up to date with the values on the server by updating sync
status (field LED colors) in the TeamSpec Panel.
Figure 11
If we explore the ‘Sync Actions’ drop down further we find the ‘Select All Differences’ fly-out (shown in Figure 12). This fly out is used to
select the Server or Document Value for ALL differences in a document. This makes it very easy in cases when you have a large number of differences and want
to take all the document values without paging through each difference.
Figure 12
Once we click the Sync option under the ‘Sync Actions’ dropdown, item 6-8 are published to the server and get assigned work item IDs (shown in
Figure 13).
Figure 13
Creating work items by dragging content from the document into the Index tree.
As shown in Figure 14, we’ve added another Scenario to our scenario list in the document. We then select the text we want to use as the Title
of a new Scenario work item and drag it onto the Scenario node in the Index tree.
Figure 14
Upon dropping the content block on the ‘Scenario’ node in the Index tree, TeamSpec opens the ‘TeamSpec Work Item and Field Chooser’ dialog
which allows us to select the Title field for the Scenario work item type.
Figure 15
After clicking the OK button, a new unpublished work item is created in my document similar to the unpublished work items that were created
when I used the associate tab. Notice, the my difference count has now increased to 1.
Since we also want to add a value for the ‘Assigned To’ field, we select the content below the Title field and drag that content onto the ‘New
Work Item’ node in the Index tab. This action opens the ‘TeamSpec Work Item and Field Chooser’ dialog which allows you to specify the ‘Assigned To’ field
for this work item.
Figure 16
As shown in Figure 17, we can now specify the Assigned To field and click the OK button.
Figure 17
Now we’re ready to select Sync from the Sync Actions dropdown (Figure 18). There are two interesting things at this point: if you toggle (and
open) the Sync Panel, you can see that similar to the Associate path of creating work items, TeamSpec has automatically selected the Document Value of the 2
differences.
Since the Assigned To field is an enumerated type, TeamSpec create a dropdown control in the document to allow the user to select from the
enumerated items. This also works for the Area Path, Iteration Path, as well as date based fields where TeamSpec uses the calendar control.
Figure 18
Creating customized TeamSpec Skins
If the TeamSpec Skins provided do not fit your team’s needs, you can easily create a custom TeamSpec Skin to bring work items into your
document. Creating a customized TeamSpec Skin is as easy as selecting a work item field in the document in the context of its formatting and layout.
We want to clear the Scenario list that we have created in order to represent the same list using a customized TeamSpec Skin. We right click
on the first work item (#318) and select ‘Send To Canvas’ as shown in Figure The TeamSpec Canvas is the place where we can drag and drop work item fields
and drag them into the Word document.
Figure 19
Upon selecting ‘Send to Canvas’, TeamSpec automatically opens the Canvas tab in the TeamSpec Panel (shown in Figure 20). Additionally, we
deleted our Scenarios list in the document and we’re ready to create a new list.
To create a new list we start off by creating some formatting. Since we want to create a list, we type “1. (space)”. Word determines that
this means that we want to start a list.
Figure 20
We then grab the Title field from the Canvas tab and drag it into the document at the desired position.
Figure 21
Upon returning to the Index tab, we notice that we now have Scenario #318 represented in our document. We’re now ready to select this item and
create a custom TeamSpec Skin.
Figure 22
By selecting the entire row of our numbered list and selecting the ‘Create New Skin’ item from the ‘TeamSpec Skins’ dropdown from the TeamSpec
ribbon (Figure 23), TeamSpec will create a new Skin given the selected work item field and document formatting (in this case the title field and a numbered
list item).
Figure 23
Upon selecting the ‘Create New Skin’ item in the drop down, the ‘Create New Skin’ dialog opens (as shown in Figure 24). This dialog allow us
to name the custom TeamSpec Skin and shows us the fields that will be includes plus the TeamSpec Skins path where the newly created TeamSpec Skin will be
stored. This path can be changed in the ‘Manage Skins’ dialog.
After naming our custom TeamSpec Skin, we click the Create button.
Figure 24
We’re ready to use our newly created custom TeamSpec Skin so we position the cursor in the document where we want to insert the work items (see
Figure 25). Similar to the beginning of the walkthrough, we use the TeamSpec Query Manager to insert the rest of the Scenarios into the document.
Figure 25
Figure 26 shows us inserting the set of work items into our document using our new TeamSpec Skin.
Figure 26
Once we select the skin that we want to use to insert the work items into our document, the TeamSpec Query Manager closes and we now have the
list of Scenarios with our new formatting.
Figure 27
Making TeamSpec Document Discoverable
In addition to storing content that was traditionally stored in a document stored in the centralized TFS work item database, we also want team
members to easily find documents that contain work item content. We invented ‘Document Links’ to solve this problem.
First we save our document to the project’s SharePoint Document Library as shown in Figure 28.
Figure 28
Once we’ve saved the document to a location that is available to the rest of the team, we click the ‘Document Links’ button on the TeamSpec
ribbon. The Document Links dialog shows us the saved location/path of the document as well as a list of work items that are referenced in the document.
We can create a link to the document from one or many work items by selecting the work items in the list and clicking the Add button.
Figure 29
After selecting the entire list of work items and clicking Add, we return to the Document Links dialog (Figure 30) and notice that all the work
items now contain links to the document.
Figure 30
In order to verify that the link has been created in the work item, we right click on the work item and select ‘Open Work Item Form…’ (Figure
31)
Figure 31
When we open Work Item #318 in TeamLook, we notice that the work item now has a link to the SharePoint Document Library.
Figure 32
