Compartilhar via

Thoughts on Managing Documentation Efforts in Team Foundation Server

  • Artigo

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

Document-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.

Item-Centric

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”:

image

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:

image

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.

Summary

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.

Enjoy!

Comments

  • Anonymous
    April 24, 2012
    Thanks for putting together this interesting discussion on documentation. I'm not exactly sure how we will be implementing documentation but it is nice to know that there are several approaches and some interesting tools that can be used. Thanks for the information.