Why writing matters + a technical design template
As a manager, the number one skill I coach in my engineers is how and when to use writing as part of their problem-solving and collaborative process. Writing is one of the engineering toolbox's most underutilized tools of the craft. Engineers write every day but often, they focus on just two use cases: documentation and note-taking. Many engineers are not taught to write to problem solve and collaborate. They go straight to the code editor or the command line.
Writing is Thinking. Time spent thinking saves you time when coding.
Engineers use writing in four key ways:
- Documentation: Writing is essential for creating clear and comprehensive documentation for software projects. This documentation can help other developers understand how the code works, what the design patterns and architecture are, and how to maintain and extend the software.
- Note-taking: Writing is an effective way to keep a record of the thought process, design decisions, and testing results, making it easier to revisit and improve upon previous work. Think about what 'Future You' will find confusing in 6 months.
- Problem-Solving: Writing allows software engineers to work through complex problems and deconstruct them into smaller, more manageable parts. By writing down the steps involved in solving a problem, engineers can better identify gaps in their logic and develop a clear plan for how to solve it.
- Collaboration: Writing is also an important tool for collaborating with other developers, stakeholders, and clients. By clearly communicating requirements, success metrics, design decisions, and implementation plans in writing, software engineers can ensure that everyone is aligned and that there is a shared understanding of the project.
When to Write
I encourage engineers to write in the following situations
- You have encountered a problem with multiple possible implementations.
- There is ambiguity. You do not have all the answers, you might not even know all the questions to ask.
- You started to write code because you thought it was going to be quick and simple but the task is now taking far longer than expected.
- You are struggling to communicate your thoughts. Your conversations with your teammates are not driving alignment.
- This is a decision that "Future You" will need help remembering.
Who Should Write
Everyone. The words "Technical Design" sometimes discourage engineers from writing. They see this as a process of more senior members of the team. This is a common misconception that is sometimes encouraged by the engineering culture. I refer to write-ups for relatively "Simple" problems as "mini tech designs" because many of the same design principles apply. A solution for a single frontend component is just as worthy of writing up and peer review as a months-long component library project if it enables the engineer to solve that problem more effectively and more efficiently.
How to Write
Use Technical Designs. A good technical design demonstrates clear thinking and can communicate that thinking to others. In order to produce an effective technical design, the engineer must:
- Understand the requirements: Product, Business, and Technical.
- Set clear, prioritized success criteria for those requirements
- Develop proposed solutions for the problem
- Recommend the best solution by evaluating tradeoffs, using success criteria as guidelines.
Who are you writing for
The audience dictates the purpose of the document. Before you start writing, identify your audience. Who is going to read this?
- Team Members: High context but might be missing a few key project details
- Partner Teams: Some context, often they have deep subject matter expertise in a relevant area
- Engineering Managers/Technical Leads: High context but might be missing a few key details
- Product Partners: High context on the product. Less context on technical implementation
- UX Partners: High context on the product. Less context on technical implementation
- "Future You": Less context than you might expect.
Tech Design Template
The following is a tech design template. This problem-solving template can be scaled up or down to problems of many different sizes, from a single bug fix or feature build to a multi months-long project. Please use it at will.
Key parts of technical design:
- Definitions
- Background: Problem and Success Metrics
- Key Decisions
Definitions
Include a glossary of terms with definitions for:
- Key concepts
- New Concepts
- Descriptions of services
- Acronyms
Background
Problem Statement
Use this section to ensure that your audience is aligned with the problem statement.
Describe the problem. Be sure to answer Who, What, and Why:
- What are we solving?
- Who are we solving it for?
- Why are we solving it?
Success Metrics
Use this section to state and align your success metrics. Success metrics are how you will make decisions and prevent confirmation bias. Confirmation bias is when you go into a doc knowing what you want the solution to be, then you write the doc such that it makes that solution sound the best.
A good way to develop success metrics is by writing up the requirements and expected outcomes. Requirements that can be quantified should be quantified. Here is a list of requirements you should consider in your technical design (for a start):
Product requirements
- Features
- UX
Technical requirements
- Performance
- Scale
- Technology Used
- Tech Debt
Business requirements
- Deadlines — how much time can we spend on this project?
- Cost
Here are examples of requirements, written as effective success metrics:
Requirement: Add new Call to Action (CTA) on the homepage for a Flash Sale
Success Metric: The CTA converts at least 20% of all page views into click throughs to the Flash Sale
Requirement: The Flash Sale Page handles all the traffic
Success Metric: The Flash Sale page can scale to 20,000 page visits per second
Requirement: The Flash Sale Page is fast
Success Metric: TimeToInteractive on the Flash Sale Page is below 2.2 seconds in all regions.
Key Decisions
A task of small scope and low ambiguity probably breaks down into just 1 or possibly 2 key decisions. A project of large scope and high ambiguity likely contains multiple problems, each of which requires a decision. Each decision is effectively a solution to the problem.
For Each Key Decision
- Provide multiple solutions
- State the recommended solution at the top. Mark it as recommended.
- Use a Pros and Cons format to express how you evaluated the solutions and came to your recommendations
- Use code snippets, diagrams, or other visuals as needed
Pros and Cons aka Trade-Offs
Pros and cons are trade-offs. Making trade-offs is key to any decision-making. Here are common trade-offs to consider. What makes an appropriate trade-off depends on the success metrics you defined above. Your recommended solution will be a balance of some or all of these.
- Does this solution solve the problem?
- What are the use cases?
- What are the edge cases?
- What are the consequences to the business if we do not cover those cases?
- What is the complexity of the solution? Some indicators of complexity:
- How many teams need to be involved in the solution?
- How many different services are involved in the solution?
- How much is known about this problem? How much needs investigation?
- Speed to build and design
- Building for the long term: is this future-proof? do we incur tech debt?
- Cost
- Performance
- User Experience of Users who consume the product
- User Experience of those who consume the code. The end users of a non-consumer-facing API are your fellow engineers.
0 commentaire