Before participating in a career panel at the TechRadar conference in November’22, I sat down with the organizers to talk a bit about my career and of course – the unavoidable subject (even though we tried) – women in tech (Hebrew).
Month: January 2022
Rubber duck debugging – out. Talking to a person – in.
If you’re part of the software industry you may have heard of rubber duck debugging. The idea is when you’re trying to debug an issue, you’ll explain it to an inanimate object and the answer will present itself. This sounds cute, especially if you visualize yourself speaking to a rubber duck, or teddy bear, or cat. But trust the software industry to find the dark side of any cute idea.
Many software engineers, particularly when they’re just getting started (but not only!) find it hard to strike the right balance between asking questions and figuring things out on their own.
First, they’re afraid of looking “dumb”. Second, many engineers convey (whether on purpose or inadvertently) that their time is too precious to answer “unimportant” questions. Third, often effective communication is neither engineer’s strong suit, and things may break down in that area.
Continue readingHow to write an effective design document
So, you’ve come up with a beautiful, elegant, solid software design. But to move forward you have to get it approved. And to get it approved, you have to communicate it to others. Because, unfortunately, having the idea in your mind is not enough to get it built as you envisioned it. Getting your design across effectively is not a simple task, and many software engineers are not skilled at it. But as most skills, your skill at writing design documents can be improved, I hope this post helps you on your way.
As we write a design document we should keep two main concerns in mind:
Purpose
In my opinion these are the three objectives of a good design document:
- Get buy-in for the high-level architecture from relevant stakeholders (engineering managers, technical leaders, engineers from other relevant groups).
- Provide a blueprint for implementation.
- Provide documentation (for historical reference, onboarding etc.)
But most importantly: A design document may include a summary of requirements, if appropriate – but it should not read as a wishlist. Someone reading a design document should get a clear idea of what you are planning to do.
Audience
Who will be reading the design document:
- People who need to approve/provide feedback on the design.
- People who need to do the work outlined in the document.
- The author (you’re not going to remember why you did any of this in a couple of months).
In addition to their role, readers may have varying context on the design:
- Internal readers who already know the background whose memory just needs to be refreshed.
- External readers or newcomers who have no or close to no context and need a high level overview of what this document will cover.
When we write a design doc we need to keep the purpose and the different audiences in mind so we can write the right thing in the right place at the right level of detail.
Now that we know why we’re writing a design document and for who, let’s get into what it should include:
Continue reading