How to Build for the Handoff
On writing software for future engineers
Part of my job here at Postlight is speaking to people who are considering hiring us to help their company build a product. These talks are pretty fascinating. I don’t think of them as “sales” as much as I think of them as counseling. My job is to listen carefully to someone describe their hopes and dreams and anxieties, manifested as some idea they have of what software could be and do for them, their users, and their business. Then I get to tell them if I think the idea makes sense, is feasible, and if and how Postlight can help.
By the time someone makes it to this discussion with us, we know a few things are true: there’s an app or platform or web site they want to build or improve. Even if their company already has an in-house engineering team, they need outside help to get that work done. Often, some source of stress or frustration is involved. Oh, and there’s a good deal of money at stake. That’s a vulnerable position to be in, and there’s one particular worried question that comes up toward the end of almost all of these conversations: “What happens when the work is done and my developers are going to take over? How do you do that handoff? How do we know we won’t have to pay Postlight to maintain it forever?”
Work Yourself Out of a Job
When you work in client services building software for others, your objective is the same as any good teacher, doctor, or therapist: to work yourself out of a job. There’s probably a lucrative business in building software that’s so proprietary and difficult-to-maintain, your clients become dependent on you and have no choice but to contract you forever in order to keep things up and running. That’s not the business Postlight is in. Postlight’s job is to empower our clients to take what we built and move forward, with or without us. In most cases, it’s without us, and when they do, it means we succeeded. (Especially because empowered, happy clients refer new business our way.)
This is the big difference between the goals of an in-house engineering team and the one you are hiring from Postlight. In order to set up our clients to move forward and succeed without us, throughout every engagement, the project team at Postlight has to build toward meeting the product’s and client’s goals as well as build toward the handoff.
When Future Engineers Are Your Other Users
When you’re defining and designing a product, you do so in service of the product’s users. Similarly, when you’re writing code you’re going to hand off someday, you do so in service of the code’s users: some number of future, unknown engineers, who are going to have to understand what you built, how you built it, and expand, maintain, and troubleshoot it.
Here are some ways Postlight builds software with future engineers in mind.
- Make low-risk technology decisions. When Postlight kicks off an engagement, we find out everything we can about our client’s existing or future engineering team — their skillsets and talents, technology preferences, and existing environments. If there is no engineering team yet, we ask what sort of engineers the client plans to hire, what their local market is like for various technologies, and if the existing stakeholders have preferences for certain tools or languages. If Postlight Engineering is making all the initial tech decisions on a totally greenfield product, we choose modern but mainstream languages, frameworks, and best practices, the ones that will be most likely understood by the widest range of developers. We only use riskier, cutting-edge, or unusual technology to get a one-time task done if it will make us more productive (like an extensive, one-time data import).
- Reduce maintenance burden. When Postlight makes decisions about how a product is architected — that is, how many and which services and servers will be involved — we think about what sort of maintenance and updates they’ll require and how the client will do that maintenance in the future. Then we optimize to reduce that burden as much as possible. For example, when we built Bloomberg Lens, we went out of our way to do it without spinning up a server, i.e., “nothing that can overflow with log files, get hacked, or become sluggish.” When we rebuilt The Village Voice, we deployed the new site to a managed hosting provider, to obviate the need for our client to hire any in-house web operations staff once the engagement with us was complete.
- Write and review code for maintainability, readability and extensibility (versus terseness or cleverness). Code that engineers can’t understand is code that engineers can’t build on, and it’s code engineers will want to throw out and rewrite. When we’re writing code to hand off, we stay wary of anything that is so clever it is opaque, where function and variable names aren’t readable, expressive, and clear, where the code structure makes it difficult to find what you need. Documentation should accompany most changes, and standard code style should be enforced throughout. (This is why creating a culture of code review is so important: you keep each other accountable to these standards.) When Postlight engineers join an existing engineering team who has already established their own style, patterns, and processes, we adapt our work so it integrates with the rest of the system seamlessly, while introducing best practices where we can.
- Create a smooth on-ramp. One of the key quality measurements of any code repository is: how quickly and easily can a new developer clone this repository and get this code up and running on their computer? When engineers are your users, your code’s on-boarding process is the README. The fewer setup steps there are, the better. When we can, we containerize our app’s environment to make it portable and easily reproducible, to reduce the number of steps it takes to get it running locally or elsewhere.
- Build Phase 1 to expand easily to Phases 2 and 3. In many cases, clients engage us to build phase 1 of their product idea, or a Minimum Viable Product, that has a long potential feature roadmap ahead of it — but it’s not clear who will build those future iterations. When you’re building for the handoff, you’re building for future engineers and future product features. When we begin, we get as much information about future plans for the product even beyond our engagement, and make decisions that will properly lay the groundwork for phases 2 and 3 to come to fruition with as little refactoring as possible. Documenting potential implementation of future features, given the MVP, gives our clients a path forward beyond the handoff date.
Building for the handoff is good practice on any engineering team, but it’s absolutely essential in a successful client engagement — at least the way we define it. Would you like to work with Postlight so you never have to again? Get in touch.
