Project Managers' Other Work: Introducing Definition and Documentation

Josh Korr, Former Product Strategy Director

Article Category: #Process

Posted on

Do these scenarios sound familiar?

  • You're regrouping with the team after a kickoff meeting, or a few weeks into a project just before development is set to begin. The discussion goes around in circles, and finally a developer says, "I just don't know what we're supposed to be building."
  • A developer is ready to start implementing a ticket but has to stop and ask you, "Wait, how is this supposed to work?"
  • The team is discussing a view in the site you're building. The UX designer keeps talking about a landing page, but the developer is talking about a product index. You can't tell if they're referring to the same thing. Meantime, the wireframe file for that view is titled "product-landing-page" and you can't find a correspondingly named design comp (turns out the PSD is named "products").

If so, you've encountered common deficiencies in two of the key areas of project managers' connective-tissue work: definition and documentation.

What Is Definition?

As the above scenarios illustrate, a bunch of feature ideas and designs don't necessarily result in clarity about a project. That's where definition comes in: It's the process of turning ideas and designs into (1) a high-level understanding of a project, and (2) details of what will be implemented.


  • Enables informed and realistic project planning, by answering the "What are we building?" question.
  • Enables efficient and optimal implementation and testing, by answering the "How is this supposed to work?" question.
  • Fosters a shared understanding of the project, by getting everyone to speak and think about the project in the same terms.

Why Is Definition Important?

Let's look at how definition helps in each of these areas.


Unless you're a PM in a very agile context, you likely have to do various kinds of project planning beyond the current or next short development period.

You may need to estimate the project's cost and length upfront. If you bill hourly and/or if team members work on multiple projects simultaneously, you need to estimate future resourcing needs.

You probably need team members to wrap their heads around the holistic project so they can take ownership of and create a plan for tackling their work. You may need to convey to clients or stakeholders what you plan to implement and what may not be possible within the time and budget. You also need to track and gauge progress throughout the project, always having a good sense of what's left relative to the time and budget remaining.

By defining a project's high-level contours — such as the app's sites, universe, and feature or work buckets — we can make all of this planning realistic and useful.


While digital project managers work on myriad types of projects, I'm focusing on software projects — which these days most commonly means web applications or native mobile applications.

There are certain things that need to be defined to implement software. To name a few:

  • The app's objects
  • The app's views
  • The data displayed on a given view, and the data's rules
  • Interaction behaviors
  • Where a user is taken when they submit a form
  • Email delivery configurations

If a developer is ready to implement something and the details haven't been defined, there are two options: get the people who are ostensibly focused on product, business, and user goals to belatedly help define the thing, or make the definition decisions unilaterally. The former is a risk to timing (devs will accomplish less than expected if they have to wait for definition) and budget (implications aren't known until definition is done), plus it's annoying if people who should be driving definition aren't doing it. The latter is a risk to the budget and larger goals, as the devs may make definition decisions that don't match business, user, client, or stakeholder needs or expectations. (This isn't a problem if your devs are expected to make these decisions.)

By facilitating or doing definition of implementation details at the right times, PMs avoid the above issues and help ensure that we are implementing things efficiently and correctly (or appropriately iteratively).

Shared Understanding

Projects are most successful when the team is on the same page about the project's high-level contours and implementation details. But it's common for team members to have their own mental models — and mental gaps — of the work to be done, which can lead to misunderstandings and strained collaboration.

By defining a conceptual framework and shared nomenclature for the project, we can make sure everyone's on the same page throughout the project, rather than stuck on their own mental model.

Project managers are often best suited to define this shared understanding. We're ideally the least siloed person on a project, as we have to work with and understand the motivations and thought processes of all team members, clients, and stakeholders.

So we can abstract out a conceptual framework and language that we know will make sense to everyone, and then shape process components around this shared understanding. For example, processes that make it easier to find wireframes and comps for the same view when UX and visual designers might otherwise have their own ways of naming their respective artifacts.

What Is Documentation, and Why Is It Important?

Documentation is simply the communication of definition. As I wrote in my previous post:

Documentation captures nuances, abstracted details, and decisions that implementers can't store in their heads or that are hard to convey verbally. And it makes those details available to teammates, clients, stakeholders, testers, and users.

Documentation is important because without it, definition can too easily get lost. If something is adequately defined but that definition is not adequately documented, it may not get implemented correctly. Or it may not get tested correctly. Or stakeholders and clients might not know how to use it. Or users might not know how to use it.

While some types and formats of web design documentation are well-established — for example, user stories, user flows, and site maps — in many cases those have a different purpose than definition for the connective-tissue areas of planning, implementation, and testing. The documentation I'm talking about is specifically geared toward these connective-tissue contexts.

Related Articles