20 January 2022 by Phillip Johnston • Last updated 18 July 2022An essential device-side capability to create for our devices is a command and control interface. Most commonly, this interface is implemented as a command-line shell, but it may also be implemented in other ways (such as through an IDL language). For simplicity’s sake, we will generically refer to the command and control interface as the “shell”. Shells are useful in development for testing device behaviors without having to go through full production flows. You can create fine-tuned commands that let you test individual pieces of the system in isolation. …
20 January 2022 by Phillip Johnston • Last updated 8 February 2022We prefer to manage the majority of our software’s external communication interfaces through an interface description language (IDL). In general, these languages/systems generally work in the same way: You create an IDL file which describes functions and data types You generate code for your target languages (the languages available depend on the tool), along with library code that handles encoding and decoding the data for transmission You import the generated code into your system and fill in the placeholder functions Specifically, you need to fill in the implementation for …
10 June 2021 by Phillip Johnston • Last updated 14 December 2021A common sticking point that comes up when we talk to potential clients is the need to dive right in. Any suggestion that we might spend a few weeks designing a solution is usually casually dismissed, or even explicitly rejected. Often, this comes from teams who have spent 6–12 months working on the mechanical design, or some other limited aspect of their system. They are building a complex software ecosystem, involving web servers, phone applications, embedded devices, communication protocols, update services, etc. But none of this complexity is allowed …
As engineers and programmers, we are constantly giving and receiving feedback. This is not a natural process, and it is extremely easy to destroy someone’s motivation with a poor comment. We must practice giving and receiving feedback in a way that preserves the dignity and motivation of ourselves and others. Our goal is to collectively improve the work we are doing.
Whenever you give feedback, you want this outcome:
“The best possible outcome from a response session is for the maker to want to go back to work.”
– Liz Lerman
One of the best approaches to evaluating whether our feedback will have a positive impact on the individual is to make sure our response passes through the “Four Gates of Speech” (allegedly) from the Sufi tradition:
Are these words true?
Are they necessary?
Are the beneficial?
Are they kind?
If you cannot answer yes to all four questions, then your response is better left unsaid.
Even though the material is not the way I would have written it, it is not wrong
For code, if theirs compiles cleanly and works, well, it is not wrong
It may not be optimal given other constraints, but it isn’t wrong
If I don’t like how it is implemented, that doesn’t mean it is bad
My feedback should reflect that I may be wrong because my perspective is different
I often think my way is the best because it is the most obvious (to me)
When I review someone else’s code, I forget that the way it is implemented is the most obvious way to the developer
We can talk about why it is different from what is obvious to me, but I should expect to often be wrong because the developer has put more thought and effort into solving the problems
Note
The key takeaway from Elecia’s points: “That’s not how I would have done it” is not effective feedback!
The Lerman Process for feedback can be effectively applied to engineering. It is important to proceed through the process in order – don’t jump directly to what’s not working!
View the work
Audience: Describe what you observe without value judgment.
What is the work doing?
What takes your attention?
Audience: Talk about what’s working
What do you enjoy?
What’s going well?
Creator: Ask the audience questions (prepare these in advance)
Focus: What areas do you particularly want feedback about?
If you don’t have your questions prepared, you may receive feedback that is not useful to you
Audience: Identify things that aren’t working or that you don’t understand
Ask questions
With the creator’s consent, offer suggestions
Before giving any feedback, step back and take a look at the big picture for a second. Make sure you have the context right. Then dive into the details.
Thinking About Feedback
If you’re stuck on providing constructive feedback, try the following exercises:
Ask a question
If they approached the work differently than you would have, ask them why they chose the approach
Focus on the future: what needs to happen next to improve the work?
If you have a problem to point out, what solutions can you propose?
Highlighting a problem without a solution is not a constructive contribution
If you don’t have anything to add, don’t make something up!
“I don’t have any feedback on this at the moment”
“I need to look at it again and think more”
“I have a couple of notes – I’ll email them to you”
If you think the work is really awful, then:
Focus on what needs to happen moving forward
Be brief, direct, and specific
Handle performance issues privately and separately
Receiving Feedback
Receiving feedback is extremely difficult and requires practice. Poorly given feedback can destroy our confidence. You must practice handling feedback with grace, especially when everyone’s goal is the improvement of what has been created.
Know this: You are not your work.
Know this too: Even the most brilliant humans produce work that needs dramatic improvement.
When you need receive feedback, try your best to:
Write it down – it gives you something to do with your hands and eyes during the uncomfortable moment when someone criticizes your work
Write it down in your note system even if it’s saved somewhere like GitHub by another party
Write it down even if you disagree with it
Write it down even if you think you’ll remember it (you probably won’t)
Have questions prepared to make sure you get what you need from the reviewer(s)
Ask questions when you don’t understand a point of feedback
Reserve the right to think
Not every question has to be answered in this moment
Not every decision needs to be justified in this moment
Avoid arguments
Stop talking when you are defensive
If you think bad feedback is being provided, write it down and ignore it. Do not attack the reviewer. Do not point it out to the reviewer. Instead, focus on the good questions and explore those areas. Keep in mind: even “wrong” feedback can expose problems with your work that you address in a different way than what was suggested. You should take the time to think through the feedback and prepare a counter-argument if it is truly invalid.
When a problem is identified without a proposed solution, say: “Excellent point! What can I/we do to address that?”
Feedback on your performance should be handled separately from feedback on your work. When someone attacks you or focuses the feedback on your capabilities, it can set our blood boiling. If this happens, employ the following strategy:
Take three deep breaths
Calmly and politely ask the reviewer to focus on the work itself (and your specific questions), and ask them to handle any performance concerns through the proper channels
End the discussion if the personal feedback continues
Requesting Valuable Feedback
It can be difficult to get useful feedback in some situations. If you find that someone is hesitating to give you honest feedback on a piece of code, some writing, an idea, or a performance, here are strategies you can employ:
Ask for a 0-10 score. Nobody will ever say 10, so then ask how you can get closer to a 10.
Ask what 20% of material the person would cut, and what 20% of material the person would keep.
30 October 2019 by Phillip Johnston • Last updated 9 October 2024Problem statement: code is not the only thing that matters. Why Documentation Matters Fundamentally, without documentation, nobody will know how to use your software. Even worse, in a couple of months you won’t know how to use your software either – especially if key members of the team depart. Documentation is valuable for many other reasons: Documentation is scalable, personal support is not. The efforts of an individual or group can be referenced by any number of individuals, reducing the support burden. Documentation can be used to aid training and …
Communication is a foundational skill that applies to most human endeavors. Engineering, programming, and product development are no exception. We continually apply our communication skills, whether we work as a team, write documentation, comment code, take notes to remember things later, report issues, or market the product.
As engineers, programmers, and product developers, we rarely work alone. Getting a product out the door usually requires multiple individuals to share the same goal and coordinate execution.
A foundational book for those who are new to working on a professional engineering team is The Unwritten Laws of Engineering. Originally published in 1944, the book has been recently updated with a revised edition (Phillip only read the original, so we cannot make any claim to the value of the revised edition).
The first section of Unwritten Laws is related to teaching beginners what they need to learn about working with a supervisor, colleagues, and outsiders. The third section oft he book contains additional information about personalities and workplace behavior that can be useful for those new to navigating the workplace.
You can learn more about working on a team by reviewing the Managing Your Career entry.
From Around the Web
Captain Awkward is an advice column about social skills and human relationships
These phrases are meaningless, instead ask people to be specific
Providing Feedback
As engineers and programmers, we are constantly giving and receiving feedback. This is not a natural process, and it is extremely easy to destroy someone’s motivation with a poor comment.
Most meetings we’ve participate in are a waste of time. This does not mean that meetings should be completely discarded. They simply need to be focused for improved results.
You might think that meeting effectiveness is a strange topic to highlight. Consider these quotes from Jason Fried:
First, there’s no such thing as a one hour meeting. Basic meeting math applies to all meetings: The time blocked off doesn’t equal actual time spent. The time spent is the time blocked off multiplied by the number of people in the meeting. So, a one hour meeting with 6 people is a six hour meeting. A 15 minute minute meeting with 9 people is a two-and-a-quarter-hour meeting. Even a 15 minute meeting with 4 people costs an hour of collective work time.
Factor in salaries and hourly rates, and meetings get expensive quick. Add in attention diverted and the cost goes up even more. Was that last meeting you had worth it? I’d almost certainly bet it wasn’t. Still not convinced? How would you feel if you had to regularly expense $1200 so you could “tell a few teammates something”. Think that would go over well?
Whenever possible, avoid meetings. Meetings force everyone to stop their work and be present, even if what they were doing was more valuable than the meeting itself (and it often is). Use alternative communication methods and resort to meetings when progress isn’t being made.
To improve the effectiveness of meetings, we recommend:
Sending out a written agenda ahead of the meeting (ideally with the invitation)
Your meeting should have a specific problem that needs to be moved forward by the end of the meeting
If you need someone to contribute something to the meeting, inform them ahead of time about exactly what you need and ask them to come prepared
Come prepared to the meeting yourself
If you’re not prepared, defer the meeting
Make the meeting as short as possible
We default to 15 minute durations for our meetings
Include only the bare minimum number of people who will positively contribute to moving the problem forward
The more people included in a meeting, the more time and money the company loses
Take notes during the meeting
End the meeting with a solution or decision, as well as the individuals responsible for the solution
This identifies a true waste of time: either the attendees weren’t prepared, you weren’t prepared, or the topic was not important enough to call a meeting for
Send out notes after the meeting
Include important notes summarizing the meeting’s outcomes
Highlight any action items that were identified during the meeting
Put timelines and due dates for next steps in the meeting notes
If you have a recurring meeting, cancel the meeting if a written update would suffice
If you’re an attendee, ask the organizer if you can skip unless there is something specific you’re needed for
When Phillip was in college, a significant amount of time in his Computer Engineering program was dedicated to technical writing. Most of the students complained that it was a waste of time. However, once Phillip entered the workforce he realized that 80% of his time was spent communicating with others.
We often have vague notions in our heads, and attempting to effectively communicate those notions to others can be difficult. Writing forces us to clarify our thoughts and exposes holes in our thinking.
Writing is not a natural skill, and it requires practice and regular feedback to improve. If the opportunity is available, we recommend taking a writing class or joining a writing group.
Written communication can take many forms, but the most common ones we encounter are:
Even in the days of Slack, email tends to be the lifeblood of business communication. Aside form internal communication uses, email is the primary way we communicate with external contributors, partners, and vendors. Improving our email habits has a dramatic impact on our day.
Our general tips for effective emails are:
Use a descriptive and meaningful subject line
Keep the message as short as possible
People tend to ignore long emails “until I have time to focus”, which invariably never comes
Be polite and formal
Think about ways your tone can be misinterpreted and adjust accordingly
Are you trying to be too brief? Perhaps you will sound curt and demanding
Without body language, sometimes additional sentences are needed to soften a message and give the correct tone
As with meetings, don’t send an email if another form of communication (such as a phone call) would be more effective, especially if there’s a chance for an emotional reaction.
From Around the Web:
five.sentenc.es is an approach where you limit email responses to five lines or less
Note that this may not always be appropriate for technical emails
Every project has problems. Every project needs a way to report and manage those problems. Everyone who has worked with an issue reporting system can tell you dozens of horror stories about horrible bug reports that they couldn’t work with.
Writing a great issue report is a skill that every engineer and developer should master.
Here’s our guidelines for writing a great issue report:
Each report should describe a single issue
Break multiple issues up into separate reports, even if they are related
Provide steps to reproduce the problem
Provide information about your environment, including hardware version, software verson, OS version, and any other relevant information about your setup
Describe the expected results for your scenario
Describe the actual results observed
Comment on reproducibility – does it happen every time? once in a million?
Describe the impact that the issue has on customers/you/the company
Pull Requests and other merge management strategies are common on modern software projects. Rather than allowing contributors to directly commit to master, the change must be proposed and reviewed through automated and manual processes. Writing effective pull requests descriptions will allow the other contributors to process your Pull Request more quickly.
