Creating a technical plan is a sign of professionalism and maturity as a software developer. No matter what you’re working on, whether it be a straightforward feature extension or a massive data migration, a technical plan must be written.
Why Should I Write A Technical Plan?
- A written plan forces you to think deeply about your work.
- A written plan facilitates communication. Review it, talk about it, reference it.
- A written plan serves as documentation. What did we set out to do and how did we do it?
- A written plan organizes your execution.
- A written plan invites collaboration, which begets technical thoroughness and stakeholder alignment.
- A written plan signals professionalism.
As you write your technical plan, here are some ways to ensure the process is as effective as possible.
Use (Or Create) A Template
If available, use a pre-existing template. A template provides structure and forces you to consider a standard set of criteria. All software companies have their own flavor of technical planning documents—Requirements Summaries, Architecture Explorations, or RFCs.
If there isn’t a template, take it upon yourself to create one. Your guidelines will create leverage for your colleagues’ work in the future. If you need ideas, read about Upstream Prerequisites in Code Complete Volume 2.
Dynamic Based On Scope
Your technical plan should match the scope of your work. A plan covering a small set of updates to business rules will be very different than a technical plan outlining a system overhaul.
Do not be lulled into thinking that you can skip technical planning for “straightforward” work. Nothing is as straightforward as it may seem. Match your plan with the project’s scope, keep it practical, and most importantly, write it.
Acknowledge Instead Of Omit
If you are confident that your work does not affect a certain subsystem, acknowledge it. For example, if there are no security implications with your new features, explicitly state so instead of leaving the security section blank. If you believe your changes won’t cause any performance degradations, write down the reasons why. Omission can easily lead to negligence.
Gather Feedback
Gather feedback for your plan. Feedback is crucial for aligning stakeholders and soliciting expertise.
In professional software development, other programmers will always have a keen interest in your work. These people are stakeholders and you have the responsibility of keeping them informed. If stakeholders are aligned early, your project will flow smoothly. If you start coding before achieving alignment, you’ll inevitably face pushback at inconvenient times.
If your work’s scope is massive, you may not fully comprehend all the technical implications of your changes. There is a key difference between neglect and actively recognizing a weak area in your design. If you know there are a handful of security edge cases and you’ve put in your due diligence to research them, reach out to the security expert for his or her feedback.
When Someone Disagrees With You
Inevitably, someone will disagree with you. This is a great thing. Having disagreement provides new perspectives and forces you to reaffirm your strategy.
Always be receptive to disagreements. If you feel strongly that your plan is the right way to go, fight for it. If your coworker has valid feedback and has poked some serious holes in your thinking, graciously accept defeat and revise your plan.
Keep It Updated As You Build
As you build, requirements will inevitably change and your original technical plan will run the risk of becoming stale. Aim to keep your technical plan synchronized with your development. If you choose to switch strategies halfway through coding, make note of it. This may feel cumbersome, but it’s worth it.
Sometimes You Have To Code
There are times when you’ll need to dig into code before you feel comfortable with a problem. This is OK. There is a stark difference between coding for exploration and coding for implementation. If you jump into the deep-end with a prototype, make sure to come back up to refresh your technical document before proceeding to really build.
Being a Professional
Technical planning signals that you are a professional. It shows that you are thoughtful with your work and care about the craft. It shows that you are a team player and that you respect the opinions of others. Make it a habit to create technical plans.