A new edition of ThoughtWorks’ Technology Radar was published this week.
To no one’s surprise, AI is the big theme of this edition, I was however attracted by 2 items:
Mermaid is in the adoption quadrant.
In my current project at ING, we used documentation-as-code from the beginning, except that our choice is PlantUML. What I can comment on my experience, in 3 aspects:
- Consistency: By treating documentation as code, it becomes easier to maintain consistency between the code and its documentation, especially when it comes to software architecture. We use C4 and when we make structural changes, the diagrams and the new code are versioned in the same PR, showing exactly the evolution of the system;
- Collaboration: Between engineers is great because it sounds more natural to edit documentation in the same flow as the software is edited. Outside the world of engineers, there is a barrier as it is necessary to know the markup and a point-and-click interface is more intuitive. This is evident in the discussion of the software context, in which interaction with business colleagues is necessary;
- Automation: This is where documentation-as-code shines. If the team culture encourages comments on your codebase, several diagrams can be automatically generated.
It’s difficult for me to agree with the argument that we should embrace complexity in software development. Complexity is something that must be combated in our design, in our implementation, in our processes. Using Cynefin as guide, our goal is to transition from the complex to the complicated and, look, the article uses AI as an example of complexity but AI operates in the complicated, by using patterns and knowledge to deliver decisions and answers.
I remember Dumbledore saying to Harry: “Soon we must all face the choice, between what is right and what is easy”. An architect’s job, and all engineers are architects to some extent, is to resist the temptation of the easiest solution; It is common in these situations to introduce accidental complexity. If we are talking about essential complexity, ok, but we should still fight to reduce it. But I don’t blame Thoughtworks for the approach, Dijkstra once said “complexity sells better”.
Read the Radar, it’s always interesting, especially check out what’s close to the adoption level.
This week I was in London attending the ApiDays event. Once a year I participate in an external event, in addition to studying alone, it is important to meet professional colleagues and talk about what happens in the trenches. To my surprise, AI was not the central topic, I watched around 30 lectures and only 4 were specifically about AI. Two major themes at the event:
API Governance: Emphasis given to the API lifecycle: definition->design->development-> testing->publication->operation. What I’ll take home:
- The importance of documentation is the central point of your API, whether consumed by developers or read by robots.
- The role of patterns in design. This is a growing market and your consumers expect you to follow OpenAPI, AsyncAPI, Semantic Versioning, HTTP response codes, Protocol Buffers definition language.
- Your operation must provide freedom of choice, do not assume a cloud provider, do not force a gateway, be open.
Democratization of APIs: Here there are 2 views that are converging, on the one hand experts say that we should develop APIs thinking about devops and gitops. This vision places great importance on the governance aspects mentioned in the previous item; In addition, this vision highlights interoperability and composability as essential attributes for modern APIs. On the other hand, if we look at the most common composition of companies, only 10% are in the technology area (Gartner research shown in one of the lectures); We have 49% end users and 41% classified as business technologists. These 41% create technology or analysis solutions based on the solutions that the IT areas provide. They coined the term ‘post-API economy world’ to embrace these people who should have easy access to APIs. The simpler it is, the easier it will be for innovative products to emerge from the available information provided. This second vision focuses on open and public APIs, ecosystems and marketplaces.
I will mention 2 tools that I tested at the event and found fantastic:
Superface.ai: OK, there are API catalogs, we know the concept of observability, how do we deal with APIs that are similar but have different formats? Think of wttr.in and OpenWeatherMap, both of which allow you to see if it’s going to rain in London today. But the similarity ends there, it is necessary to write code for each of them. Furthermore, if one of them is unavailable, you are responsible for routing the order. Superface deals with this: (1) you say what your contract is (2) Superface has autonomous agents that discover APIs consistent with your contract and maps your contract to the contract of the APIs it found. (ok, there’s AI here🙂)
Postman mocking servers: I often use Postman to test APIs, and I discovered that you can prototype your API in it. Design your methods, specify contracts from examples, and Postman creates documentation and an endpoint. When I wanted to think about an API, I used httpbin, this is much cooler.
In 2008 I worked at Itaú in the IT for relationship with investment funds. I was part of a team responsible for fund performance reports, used by traders to guide their strategies. Our support was 24×7, especially during the night when these reports were generated. We discussed whether it would be possible for the engineer responsible for stand-by to work from home; our request was denied on the grounds that it was more productive to work in the bank’s infrastructure, where everything was available and where all the stand-by engineers were. 2020 came, Covid came and we know the result: we work very well in our homes. My experience and that of colleagues: we work better from our homes.
Zoom has grown exponentially precisely in this niche and last week we read that its CEO prefers work at the office. Eric Yuan points to speed of innovation and interaction as motivators, between the lines I read ‘our productivity needs to increase’, yeah, productivity again is the culprit. Also between the lines, I read that on Zoom the high command doesn’t trust people except when they’re around so they can see what people is doing. Microsoft showed this in the 2022 Pulse Report:
“The majority of employees (87%) report that they are productive at work (…)” but “85% of global business decision makers say that the shift to hybrid work has made it challenging to have confidence that people are being productive”.
I work in IT, this is the world that I know and about which I can give my opinion. Here, engineers are productive working from home and there are doubts in the C-level. McKinsey gave voice to this feeling and brought its idea 2 weeks ago: Yes, you can measure software developer productivity. Kent Beck wrote about this in his newsletter. Given that crisis of confidence that I mentioned, metrics are proposed to measure what I am doing. Kent is precise in his analysis, I agree: they confuse “activity” with “productivity”. Productivity is about delivering value and transforming your company.
The dichotomy of remote work vs. in-person work should not be the central discussion, trust and productivity are the central elements. And besides, do you want to go back to the office every day?