Self-Documenting SCM Software

  • Article

Visual Studio 2005 Team System (VSTS) won’t RTM for another year, or so. And while many of the major architectural design decisions have already been made, our software configuration management (SCM) lexicon remains somewhat in flux; and rightly so! In preparing for the big unveiling at TechEd, the VSTS user education team, in cooperation with our program managers, developers, and testers, hammered out a comprehensive set of scenario-driven whitepapers for VSTS that describe most of the mainline usage scenarios that are possible today. If you want to thank one person for these great papers, thank Rob Caron, who coordinated their production. Rob is responsible for the end-to-end documentation user experience for VSTS. Got doc ideas? Ping Rob.

Since I write documentation, you might be surprised to learn that I don’t WANT you to read my help topics. Okay, you can read my whitepapers but I don’t want you to have to read the help topics that I write for simple, or what should be simple HowTos. I certainly don’t want you to have to read the help topics that I write for error messages. Nope, the ideal software application is completely self-documenting: 100% UI text, 0% KorbyHelper. And the foundation of self-documenting software is intuitive user interface text.

Late last night, after a long day of TechEd that commenced with the keynote announcement of VSTS, I bumped into Kevin Kelly and Brian White, who are the VSTS program managers for work item tracking.  Kevin, a seasoned Microsoft veteran, and Brian, a recent recruit from Rational, had just returned from dinner with a gaggle of important customers and were obviously ready for a little R&R. I joined them in the bar for a glass of lime and gin-flavored ice water and mercilessly peppered them with SCM terminology questions (my name is Korby and I am a terminology junkie)…

  • Will customers from a VSS or ClearCase background understand what a ‘workspace’ is intuitively?
  • Should we define ‘work item’ (ie, tasks, bugs, requirements, features) in each help topic and whitepaper on first use?
  • Is the ‘shelve’ command verb self-descriptive enough? Is there a better alternative?
  • Why did the chicken cross the road? To rollback its checkin. Perhaps we should use ‘check-in’ instead?
  • Should we run with ‘work item tracking’ or ‘work item management’? Does it matter?

As the Team Foundation team continues to build, refine, and document VSTS I plan to blog often about these and other terminology issues and questions and invite you to provide your input.