In the past, we managed our work by defining the topics that we need to write, and then estimating and prioritizing the work to write those topics. Before VS2010, that worked really well. We documented the features that the product team created. As they created new features, we added topics to the backlog. However, for VS2010, we started thinking differently about what we write. We try to make sure that we’re writing about tasks that you want to perform, not just features. For example, in VS2008, we had a section on Setting up a Build Machine that was a collection of information on using features related to setting up a build machine. However, it failed to completely cover the task of configuring a complete build system that you can then start to use. In VS2010, the writer looked at the this from the perspective of the developer’s task instead of the build features and made the following improvements as a result:
Added information to the section (now called Configuring Your Build System ) so that it now helps you understand what options you have ( Understanding a Team Foundaiton Build System ).
Replaced the list of How-to’s with an outline of everything you need to do.
Finished with a link to what you’re most likely to want to do next: Build the Application .
Now, we plan our work around these development tasks. Each is a work item in Team Foundation that we call a story. The stories are the items in our backlog that we prioritize, estimate, track and report our progress against. For example, one story in our backlog is “Create an application that subscribes to Team Foundation events”. When that one is popped off the top of the stack and written, the content won’t just cover the relevant APIs, but it will tie them together from beginning to end, with the information that you need to be successful in that task.
We have some guidelines that help us make sure our stories effectively meet our planning needs. The most important of these, I think, are:
Describes what the developer (or project manager, administrator, etc) does, not what the product does.
Has a start, finish, and outcome.
Has a title that is clear to our team, management, the product team, and our customers
By taking the time to define our stories well, we have defined some content that will be more valuable than topics that just cover features. But, as with all things, we don’t have time to do everything. So the next thing that we did is estimate and priotize the work so that we do the most important things first. I’ll post something about that soon….(read more)