As software engineers, we spend a lot of time fixing things. We code. We debug. We troubleshoot.

I recently had a conversation with someone which went a little like this:

(me): Do you have any diagrams of this architecture?

(dev): No, we prefer not to make pictures because they often become quickly outdated.

(me): But you know the saying "picture is worth a thousand words" right?

(dev): Yes but we prefer to write things down.

(me): And those words, are they always the right words and up to date?

It turned out that there weren't many words and those that did exist were either outdated or not easily discoverable.

Many times, we keep designs and models in our heads. When you have team members coming and going, knowledge can get lost.

Using diagrams and words to describe designs forces us to think about the choices that have been made. If documents are outdated, use onboarding as an exercise to update the words and the pictures. Knowledge is not a static thing - decisions happen all the time. The act of keeping your documentation up to date has value for everyone, especially the newer team members.

When design decisions are made, they depend on the context and they have important implications. Thinking about the lifecycle of your decision-making process is about starting to think in systems. Because this is what we are doing - creating systems for others to use. To do this effectively, we need to be aware of the lifecycle of those systems.

This is the basis of 'platform engineering' for internal or indeed external products. When we think of those we serve (such as dev teams) as actual customers, then we start to think about the platforms as products. Customer experience becomes central to the way our product is perceived and how our customers react to that.

So my thought for the week is this: if you have a platform that serves internal customers, then treat them as such. Respect them by building a system that you are proud of and that they can rely upon.

I would love to hear your thoughts on building internal platforms for your developer teams. Do you aim for self-service? Do you handle tickets for internal teams? Do you think either is a good or necessary use of resources? How do you approach identifying and building a new platform?

--

I am still working through my reactions to the McKinsey Developer Productivity article, which first appeared well over a month ago. Last week, I published a blog that surprised me and I think the reaction was split. You can read more about it in the first linked article below or find it on LinkedIn.

--

I'm helping organise the Fast Flow Netherlands meetup group. Our first ever meetup will be on the 9th of November in Amsterdam and we'd love to see you there. If you register now remember to watch out for when the first meetup goes live as places will be limited and it's first come, first served!

--

I wish you a great week ahead!

-- Richard

---

​Why Developer Productivity is the Wrong Question​

Published on September 21, 2023

“I can see why measuring productivity is so seductive. If we could do it we could assess software much more easily and objectively than we can now. But false measures only make things worse. This is somewhere I think we have to admit to our ignorance.” Martin Fowler CannotMeasureProducivity, 2003 According to the developer productivity… Read More »Why Developer Productivity is the Wrong Question​

​Read more...​

​How To Build a Successful Platform Team​

Published on September 16, 2023

In an ideal world, there would be no technical debt. No legacy. We could build whatever we like and then throw it away when we are done with it. You may have read books about clean code, refactoring, test-driven development and so on. You agree and want to strive for high code coverage and quick-running… Read More »How To Build a Successful Platform Team​

​Read more...​

​