Here at SuperOffice R&D we have always used specifications to plan work on new features. We have a long tradition of doing lots of design + prototyping work up front. User Experience Design is one of our a core strengths, and good UX takes a fair amount of work before you give it to the team to implement.

So when we moved over to TFS we were trying to figure out how to integrate our spec-driven design workflow into the TFS pipeline that the development teams wanted to use.

The problem we faced was two-fold:

• We like to use lots of illustrations in our specifications, which TFS work items supports using attachments, but not in-line with the text.
  You can imagine what this blog post would be like with all the pictures on separate pages instead of in-line with the text
• We like to update the specifications as we uncover new details – so having a diff and a list of chapters with changes is useful. The specification is not a static thing.

The solution we came up with has four parts:

1. Specification documents are worked on as before, with rich text and screen mockups. The DOCX files are checked into TFS. The design team edits + updates the files as they have always done.
2. Custom Word Ribbon to make it easy to create work items based on chapters in a DOCX file. The ribbon inserts the work item id into the text.
3. Regularly scheduled document splitter task on the TFS server that grabs the latest DOCX files, converts each file to HTML and splits it into chapter sized chunks of HTML.  The system also computes the diff whenever a fragment changes, and posts the diff to the work-item history, so developers + QA can easily see what changed in the spec.
4. The User Story work item uses a web-control to display the corresponding HTML fragment. This makes it easy for the developer to view the feature description and the illustrations in context.

Specification Documents

These are just word documents with pictures and headings.

Typically we will have a structure like this:

• Introduction
• Feature A
  • Feature A Screen
  • Feature A Dialog
  • Feature A Sub Dialog
• Feature B
  • Feature B Screen
  • Feature B special consideration
• Tech Details

Each chapter maps to a user story (roughly). Each chapter starts with a picture or illustration of the desired part of the feature. Sometimes a feature will exist in multiple variations (basic, plus, full-blown) with more stuff added each time. In these cases the additions are highlighted in the pictures.

The advantage of working with a MSWord document rather than the user story items directly is that context and

Word has a new ribbon we’ve built for making user-stories + test cases based on the document contents.

We select a root User Story using the ribbon. We typically have a special user story to represent the spec as a whole that all chapter stories are linked to as children.

This tree of work items can be seen in TFS using the new hierarchy queries:

This makes the user stories easier to find, and makes it easy to get a look at the progress made within a spec.

You don’t have to do this kind of hierarchy – but we find it gives us a bit more structure.

Anyway – having selected the work item that new work items will be parented to, we can go through the spec with the team, using the ribbon to create User Stories out of chapters.

When we come to a new chapter heading, we place the cursor in the chapter and click the CREATE USER STORY button.

This displays the simplified USER STORY DIALOG. Most values are copied from the parent user story (Assigned To, Area, Iteration).

Clicking OK creates the work item in TFS. The work item id is inserted into the heading, so that document splitter can match the chapter with the work item.

The work items are used for prioritizing and scheduling. Previously we would mark certain chapters in the spec as “for later”; now we can leave the spec alone and just edit the work item “Priority” field instead.

When the review is finished, the headings have all been decorated with work items.

• Introduction
• Feature A #123
  • Feature A Screen #124
  • Feature A Dialog #125
  • Feature A Sub Dialog #126
• Feature B
  • Feature B Screen #127
  • Feature B special consideration #128
• Tech Details #129

The review ends and the updated specification document is checked in to TFS.

Checking the document into TFS triggers a server task.

Regularly Scheduled Doc Splitter Task

A dusty server sits in a rack and runs a scheduled task every 10 minutes:

• Sync the Documents folder from TFS to the local file system.
• Run a through all the documents in the Documents folder:
• If a document has changed in the last 15 minutes:
  • Convert the document to HTML
  • Run through the HTML document and split each chapter into a separate HTML file. Use the id found in the chapter title as the filename.
    e.g. “Add System Event Dialog #1574” –> 1574.html
  • Compare the new chapter HTML document with the previous version.
    • If there is a diff, write the diff to the TFS work item history.
    • If there is a diff, change the TFS work item state to “Spec Changed”
  • Overwrite the previous version with the new chapter HTML document.

The chapter-sized HTML files are copied to a a website folder, where a simple ASP.net page takes a work-item-id as a parameter, and redirects to the page if the page file exists. You could link directly to the chapter files, but then you get ugly error messages when the file doesn’t exist. We prefer the intermediate step – so we can do something more useful (like display the user story description when there is no chapter file present).

User Story Web Control

The Work Item Template for User Story has been altered – we have added a new tab for Specifications which contains a single large web-control.

The web-control passes the work-item id in the URL.

The website digs out the file with the work-item id in the filename and redirects to it, giving the developer this view:

This web panel displays the images and text from the corresponding chapter in the spec.

The history tab tracks the work item changes and also shows the changes in the spec:

Summary

This is a simple and straightforward way for us to get our specification workflow plugged into TFS without forcing too many changes on how we work with our designs.

The web panels give us read-only access to the specification.  In an ideal world we would be able to directly edit the spec in the work item, but not having this hasn’t stopped the spec viewer from being useful.

Having the relevant part of the specification easily available and up-to-date is vital if the result is going to resemble the design. When the design sketches + descriptions are in easy reach of the developer, the work that is handed over to QA is much closer to what QA is testing for.

The QA team can develop test plans based on the spec chapters when the spec broken into small User Story pieces.

We have discovered that we are writing our specs differently – we are breaking features into smaller pieces. When we have several variations of a feature, each variation gets a separate chapter – this makes backlog management simpler.