Explaining software engineering concepts to non-engineers
Software engineering does not need to be a rocket science all the time
No matter which company you work at: chances are that you - a software engineer - work with both technical and less technical people. I’m in the same boat with my current job. I love all these exchanges yet you probably agree with me that explaining concepts related to software engineering can be rather draining at times.
Have a look at the image below: how many are you familiar with?
As to be expected there are a lot of terms and acronyms we regularly throw around in code, threads, meetings, issues and talks. For an engineer CI (continuous integration) means something different than for a marketer (corporate identity).
We could spend days and weeks going over all these but I figured there must be an easier and faster way to explain these. Recently, I came up with a short talk aiming to give an introduction to software engineering and product concepts and topics for non-engineers. The goal was not about turning marketers to software engineers. My guiding principle for this talk: create awareness and understanding for a variety of relevant software engineering concepts in a somewhat fun and not so serious way (which the human brain can remember far better than plain boring facts!)
In this post I want to share a few slides that I created for this purpose.
Difference between UI and UX
Many websites, apps and ads are trying to be as flashy and beautiful as possible. This comes primarily from the desire to impress the audience as that would make them buy and use our advertised products. After all we need WOW moments, right?
Yet there are plenty of examples where something is not as flashy or beautiful yet we end up buying and using this one instead. “Form follows function” is a design principle originating from architecture and industrial design which may also apply for digital products.
In the image above you see ketchup in two different forms: in glass and in a tube. While the ketchup in the glass looks better on first glance it has a disadvantage compared to the ketchup in the tube. In practice, it’s harder to get the ketchup out of the glass compared to the tube where you just have to squeeze. Same for software: you could allow users to build a fully customizable dashboard to view the engineering metrics of their company or you could provide a ready-to-use dashboard with four charts for showing the most important metrics (DORA).
Therefore: UX > UI (in most cases)
Ownership in a software company
I had a few coworkers in the past who enlightened me on the definition of done and how ownership looks like in a DevOps organization. I love coding but that does not mean it is the only thing I am doing all day. In a software company the work of a software engineer can also involve preparation work, quality assurance, building CI/CD pipelines and introducing monitoring tools.
My former engineering manager told me something like this: “Instead of documenting the problem we can try to fix it; code, processes, …”. Just imagine someone starting in a newly founded startup after having worked at an enterprise for years. Suddenly, not everything is defined and polished yet. One could complain about all these things and wait for someone to bother OR the person could take the initiative to change for the better: e.g. by improving the setup guide for future developers, writing tests, improving the build times, introducing proactive monitoring and alerting.
Continuous improvement
Remember when you moved into your current place? When everything was tidy, organized and clean? And then you came home late once and you did not feel like washing the dishes so you postponed it (“yeah, I’ll do it tomorrow morning”). And then you did not do it next morning. And your room mate also skipped washing the dishes as he figures: “I just leave my dirty dishes here together with yours so someone can wash them all together”.
Code usually lives for a while. The hacky code which you thought you would throw out after the customer presentation next week often survives, becoming product functionality used by paying customers. And the costs for fixing issues with this code increases with time because of lack of comments, missing automated tests and unreadable variables.
By adhering to a “continuous improvement” mindset you are making your own and your future coworkers lifes easier: e.g. by documenting a newly added function, adding a unit test case to prevent a bug from reappearing unnoticed, making function and variable names more descriptive.
YAGNI: just because you can build it does not mean you should
Most of us do not have unlimited resources and time. Therefore, we need to make the best with what we have. If we do not have our limits in mind then we can easily fall into the trap of losing what is important.
I’ve seen plenty of code which is unused but with a comment: “this will be used in ticket JIRA-1337”. The code and the comment have not been modified or used in years but they are still there, waiting for that brave engineer to ask the question “who wrote 300 lines of code for mimicking Redux without actually using it anywhere in our code base?”.
Keep it simple (stupid)
There are so many great tools and frameworks out there, just waiting to be tried out by you! Just take a look at all the different services offered by Azure or AWS. And Kubernetes is the way to go so I use it from the start for our two-people startup, right? Well, maybe not!
It is easy to go from something easy to complex. However, it can be much harder to go from something complex to easy. Do you really need Kubernetes if you will only have one running backend service until next year? Instead of having to deal with all this overhead you could opt in for a more lightweight solution like Render and focus on the most pressing business problems.
Do not reinvent the wheel until necessary
When looking for a third party solution for a problem one can easily get the feeling “I could do this better myself”. Coming up with clever and sophisticated solutions can be fun but there is a huge pitfall as well.
Let’s say we want to produce a new electric car. A car needs wheels: do we buy some or build our own? If we build them ourselves we can tailor them perfectly to our needs. But we also need to gain expertise, physically produce the wheels and maintain them. Don’t we have more important issues that only we can solve?
It can be tempting to just build your own state management solution / framework / deployment script. After all, you want to have full control and flexibility which is good, right? Remember that any product functionality probably needs to be maintained. And maintenance costs are usually far higher than the initial build.
Move faster because of tests
Software engineers who have worked long enough on a project which has tests appreciate the benefits and safety which tests provide. There are lots of people who never worked on something for a longer period of time. It could be because of having different projects (freelancing, outsourcing work) or because of switching jobs. Without working on something for a longer period of time we will never really own something or grow beyond a certain point (see this video by Steve Jobs).
A product grows over time. The code does so, too. What used to be a simple function with one parameter might evolve to a sophisticated recursive function with five required and three optional parameters. The moment you have to touch someone else’s code you will appreciate having good tests. Good tests will tell you more about the functionality the code is supposed to provide, the edge cases we need to consider: in some cases far better than code comments could ever do!
BTW: you are awesome if you recognize where I got the inspiration for the headline of this slide.
Writing code for your future self and coworkers
Have you ever written code that is self-documenting™️? Or beautiful? All of us probably have done so (at least we thought that when we wrote this code). In the best case you will still be able to remember when you or another developer has to touch this code again. In the worst case nobody will know what to do with this code: there is no linked issue ticket mentioned in the commit message, there are no tests or code comments, the variable names are all single letters and there are dozens of impure function invocations.
In many (not all!) cases we should prefer writing readable code rather than writing prematurely optimized or beautiful code that nobody understands. Remember KISS: a simple and straightforward solution can easily be improved or extended while a complex solution will scare off newjoiners and slow you down in the long run.
Uninterrupted focus time is important
Focus time is important. Remember that different jobs need different skills or cater to specific personalities. As much as I like to talk to both developers and non-developers during or after work, you need to have some time for yourself.
There was a point in my life when I felt exactly like this: jumping from meeting to meeting with little breaks between them. A bad feeling: having no time to actually get invested into a topic because you need to switch context soon enough. Luckily, I was not the only one who felt discouraged by this so we brought it up. What did came out of this:
- Focus Friday: not holding any additional meetings (few exceptions like the daily standup in the morning)
- Checking whether we need to involve all these people: making people aware of meetings but not making them mandatory so you can decide for yourself if your participation brings anything to the conversation
- Favoring asynchronous communication (e.g. Slack or Confluence in our case): most things are not so urgent after all, are they? And we can always read up on a decision that was written down somewhere.
Conclusion
Thanks for reading this post. If you were wondering: the feedback I received was great! It turns out that a lot of the concepts, topics and challenges we deal with as software engineers can be found in other work areas as well. Not everyone calls it over-engineering or YAGNI or KISS but these things may exist under a different name in their world. A shared understanding is crucial, especially when you work with people from different areas and with different backgrounds.
Anything that I missed which might be helpful? Let me know in the comments.
