Effective team communication is key to success
Long gone are the days of sharing a single codebase. As architectures embrace looser coupling and higher cohesion, our APIs and service boundaries will also become boundaries of expertise. Further, most interactions between internal services require interaction between teams in the organization. Crossing team boundaries incurs an overhead on day-to-day workflow, but if we hash out some best practices for creating more effective team communication, we can make the process a bit less painful.
In this post, I'll lay down some hot takes on effective team communication about our code in the hope that we can start these conversations with some common ground and shared expectations. But this post aims to be, at best, the start of its own conversation—if you have anything to add or differences of opinion to voice, feel free to share.
Being a better expert
Part of owning your code is helping other devs interact with it. This isn't always easy, but there are some ways we can be proactive to help ease the process for both parties.
Ideally, integrating components or services across teams would be as simple as reading the impeccable documentation and executing the prescribed steps—no questions asked. So let's start with a brief detour, touching on some things we should strive for when writing documentation.
1. Make it discoverable
Your documentation should be discoverable, otherwise you can't expect anybody to find it and read it. We've been creating descriptively named GitHub repositories just for documentation, which we then link to each other in a sensible structure. Your source code should explicitly call out the location of your docs, especially if they don't live together.
2. Keep it updated
It's easy to forget—or intentionally skip—this part, but your docs need to be up to date. Few things are more frustrating than trying to debug step-by-step instructions, asking for help, and being told, "Those are out of date. You're supposed to do something completely different."
3. Walk in your consumer's shoes
Take the time to work through a client for your service, another app that integrates with yours, or whatever integrations you may support. Getting into your consumers' shoes will help you anticipate issues and understand the frustrations of the people trying to work with your code. And when you're done, publish it alongside your docs.
Also related, the Rule of Three. In short, taking the time to consume your service—no fewer than three times—will help shake out design issues and incorrect assumptions.
4. Create a first-class deliverable
Documentation is a deliverable, just like code and tests. Your team can form its own agreements on this, but documentation should not be seen as optional or nice to have.
5. Claim ownership
Somewhere in your documentation, hopefully in the README, identify the team(s) that own this component. It's also nice to point out how to get in contact with you.
Opening lines of effective team communication
Now that you've got perfect documentation, it's time to get ready for people to find it woefully inadequate and come to you with questions. An open, well-named chat room can be an easy way for people to find your team and ask questions. It's not enough to just set up shop, though. Failure to respond can be just as much of a wall as a private room.
Being a better asker
Again, there are other write-ups on asking good questions for technical audiences. But we're all coworkers, not a massive mailing list. These interactions take on a different flavor between colleagues. Keeping in mind that we're all on the same team, what can we do to get through the help cycle and keep everybody happy?
Read the documentation
If your expert coworkers are spending time maintaining documentation, it’s your responsibility to read it. If you can't find anything relevant to your issue, your first question could be, "Is there documentation about this topic somewhere?" Asking another team for help is not your only option. Start by reading the docs, searching on StackOverflow, reading the docs, searching on Google, reading the docs, browsing the code, etc.
Before you ask a question, do you really understand the problem? Have you done the research and exhausted the available resources? Sometimes the issue is in our understanding, not in the code. That doesn't mean you're not allowed to ask questions. But when you do, be aware that your question is the start of a technical conversation. You'll need to be prepared to provide clarifying details about your problem. You are the expert on your problem space, so you'll be relied on to educate others about it.
Your code isn't working. You don't know what's wrong. You haven't been able to figure it out. That's fine. We still love you.
Don't be scared to ask for help. As the consumer of a library or service, you are one of the customers. We want to delight all of our customers, and we'd hate to hear through the grapevine that our code is your personal El Guapo.
While you should be sure to have a firm grasp on your own code, it's usually not necessary for you to grok all of the implementation details of the service or library you're trying to integrate with. This is important when you suspect you've found a bug. You're probably able to change the line of code that is broken for you. But you should respect that you’re not the owner of the project, and your fix may not be in line with the owners' goals for their project. Report the bug, offer to help with a fix, but don't assume you have it all figured out.
Stay on target
Offer relevant details, not your debugging and diagnostic guesses. Tell your audience what you expect to happen and what's actually happening. Anything beyond that can muddy the waters.
Ask a question
There are other articles and documents out there on this topic. They're generally geared toward how to get help from the hacker community. We're all coworkers with shared goals, so there are some mental adjustments to be made. But it never hurts to read more opinions:
Here are some examples of ways to start a conversation that are not questions:
- "I'm trying to do this thing, but it's not working."
- "I think there's a bug in your API."
- Copy/pasting a stacktrace with little to no context
And here are examples of questions that barely count as questions:
- "Does anybody know how this service works?"
- "Is this supposed to behave like this?"
- "Can anybody help me with this thing I'm working on?"
- "I've been working on this, and something happened. Any thoughts?"
In order to have effective team communication, make sure your question is a good question. Describe your problem and ask about what has you confused:
- "In my team's python service, we want access to the current user's role_list to restrict access to our APIs a bit. I'm trying to get that info from your session_data endpoint, but the response I'm getting has an empty user object. Do you know why that might be happening? See this gist for the request/response details..."
- "When I run gulp dist, I think it should create a self-executable JS file in my project's /dist/ directory. Frustratingly, the process finishes without errors and produces no output. I don't see any similar issues on GitHub. Is somebody free to take a closer look and let me know if I'm doing something wrong?"
Finally, be polite. When asking about an issue, keep in mind that the people you're talking to are probably proud of what they wrote. When answering a question, remember that the asker has put him or herself in a vulnerable position. In short, be kind to each other.
About the Author
Chad Knight, Software Architect, designs and builds backend services for the Workiva platform. He has been with Workiva since he graduated from Iowa State University. Chad lives in Chicago, where he also brews beer and makes pizza.