Stuff Yaron Finds Interesting

Technology, Politics, Food, Finance, etc.

Tools of the Software Program Manager Trade

In my previous article about what a PM does I talked about contracts. While I didn't mean contracts in the literal sense of a legally binding document the best PM groups I've worked with do produce a specific set of documents which serve to record what has been agreed to, track status and help to identify and resolve problems. Below I walk through those documents and what their purpose is.

Being a PM can feel like being an over priced e-mail router but in truth the most powerful tool of the best PMs I have worked with is the Word Processor (and for bad PMs, PowerPoint). Word processors matter because bad PMs have a habit of striking oral agreements with the folks they are working with and the old joke that an oral contract isn't worth the paper it's written on is completely true. For an agreement to be well understood and tracked it needs to be written down. The following are the types of documents the best PM groups I have worked with generate:

  • Market Requirements Document (MRD) – Provides a 60,000 ft view of what the development team's charter is, what market they are going after, who their customers are, who their competitors are and what the product will deliver. A high quality MRD will provide a one paragraph summary of what the group is all about. It will crunch the data that has been collected on customers and use it to create some typical customer profiles so the group can focus on who their customers are. It will define a set of mission critical scenarios that the group has to satisfy in order to be successful. It will identify any critical non-customer focused success factors such as legal issues, regulatory issues, etc.

  • Product Requirements Document (PRD) – Translates the scenarios in the MRD to implementation requirements for the current release. The PRD provides the detailed contract for exactly what the development team is agreeing to deliver and when it is agreeing to deliver it. Good PRDs give a unique label to each requirement so it can be tracked through the code and tests and validated as having been met. PRDs will typically define customer facing APIs, customer facing protocols, customer facing user experience (UX), any development dependencies (with a link to that group's PRD), service level agreements and operations dependencies. The PRD, written in deep partnership with Dev and Test, tells the team and the world what functionality the product is going to deliver.

  • Ship Specification – This specification is a catch all for issues that Dev/Test doesn't need to be directly involved in. For example, this document tracks the list of groups outside of the development team who have to sign off on the product in order for it to ship (e.g. senior management, legal, privacy, PR, marketing, etc.) It also tracks non-Dev/Test deliverables like documentation, sample code, standardization work, etc. The goal is to have a complete enumeration of all dependencies that aren't appropriate for the PRD.

  • Status Emails – The best teams I was on regularly send out a status mail, typically once a week, giving visibility into what the team has accomplished and where they are going next. One of the banes of a PM's existence are surprises. If PMs don't want other groups to surprise them then they need to return the favor by giving a lot of visibility into what they are doing.

These are all very much living documents. As competitors do something new or new customer data comes in the MRD is updated. As issues are found in the implementation or changes are made in the design the PRD is updated. As dependencies are added or removed the Ship Specification is updated.

There may or may not be a single MRD or PRD. For example, a detailed analysis of a competitor would likely go into its own document and a link to it put into the 'main' MRD. The PRD is almost always a collection of documents that cover different areas of the product.

In addition to the previous documents, which are usually written by the PM team, the following documents are typically written by development or test. But these documents are critical for PMs to do their job of ensuring the team will keep its end of its contracts. In fact these documents are so critical that when I have been in situations where the dev team couldn't or wouldn't deliver them I have written them myself.

  • Architecture Design Document – Explains how all the major components of the system are related to each other.

  • Functional Design Document – These translate the PRD into actual technical design. This records the details of how an API, protocol or UX will be implemented.

  • Test Design Documents – Defines how the testing framework will be built as well as well as how the testing team will approach testing product functionality.

  • Ship Schedule – Identifies major work items, specifies who owns each item, identifies dependencies between items, estimates how long each item will take and tracks how close the item is to completion.

  • On Boarding Document – Development teams have a lot of process, they just don't always admit it. They have rules for what their code is supposed to look like. They have rules for how bugs are to be filed. They have rules for how build verification tests (BVTs) are to be written. They have rules around how unit tests are to be managed. Where functional tests are supposed to go. How issues are to be escalated. These rules exist but they are often not written down which causes needless pain every time a new team member is added. So good teams write these rules down. The process has the salutary effect of making sure that everyone actually agrees on what the rules are.

The previous documents are all 'team' documents. They describe things relevant to the entire team. There are two more documents that I use on a regular basis to help me do my job.

  • To Do List – Being a PM means juggling at least 10 or 20 issues at any instant in time with another 100 or so on the back log. It is therefore incredibly easy to drop things accidentally. To deal with this I keep a to do list which lists all the work items I owe other people and the work items other people have promised to deliver to me. I rarely go more than a few hours, much less a day, without consulting and updating my to do list.

  • Weekly Status – Every week (or so) I send out a brief weekly status that outlines what interesting meetings I had, gives a one line summary of what happened and notes any work items I completed. I then list any interesting meetings for the next week and what work items I expect to accomplish. I use this to communicate with the numerous groups I am typically responsible for directly coordinating with. This is a bit more detail than is appropriate for the team status email but helps me work with the dependencies I personally own. It's also insanely useful around review time since I have a complete record of all the interesting things I have done.

3 Responses to Tools of the Software Program Manager Trade

  1. Robert Van de Water says:

    Yaron,

    Sounds like you have had a good deal of interesting experiences in the 12 years since we last saw one another. Just out of curiousity, what do you think of UML? Where do UML diagrams go in the various documents you have discussed? (Use case scenarios etc…)

    Did I see you mention a daughter in an earlier post? Congratulations.

  2. Administrator says:

    I tend to use UML diagrams judiciously. I actually live by the text based use case format suggested in UML Distilled (I just got around to buying the latest edition and it’s waiting for me on my book shelf) but not the Use Case Diagram format. I haven’t found that format to be sufficiently informative to use very often.

    I use swim lanes a lot but usually by way of introduction rather than formal specification. Although I recently used them to debug a purported attack against a system I deployed and to show that the attack wasn’t real.

    I have used UML as a more formal modeling language in the past, especially when I was working on BPEL but even then I used it more to help me debug the system then to formally specify the system’s functionality.

    I’ve never used UML to actually write code but most of the code I write are prototypes or little tools for me since I’m a program manager not a real dev.

    So while I do like UML and I do use UML (Gentleware’s editor is my favorite, I found Visio’s UML implementation to be a bit uneven) I tend to use it more for illustration and exploration than formal specification.

  3. Robert Van de Water says:

    Yaron,

    I am relieved to hear you say that program managers use UML judiciously. In my experience, interpreting UML is rather like interpreting hieroglyphics. Look at the diagram, look at your pocket UML reference, look back at the diagram . . . Creating some of the diagrams isn’t that bad since they can be auto-generated from code and then tweaked for aesthetic reasons. Perhaps it is just the software that I have used. (Early versions of Rational Rose.)

    Honestly, though, I think the standard was a little too ambitious and sacrificed clarity and simplicity for power and flexibility.

Leave a Reply

Your email address will not be published. Required fields are marked *