Writing a good Project Brief for your Developer

An important part or my role is communicating with both end-users and developers. Naturally, there is usually a communication breakdown when the two communicate directly. The end-user doesn’t really know what they’re asking for and the developer doesn’t understand the full requirements of the project.

I listen and learn about the end-users issue and understand how the issue and the solution would all fit together.

In fact, I find myself asking end-users about subjects they never thought to mention because they took a piece of information for granted… And other times I find myself removing completely irrelevant information that may only confuse the developer.

Then I take that information and break it down into a bitesize brief (or milestones) for the developer. Typically, it can take several days to research the problem and break it down. Over the years, I’d like to think that I’ve become quite good at this. As a result, I’ve found that my experience with developers have become that much smoother and quicker.

So, I figured I’d share with you an example brief that I created to help you structure work for your developers.

Example Brief (Good)

About example.com

We are a small eCommerce business that primarily focus on selling Dog Collars. We ship nationally within the UK and have a single brick-and-mortar store (which also serves as our warehouse). For our eCommerce site we’re running on Magento 2.3.2 with a just a couple of 3rd party extensions.

Note: When I’ve never worked with a developer before, I like to give a background of the business that I represent in order to give them some context. I might expand on this if the Project requires it.

The Problem

We already ship nationally using Royal Mail. However, we’ve been trialling a new local delivery service using our own vans. We use 4 vans that delivery to 4 zones within our city. Each zone is determined by a list of postcodes that we use.


The problem is, whenever we receive a customer order, it takes the warehouse administrator a long time to work out which order needs to go in which van because they have to cross reference the postcode for each order. And sometimes the order ends up in the wrong van.

The current workflow looks like this:

  1. Customer places order
  2. Warehouse administrator prints off the Invoice
  3. Warehouse administrator cross references the delivery postcodes against a spreadsheet
  4. Parcel given to driver

Note: This is where I like to explain the problem in as much detail as I believe is necessary. I often find it helps to include a scenario to help explain.

The Solution

To help the warehouse administrator go through the orders quicker and to help avoid mistakes, we’d like to highlight the orders.

So, on the Orders screen we were thinking about adding an additional column that automatically assigns a zone based on the list of postcodes we currently use. This would also allow the orders to be filtered by Delivery Zone.

And I was also thinking about adding a line to the Invoices that we give the drivers so they can double-check they have the correct parcels before they leave.

The new workflow would look like this:

  1. Customer places order
  2. Magento checks if the delivery postcode belongs to a certain zone
  3. The appropriate zone is assigned to the order and is display in the “Zone” column
  4. Warehouse administrator prepares the orders and gives to the driver
  5. Driver does a final check before leaving by checking the Invoice label

Note: Here I like to propose a “loose” solution. A guide to help the developer form a work-flow. It’s also helpful to include an example scenario here too.


Orders grid could look something like this


This would be ideal for the Invoice PDF

Note: Finally, to help the developer visualise the solution I like to spend time working up some concept images of the final solution.

Example Brief (Bad)

I have website which I am not happy with the sliders as they are not WYSIWYG or for non coding knowledge. Its been suggested to either use a different theme or add a page builder.
Its magento 2.

I just found this on UpWork. This is all there was.

1 Like