Back when I was a junior software developer, I always dreaded whenever a manager would ask me, “How long will it take for you to finish coding that project?” I couldn’t predict the future, but I felt tempted to give an unrealistically optimistic estimate to make people happy, or a super-pessimistic timeline to protect myself from being blamed for slippage. Eventually, the manager would coax a time estimate out of me, after which I’d sit down and begin feverishly coding. In the end, not only did the actual duration differ wildly from my estimates, but I often had to rework the project because I either misunderstood the original requirements, or forgot to make changes to a related software component.

Over time, I’ve learned to manage this situation better. One thing that’s helped a lot is learning how to craft useful engineering design documents. Not only have they helped our team achieve timely software deployments, but they’ve also helped promote team collaboration. Below are a few guidelines I’ve found helpful along the way.

Engineering design docs are intended for team collaboration.

They’re not supposed to be perfect or represent the final word – they’re invitations to think about something together. Oftentimes the design docs we write include proposals and open questions, but the entire document is open to the team for comment, feedback, or questions. I love seeing design docs that are marked up with lots of comments from multiple team members. It helps to have a team culture where team members aren’t afraid to be vulnerable about suggesting risky ideas, and where everyone is encouraged to be open-minded and welcoming to critical feedback.

The first part of an engineering design doc should include a clear problem statement.

The problem statement should answer two questions:

1. Why are we doing this? What are the objectives and motivations for the project?
2. When do we know we’re done? What are the requirements, scope, and success metrics for the project?

It’s funny how much the simple exercise of writing out a problem statement has helped me. On one occasion, I had been mulling over implementation details for a project, but as I wrote down the problem statement, I realized that the desired objectives could be achieved using something that another team had already built. We ended up saving a lot of time because there was no need to write additional code in the first place.

Another time, I wrote a very complicated problem statement. When I reviewed it, I realized that I was trying to achieve two goals that would be better served as two smaller projects. This helped our team achieve a breakthrough since the scope of those two projects was much more manageable and easier to complete.

The rest of the engineering design doc should outline the tasks to complete the scope of the project.

I often find it helpful to group the tasks into three phases:

• the MVP (minimum viable product) phase, consisting of the bare minimum necessary to get the project into a functional state that can be demoed and tested;
• the short-term phase, consisting of tasks that allow the product to achieve an acceptable level of robustness, stability, performance, and autonomy; and
• the long-term phase, consisting of tasks that ensure the long-term sustainability and scalability of the project.

For each task, I provide details and diagrams, with more attention to tasks in the earlier phases.

The design doc should include work estimate ranges to each task.

It is much easier to estimate the work effort of individual tasks as opposed to an entire project as a whole. I provide worst and best case estimates. Generally, I spend more time on MVP estimates, and use a larger range of work estimates for tasks in later phases. This gives my team more certainty around what’s required to achieve the MVP phase, while also giving us flexibility to make adjustments down the road for later phases of the project.

Over the years, I’ve written countless design docs using these rough guidelines, and it’s now much easier to field that inevitable question from a manager or team lead about how long a coding project will take. Even if the answer isn’t always simple, I can provide the information my team needs to prioritize and plan, and it also helps my teammates understand and weigh in on how we build things.