Steve Lange @ Work

Steve Lange's thoughts on application lifecycle management, Visual Studio, and Team Foundation Server

April, 2012

  • Steve Lange @ Work

    Slide content from Denver ALM Roundtable


    This is a slightly tardy post, but here is a link to the presentation slide deck used by Peter and Matt during the ALM Roundtable in Denver.  You’ll see that it’s rather light; but keep in mind the slides were merely for talking points leading to more demo (remember, this was a demo-heavy event!).

    If you have any questions, please let me know!

  • Steve Lange @ Work

    Thoughts on Managing Documentation Efforts in Team Foundation Server


    I’ve met with several customers over the last few months who either are, or are looking to, manage their documentation efforts in Team Foundation Server.  There’s not much guidance or documentation about the best way to do that.  Now my blog is hardly a repository of impactful information; but I hope this post helps to shed some light on practices that can be used to manage documentation in TFS.

    In thinking about this, the concept of documentation management is somewhat similar to requirements management:  A document format is the ultimate output, consistent capture and management is ideal, and a development workflow is needed.  Several years ago (when TFS 2005 was the current release), I blogged a four-part series on requirements management in TFS, a series which many seemed to appreciate.  (Since then, a much more robust, prescriptive guidance has been published on CodePlex around TFS 2010 called the “Visual Studio Team Foundation Server Requirements Engineering Guidance” ). 

    There are two main schools of thought around using TFS to manage documentation efforts:

    • Document-centric
    • Item-centric


    In the document-centric approach, the document itself is the “version of the truth”. Updates are made to the document directly, and either TFS or the associated SharePoint site manages versioning.  Any approval workflows are handled by SharePoint.

    The benefit of this approach is that people already know how to edit a document (Word is the most popular requirements management tool, as well!).  It’s natural and seemingly convenient to just pop open a document, make some updates, hit “Save”, and close.  When the documentation process is finished, you already have your “output” – the document itself.  Just convert it to the format that you want (PDF, XPS, whatever), and you’re done.

    The drawback however, is in its simplicity.  You lose formatting consistency of individual sections of the document, as well lower-level management of those sections.  This results in extra scrutiny over a document to check for those inevitable inconsistencies. If you have traceability requirements in your process guidelines, it’s going go be very difficult to accurately relate a specific section within a document to another artifact in TFS.  It’s quite near impossible to report on the status of a documentation effort, other than “the document is or isn’t done yet.”  There are no metrics around how much effort has been applied to the documentation, how many people have collaborated on it, etc.


    The item-centric approach uses the work item tracking system in TFS to manage components/pieces of documentation individually.  This is accomplished by creating a work item type designed to support individual pieces of documentation.  In this scenario, TFS becomes the “version of truth”, and the actual document is really just an output of that truth. (Think of this as similar to version control, which houses the truth of your code, and the build is the output of that.)

    Several of these RM-centric approaches can be applied toward documentation efforts:

    • Custom work item types
    • Consistent UI for consistent data capture
    • Querying and reporting
    • Categorization or classification

    Below is just one example how a “Documentation”-like work item type might look in TFS:

    Sample documentation work item type

    You’ll notice there are standard fields such as title, assigned to, state, area, and iteration.  In this example, there are a few custom fields added as well:

    • Document Structure (group)
      • Target Document
      • Document Order
    • Documentation

    Target Document allows you to target a specific document that this documentation piece belongs to.  In my example, I use a global list for this field, allowing choices of End User Manual, Administrator’s Guide, and Installation Guide.

    Document Order is a field I created to help with the ordering of the documentation piece (for sibling work items) when it is finally output into a document.

    In TFS 2010, you also have the added advantage of work item hierarchy to better help organize the structure of your documentation. You can use hierarchy to break down sections or areas of the document.  Viewing the “structure” of a document (like a document outline in Word) is a matter of constructing a query.

    For example, below is a query result that shows a document hierarchy for my “End User Manual”:


    There are a few very tangible advantages of using this approach:

    • Each section of documentation is individually manageable.  They can be assigned to different people, follow individual workflows, and be reported on and queried against.  Documentation can much more explicitly be planned as documentation work items can be put into sprints, iterations,etc.
    • Sections can be modified using a number of tools (Team Explorer, Excel, Web Access, or several 3rd party integrations).
    • Documentation work items, as they are work items, can be related/linked to other artifacts they support.  For instance, you can tangibly relate a build, task, requirement, or even code to a piece of documentation.
    • You can use work item queries to help identify and track the progress of your documentation efforts.  For example, while the previous screenshot shows the entire tree of documentation items, you could have another query to display the items that haven’t yet been completed:


    Creating your Document

    Sounds great, right?  Oh yeah, but what about actually creating the document itself? (What, you don’t just want to dump the query results to Excel and format from there?)

    Well, the first main step is to get your work items exported to a Word document (for any fine tuning) and ultimately converted to your final output format (probably PDF).

    If your list of documentation work items is flat (i.e. no hierarchy, parent/child relationships), that simplifies things because you can dump your work items to a file format that can be used as a merge source for Word (like a TSV or Excel file).  Then you really just have to worry about formatting your document appropriately.

    And there are a couple of 3rd party tools that you may (again, based on your specific needs) be able to leverage.  These tools work to integrate Word with TFS, and each carries their own pros and cons:

    It gets more complicated as you work with a hierarchy.  In my above example, I want my work item hierarchy to reflect  a document hierarchy in the output document (i.e. first level gets Heading 1, second level gets Heading 2, etc.).  That puts a small wrinkle in things.

    So when in doubt, roll your own.  I have several customers who have implemented custom utilities to export their documentation work items to a Word document.  Given my amateur status as a programmer, I thought I’d give it a shot myself.  More on that in a future post, but the basic idea of such a utility is something like this:

    1. Select the WI query that gives you the work items you want, in the right order, etc.
    2. Select a document template to use, or at least a document style.
    3. Click “go”, and watch the utility run through each work item in the query results, inserting field values in the appropriate placeholder (named area, bookmark, whatever) in the document.

    Again, more on that later.


    So keep in mind that while your mileage may vary in terms of approach and need, it is definitely possible to leverage TFS WIT as repository for your document development needs.  My examples above are by no means the only way to attack this topic – I’ve just seen them work with other customers of mine.


  • Steve Lange @ Work

    Content from the VS11 ALM Roadshows (Denver/Phoenix/Lehi)


    Happy Monday!

    First, thanks to all of you who have attended the ALM Roadshows so far, and I hope to see many more of you attend the upcoming stops.

    VS 11

    Many folks from the Denver and Tempe events asked if the content would be made publicly available (to help minimize the amount of note-taking required).  So as promised, this morning I posted the slide decks from the three sessions on SkyDrive here:

    Here are direct links to the individual sessions:

    1. Continuous Delivery
    2. Beyond Software Testing with Agile Team Support in Visual Studio 11
    3. Beyond Code - Increasing Developer Productivity

    And again, if you want to more easily download all the session content, you can view the entire folder here.

    The demos performed during the sessions are very similar to the labs which are included in a publicly-available VM by Brian Keller.  Download the VM + labs from here and enjoy a pre-configured environment will all the VS11/TFS11 Beta goodness ready to roll.

    For those of you that will be attending a roadshow event in the near future, take note: Exact content varies between venue, so the content I posted is really most applicable to Denver, Tempe (Phoenix), and Lehi (Salt Lake City).

    And as a reminder, if you can’t make it to an in-person event, definitely check out some of the many webcasts being delivered as well.

  • Steve Lange @ Work

    Holy VS 11 Webcasts, Batman!


    Want to learn more about Visual Studio 11 and TFS 11 but can’t make it to an in-person roadshowCheck out this line up of “11” webcasts provided by our awesome ALM partners.  Topics include:

    • A View into Microsoft's New ALM Features and Tools
    • Agile Planning
    • Managing Requirements & Customers
    • Testing Tools
    • Cross-Platform Development
    • Storyboarding
    • Exploratory Testing

    .. to name a few.  Check out the list of webcasts and sign up!

Page 1 of 1 (4 items)