/ Project Handbook

Project Briefs

We use the term “Project Brief” intentionally, as opposed to something like “Project Specification” or “Statement of Work” because in general these documents tend to be less specific and detailed than a typical agency’s technical specifications or SOWs would need to be. We try to balance the need to have a clear, shared understanding about the work we’re doing for our partners, with the reality that scope of our work is necessarily flexible and evolving to meet partner expectations.

We create Project Briefs for each non-trivial project we take on. Basically, if it’s going to require technical work from one of our contractors (design, development, etc.) then it should have a Brief in place before work begins. Also as a general rule, a new project brief warrants a new project P2 to track the work related to that brief (reminder that each project P2 should also have its own discrete project entry in Linear).

It may feel like these briefs take a long time to create. It may also feel like the information is already available in other places, and so re-stating it in a new place seems redundant. But we’ve found that not having a clear, consolidated document that we can reference throughout the project can result in projects that don’t meet expectations, take longer than they need to, or that never successfully launch.

Projects with Multiple Phases

It is fairly common for our team to launch sites in phases, with an initial site launch being followed by additional feature build-outs (in one additional phase or perhaps multiple phases).

Each project phase should have its own project brief which clearly defines the goals of that phase. As a general rule: each phase should have its own project P2 and each project P2 should have its own project brief.

Projects Brief For Internal Projects

One of the outcomes of ███████████████, was that we shouldn’t do Project Briefs for internal projects. That said, we should still include timeline considerations, key functionality, content structure, and other important details in a well-formatted P2 comment on the project’s P2 for easy discovery and digestion for internal stakeholders.

Audience

The project brief should be written in a way that is friendly to partners, team members and contractors alike. (Because of the latter, make sure you don’t include any sensitive information in the brief that goes beyond what a contractor needs to know to work on the project.) We should avoid technical jargon, acronyms and links to resources that aren’t visible to everyone with access to the project brief.

Project Brief Structures

Typically we compose project briefs as Google Docs. ███████████████.

The project brief should cover, in some form, these details about a project:

  1. Goals. What is the partner trying to achieve here? What’s at stake for them, and what does success look like? How does it relate to their larger efforts? Usually a 1-3 sentence summary.
  2. Basic Approach and Timeline
    • Approach. A high-level overview of the work that our team will be taking on as a part of this project to meet the goals stated above. Usually 1-3 sentences.
    • Timeline. A bullet-point list of all the key stages in the project, including all deliveries.
      • The general key stages of projects include (but are not limited to):
      • We should provide specific ranges for the known stages of the project and, alternatively, wider ranges for future stages that we refine and communicate to the partner as the project progresses.
      • Consider adding sub-bullets for relevant details for each stage (e.g., Information Architecture, Design Concepts, Migration, etc.). Remember that every project is unique, so the suggestions in the template are guidelines only.
    • Contacts and Stakeholders. A list of names and roles for everyone who will be involved in the project at any level, both on the partner side and on our side. On our side, we will typically only include the TAM(s) assigned to the project (not designers or developers whether internal or contractor).
  3. What We’re Doing Together
    • Design and Other Assets. This section should describe where any assets will come from and when they’ll be ready. This may include design assets, references or any other content the partner can supply is with. Even if we’re just re-using existing assets, we should spell that out. If custom assets will need to be created along the way, we should indicate who will be doing that and their general availability.
    • Key Functionality. For each functional requirement that goes beyond what WordPress Core + Jetpack offers, a bullet point list of how the functionality should work. If a simple user story format doesn’t suffice (e.g. “As an anonymous user, I should be able to search for records by creation date.”) then additional detail and supporting documents may be needed.
    • Content Structure. As part of the content stage, we’ll gather and refine the written content, media assets, and structure. But it’s helpful to include an overview of the featured archives, static pages, navigation items, and content types we’ve gathered so far as part of our discovery.
    • Key External Links and Integrations. A list of all the key links to third parties that will need to be included (including social media accounts) and integrations with external services that will be included (e.g. a Google Map embed).
    • WordPress.com Account Creation. These are instructions for the partners to create a WordPress.com account if they don’t already have one. This is very helpful to get the partner doing up front, eliminating blockers when we’re ready to add them to their new site.
  4. Important Decisions and Information
    • ███████████████
      • ███████████████
    • Domain. Note who has access to any domains that will be mapped to the site, and where the registration and DNS management for those domains live. Suggest a better DNS provider if they aren’t using a high performing one. ███████████████
    • Hosting and Jetpack. Note clearly where the new/updated site will be hosted, and who will manage that hosting. Also ensure that the partner is aware of our use of Jetpack and that the site will be included in the Creator Network that powers the Reader.
    • Your site’s content. If the partner, for any reason, would like the site not to be available for search engines or other third-parties, we can discourage search engines, common third-party crawlers, or both from indexing. Make sure to capture these details. ███████████████
    • WooCommerce & Sensei. If using WooCommerce and/or Sensei on the site, we should include our standard language notifying the partner of being opted in to usage tracking (Woo and Sensei).
    • Showcasing Our Work Together in Public. We’re asking for permission to showcase the new site in the most common scenarios. This is a new section, so if you encounter any questions from the partners on this, please share that feedback.
    • Open Source. Given our transition to the Blocks Monorepo and the open source nature of our development, we’re being more explicit about open sourcing the code and solutions we provide.
  5. Other Notes and Questions. For any other details not covered in the previous sections, list them out here. Also include any pending questions that we need to get answered (from the partner, from their related service providers, from our colleagues, hosting platform, etc).

