Ryan Loos Senior Drupal Developer
August 30, 2023

One of the core pillars of the web consulting industry is the relationship between clients and vendors. The beginning of this relationship is defined by a legal contract, which is meticulously constructed to account for every detail. The end product is delivered in code, a medium which is also incredibly precise and specific.

It's ironic, then, that getting from contract to code is a fuzzy process that inevitably sees its fair share of mistakes, undos, miscommunications, redos, misinterpretations, undoings of the redos, et cetera. Many of these stumbles are caused by underlying assumptions that each team brings to the project. Here are seven assumptions to watch out for.

Assumption #1: They know what we know

When the client and vendor teams meet, both sides bring in a whole pile of assumptions about the project. Sometimes these assumptions are dead wrong. The client team, for example, may believe some technically infeasible things are easy, while the vendor team might misunderstand the intention of a client’s design choices and apply them incorrectly.

Regardless of which side you’re on, you are responsible for correcting the other side’s faulty assumptions. In the aforementioned case, the vendor team needs to explain technical limitations and the client needs to explain why a seemingly odd design choice is actually a business need.

Correcting others can be uncomfortable, but the project will ultimately be better for it.

Assumption #2: We know what the final product will look like

Before a project starts, both teams come together to write documentation that hammers out what the final product will look like. However, no magic combination of design docs, spreadsheets, and database models can perfectly encapsulate the results before they exist.

For example, two code libraries you intended to use might be incompatible. A feature might be redundant with other functionality and can be dropped. A seemingly simple task might take ages because of unknown complexity within the codebase or content requirements. In the end, you have to accept that no one knows 100% what the product will look like, and be adaptable

Assumption #3: We can ignore that nerdy word

Say you’re a news organization that has hired the vendor to build a new site. You want to have a field that links news articles to other related articles. The vendor suggests an "entity reference field"  for this purpose. You don’t know what this is, but it sounds right so you just nod and smile. A few weeks later, someone on your team complains to the vendor that the field isn't working when they link to an external piece of content, necessitating a costly rebuild.

A lot of pain could have been avoided if the client had asked the vendor to explain what an entity reference field is. If the other team uses a term you don’t understand in a meeting or email, they believe you know what they’re talking about. That might be a false assumption on their part, and, as we’ve already established, it’s your job to correct that assumption and ask for clarification. 

Simultaneously, the vendor then has to clearly explain the concept using layman's terms so that everyone can be on the same page and catch the mistake before it happens. Ultimately, both sides need to develop an understanding of each other's unique vocabulary, and be comfortable both asking and answering questions. This applies to vendors as well, who may not understand the business lingo specific to the client.

[Entity Reference Fields are used in Drupal to help pages reference other pieces of content on the site. They only reference that site's content, though. External content would need a different approach, like a link field.]

Assumption #4: Requirements shouldn't be questioned

There is a tendency for vendors to take all client requirements and requests at face value and just do the work. Most of the time this is totally fine, but an ever-present critical instinct can help transform a project from good to great. 

Vendors shouldn’t blindly do precisely what they’re told, and should consider other options when appropriate. Someone’s false assumptions could be preventing the team from finding the best solution. Likewise, clients shouldn’t blindly ask for something to stay the same because that's how it was done in the past.

Both sides need to regularly ask both themselves and the other side why a feature is there and if the same goal can be accomplished in a better way. A project underway is a lot easier to fix than a project that’s “completed”. Take the opportunity to do things the right way the first time around. This requires openness and flexible thinking on both sides.

Assumption #5: We don't need to write *that* down

Yes, you do. Website projects are complex, ever-changing, and take months to complete. The sooner and more extensively information is written down, the safer it is from the fallible human brains that need it.

First, make sure that at least one member of your team is taking meeting notes. These notes should capture what was agreed upon, what has changed, what was updated, et cetera. They then provide a paper trail of discussions that can be referenced if a decision needs to be revisited. For an extra layer of record, you can easily record meetings too.

Second, the product itself should be documented as it is created. This starts with an extensive planning document which lays out the intended approach, which should be updated as the designs change. The code itself should have ample readmes and comments. Both of these tools help new team members onboard more easily, and give context as to why and how certain decisions and features were made.

Assumption #6: Feedback can wait

Quality feedback has a shelf life. The later it’s delivered, the less useful it is. A developer who gets feedback on their feature within a day is going to be able to respond and fix the feature much faster because the work will be fresh in their brain. Conversely, if feedback takes weeks to arrive, the developer then has to re-read their code and re-contextualize everything, taking extra time. 

Prompt feedback is better for the team too because every feature checked off as complete is one less cognitive burden on everyone. When giving feedback, reply early and reply often. At the same time, take care to be precise with that feedback.

Assumption #7: They always know what I’m talking about

All of the aforementioned complexities truly start to converge when the client team starts evaluating whether the vendor’s work meets expectations (aka QA testing). This process can be a communication minefield, and the key to avoiding mines is to leave as little room for interpretation as possible.

To that end, never assume that the person you’re giving feedback to knows exactly what you’re talking about. Explain everything and make ample use of screenshots, videos, and GIFs to demonstrate the issue.

  • Bad: “Let me know when this is ready to test. Hopefully it will fix the other page as well.”  
  • Good: “Let me know when this is ready to test. Additionally, I have noticed there is an error on the other page that we have not yet discussed. Here is a screenshot demonstrating that the other page does not properly display status, compared to the live version, which does.”

A helpful rule of thumb is do not simply say that a feature is broken. Instead describe what it is currently doing and what it should be doing

  • Bad: The formatting on the homepage on mobile is wrong (This leaves a lot of room for interpretation. Which formatting? Is it a text issue or layout issue? What’s wrong with it?)
  • Good: On mobile, using Safari, the title at the top of the homepage screen continues off of the page. It should be wrapping so that it is visible for mobile viewers

The second comment might feel more laborious to write, but it’s important to think your comments through and add detail that cuts through the confusion.

Bonus assumption

If you’ve been in this industry any amount of time, you’ve probably seen these assumptions wreak havoc on a project. They cost money, time, patience, and sanity if ignored and are fairly straightforward to handle if recognized. 

Arguably the most dangerous assumption is the secret 0th one from which all the rest radiate. The belief that good communication will occur naturally on a project. The truth is that communication is a skill like any other that needs to be recognized, practiced, and maintained.

Once you have teams speaking clearly with one another, you might not need this list anymore as you develop your own shared language. But this process takes time, patience and a lot of collaborative work.