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 more 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 keeps your execution organized.
- 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 gives you structure and forces you to consider a standard set of criteria. All software companies should have their own flavor of technical planning documents—Requirements Summaries, Architecture Explorations, RFCs, etc.
If there isn’t a template, create one. Write your technical plan to the best of your ability and take it upon yourself to set up the guidelines necessary for your colleagues to leverage this 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 which covers a small set of tweaks 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 area of the system, be sure to acknowledge it. For example, if you believe there are no security implications with your new features, explicitly state so instead of leaving the security section blank. If you believe there will be no performance degradations with your changes, write down the reasons why. When in doubt, write it down. Omission can easily lead to negligence.
Gather feedback for your plan. Feedback is crucial for two reasons: aligning stakeholders and soliciting expertise.
As a professional software developer, it’s highly likely that other programmers will have a keen interest in your work. These people are stakeholders and it is your responsibility to keep them informed. If stakeholders are aligned early, your project will flow smoothly. If you start coding before achieving alignment, you’ll inevitably face pushback.
If your work is massive in scope, you may not fully comprehend all the technical implications connected with your changes. Remember that 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 good thing. Having a reviewer disagree with you provides new perspectives and will potentially force you to re-think your strategy.
Always be receptive to disagreements. If you feel strongly that your plan is the right way to go, fight for it. If someone 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 begin coding, requirements will inevitably change and your original technical plan will run the risk of becoming stale. Strive to keep your technical plan synchronized with your development. If you choose to switch strategies halfway through coding, make note of it. This is very challenging and requires diligence. It is worth it.
Sometimes You Have To Code
There are times when you’ll need to dig into code and prototype 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 sends a signal that you are a professional. It shows that you are organized, thoughtful with your work, and care about the craft. It shows that you are a team player and that you respect the opinions of your colleagues. Make it a habit to create technical plans and I am positive it will help you become a better software developer.