Sep 15 2017

As consultants at MojoTech, our job is not only to deliver great software products but to make the client-consultant experience enjoyable. In other words, we focus not only on results but the process itself. This balance is crucial to ensuring all our clients have the same great experience when working with us on a project.

Our clients come in many different shapes and sizes ranging from small startups with just an idea or vision to large, veteran companies that have been around for decades. As you can probably imagine, working with a brand new company that has never built a software product before is quite different from working with a company that has an existing development team and has been refining their workflow and product for years.

Just by virtue of experience, the former is likely to be more open to new ideas concerning the technology used or workflow techniques adopted. The latter is more likely to have existing software such as a database that needs to be integrated, streamlined, or expanded, rather than coded from scratch.

This isn’t to say that older companies aren’t ever open to new ideas, just that they may be more cognizant of the costs of changing something that already exists.

This reluctance can sometimes lead to friction or complications when making design, development, and project management decisions with more established clients. In order to deliver a successful product and maintain a high-quality team experience, we as consultants must be able to balance these responsibilities in such a way that minimizes conflicts while preserving the ability to make decisions quickly and confidently.

In this post, I’d like to discuss some considerations and strategies for maintaining this balance when working with clients with existing development teams or products.

The WHY question

One of the most important questions we ask ourselves and our clients during development is why. Why do we need this extra feature? Why do we want to use this framework over that one? Why are we using a hamburger menu over traditional navigation?

This question is essential for clarifying differences of opinion on everything — design, technology, and team management. Imagine you have been working on a project for 30 years — you’ve probably gone through countless iterations of your product and taken great care not to break anything in between. Now you’ve reached the limits of your team and have decided to hire a consultant to advise on a new major expansion. They don’t yet know your product, how hard you’ve worked to build it, and all the details of why you made the choices you did. My guess is you aren’t going to blindly accept breaking changes unless you are absolutely sure that they will work and be advantageous in the long run.

Finding a balance that respects both client concerns as well as your consultative advice requires effort on both teams to take the time to explain their own reasoning comprehensively, and simultaneously be willing to change their opinions given convincing arguments from the other side.

If either team adopts the “I don’t care what you say — my way is best and we’re doing it that way” argument, communication is halted and the decision inevitably takes longer, which not only costs time but also emotional energy. It’s easy to see how too many of these conflicts, even if they are about something as small as border width, can build up and have a serious impact on the overall project experience. Therefore, great care should be taken to mediate these conversations to ensure that everyone is on the same page.

The Importance of the Project Manager

On projects where it’s just us doing the development, the project manager (PM) is essential in that he or she is the bridge between our designers and developers. When other development teams are brought into the mix, the PM becomes more important than ever in minimizing conflict by facilitating clear communication between the two teams.

To accomplish this, our PMs are constantly looking for ways to add clarity to the project and team communication. While developers are writing code and designers are building wireframes, the PM is constructing and maintaining a high-level overview of the project by writing user stories and coordinating any questions that come up during development. Developers and designers know that they can rely on the PM to clarify or redirect those questions without having to ask around themselves for the right person on a large team to answer their questions. As a result, they can focus more on development than on debates with other team members.

Additionally, because all questions go through the PM, they have a more holistic view of not just the project requirements and scope, but the current status of the work itself. This is essential because the PM is responsible for keeping the team on track and the client up to date. The more info they have, the better able they are to keep everyone in sync and drive product delivery.

Lastly, when questions are inevitably asked more than once by different people, the project manager can quickly reiterate the answers. This process creates a virtuous cycle which keeps everyone better informed and more efficient.

Picking your battles

While we want to be diligent when explaining why we have the opinions we do when making arguments, some things do eventually just come down to personal preference, and too much discussion about them can become a problem in itself. Code formatting guidelines and linting rules are good examples of areas that may seem important on the small scale, but putting too much weight on those decisions can take away from the larger, more important ones. If one side feels very strongly about using spaces and you’re a tabs guy/girl, seriously just use spaces — it’s not that big a deal. Save the emotional energy for defining the data model or API contract.

Useful practices to improve communication

On the development side, there are many code-level strategies we have used throughout our development process to increase clarity in team communication. I’ve listed the some of the major ones below:

Document your code

Having multiple teams with different backgrounds working on the same codebase can be confusing, to say the least. Everyone has a slightly different way of writing functions, defining variables, organizing files, etc. Writing documentation is a low effort, high gain type of task. It is possible that someone on the team is just learning the project framework for the first time, and documentation can really help them get through the learning curve. It can also help future developers working on the project understand the codebase as a whole much quicker.

Use GitHub’s pull request templates

You can also add a pull request (PR) template to each PR on GitHub by including a pull_request_template.md file in the base repository. This practice encourages all developers to provide a complete explanation for the intentions and contents of a PR much in the same way regular code documentation does for individual functions.

Here are some things to include in a PR template to add clarity to the PR as a whole:

Description - A few sentences describing the overall goals of the PR's commits

Related PRs – from other branches

Links to relevant user stories - on Pivotal Tracker or other project management tool

UI Demo / Screencap – Animated gif or static screen capture of visual additions or changes

Release Notes - any additional release information

PR Checklist – tasks for developers to complete before making PR, such as including documentation

Encourage in-depth code reviews

Code reviews are an integral part of our development process and are an essential and effective strategy for improving code quality on projects with many developers on the same codebase. With larger projects and each developer working on small slices, it’s easy to just work on one’s own code and not worry about the rest. However, this can lead to problems in the future if your code needs to interact with someone else’s code, and you have never seen their code before.

At MojoTech, we preempt this problem by spending a chunk of time each day reviewing other developers’ open PRs. This not only helps each dev maintain a higher level understanding of the project as a whole but also improves each PR dramatically before merging as many more eyes are reviewing it for errors or potential improvements.

Moreover, by reviewing other devs’ code, each dev is likely to learn about new approaches that they may not have been exposed to before.

Lastly, this practice encourages discussion about code patterns early on so that each member of the team fully understands the code when it is still being developed, ideally decreasing the number of questions that need to be asked in the future.

Conclusion

Working with clients with existing development teams can add complexity to our responsibilities as consultants. But, by staying aware of potential conflicts and adopting practices to increase clear communication, we can bring balance to the team, not leave it in darkness!