Once finalized, copy the entire brief into a new Google Doc to clean out the comment and edit history.

Getting Partner Agreement

Once we’re sure a project brief represents our best internal understanding of a project, it’s time to show it to the partner and see if they agree. Here’s an example delivery you can use for emailing them a PDF version of the brief (also shared as a message template in Zendesk):

zendesk Macro

51::Message Templates::Project Brief Delivery

Hi ….

As discussed, we’ve put together a project brief that we believe pulls together the information we discussed on our call along with the other information you’ve sent along. We’re including it as a Google Doc link here:

and as a PDF attachment.

Can you read through this carefully and make sure it seems right to you? Since we’ll use this document to plan our work and resource the people working on the project, we want to make sure it’s accurate and comprehensive. There are a few questions for you at the end. Beyond that, if you notice anything that sounds off or that’s missing, or if you just want to talk through the details of a given point, let us know. (If you’re comfortable using the Google Doc interface to comment, that’s great, but email is fine too.) Once you confirm that this brief is a good reflection of the work we’re going to do together, we can plan to refer back to it throughout the project to make sure we’re on track.

When the brief is finalized, our next step is to … , and start planning out the rest of our work on the project.

I hope that’s helpful. If you have any questions or if you need anything else, just let us know!

It’s essential that we have the partner’s engagement here. If the partner doesn’t seem to review the brief in detail, or if they never confirm their agreement, we should take a step back before starting work on the project.

Reviewing Larger Briefs

For most projects, we send the brief to the partner through email and gather their feedback/approval of the brief that way. However, for larger projects with more complicated briefs the TAM should consider whether it would be beneficial to review the brief with the partner on a call. This could provide a few potential benefits:

  • Real-time clarification of any questions the partner may have.
  • Confirm/clarify any assumptions the partner is making based on the language shared in the brief to get ahead of any misunderstandings.
  • Confirm/clarify the use of any paid subscriptions or plans we suggest.
  • Re-emphasize our team’s approach to site building, by scoping and assigning designers/developers for defined feature build-outs (our team generally does not work in an “agile” method).

Keeping these items current means that the brief can still serve the purpose of being the document we “verify” our work against over time.

Ensure these updates to the brief are communicated to the partner, with the specific updates made clearly visible for the partner’s review.

Example Project Briefs

Possible inspiration:

  • ███████████████
  • ███████████████
  • ███████████████
  • ███████████████
  • ███████████████

🔍 Search the handbook

All pages