It’s time for another update on “Designing APIs with Swagger and OpenAPI”, the upcoming API design book from Manning Publications that I’m writing together with Josh Ponelat. Since my last update, we’ve made a lot of progress, and we’re near the finish line for the book. We’ve slightly adjusted the table of contents in the previous months and restructured the material into three parts instead of four. While we’re busy working on part three, the second part is now fully published on MEAP (Manning Early Access Program).
At the beginning of the second part, which was part of our previous MEAP release, we introduced a fictional development team and their project. The team decided on an API Design First approach and created their OpenAPI description based on a domain model and user stories. In the remaining chapters of the second part, we’re going on the journey from design to implementation. Our topics range from auto-generating code with OpenAPI to additional crucial issues such as authentication. Throughout, one of our major themes is the workflow for handling API changes to ensure that the OpenAPI description remains the single source of truth upon which every developer can build. Through a great process, frontend and backend developers can work independently, and in the end, their components will still work together.
You can preorder the book “Designing APIs with Swagger and OpenAPI” on Manning’s website now, get immediate access to MEAP and receive a full ebook or physical book later.
Performance is a crucial aspect of APIs. Stress testing is one way to determine an API’s performance and behavior when load levels are critical. Will your API fail under stress or behave in unusual ways? For BlazeMeter, I wrote an article titled “3 Things to Look Out for When Stress Testing Your API”. The first thing I highlight is the environment in which you run your tests. The second aspect is the traffic patterns you test. Finally, the third issue is the assertions you include in your tests. Head over to BlazeMeter’s blog to read the full article.
Disclosure: This work was paid for by BlazeMeter.
With COVID-19 still preventing in-person conferences in most parts of the world, API the Docs started the third season of their virtual events series. As usual, I’m attending these events to learn more about APIs and developer experience and gain insights into the problems and solutions from different companies in the space. Here’s my subjective summary of the latest installment.
First of all, I find it impressive that they did an event with an all-women speaker lineup, rare for technical talks. I enjoy this arrangement because it normalizes women in tech while avoiding direct comparisons between speakers that are (subconsciously) based on gender, which is a risk of token representation.
Yantian You, the first speaker of the night, shared the journey of SAS as they moved from code-first to design-first when it comes to creating APIs. Yantian also showed where the design process starts: with post-its on whiteboards, not API design tools. Those come next, of course, and SAS has built a pretty impressive internal toolchain in their continuous integration (CI) pipeline. It even includes server code generation to assist backend developers after API changes. There’s also a custom tooling package with features such as linting and contract testing that works locally and in CI.
Next in line, Anna Tsolakou from Amadeus made her case for building a developer relations (DevRel) team. She said that DevRel is a diverse team with different roles representing the customers internally and, on the other hand, the API outside of the company. According to Anna, there are three rough areas of activities. The first is developer experience, which includes SDKs and documentation. What I found impressive is the massive impact of SDKs on developer productivity, even for senior developers. However, I’m wondering how reproducible these tests are for different API designs and tech stacks. For documentation, Anna quoted that they got 300% more visits to their blog after increasing the ratio of educational content (now at 80%) over promotional content. In combination with video content and open source sample apps, it is totally in line with my take on the relevance of developer content. The second area is community-building. Events like hackathons are excellent for feedback. Amadeus uses Discord as an online forum, and engaging with OSS communities and collecting feedback outside standard channels are essential activities. That is the third critical area. The DevRel team collects feedback through various channels and aggregates it for internal use.
The last speaker of the day, Mihaela Ghidersa, gave a critical perspective on the backend-for-frontend (BFF) design pattern and suggested GraphQL as an alternative. She spoke about the changing responsibilities and shifting complexities of backend and frontend, which may lead to a “war” between developers in each area who blame the others for problems. Those usually start when the frontend needs additional data and developers need to negotiate the balance between fat payloads and chattiness. The BFF design pattern allows frontend developers to build a custom backend as middleware in front of the backend API. A BFF is typically more complex than an API gateway, but the key differentiator is ownership by a single client team. With GraphQL, there is just one backend API. Frontend developers can formulate queries to get the data that they need for their clients. It’s no silver bullet, though, and developers should take a full-stack perspective and choose which architecture works best for them while having empathy for different teams and perspectives.
The following virtual API the Docs event takes place on the 5th May, and tickets are available for free.
Making friends and staying in touch with friends are essential parts of our shared humanity. More than ever, the whole world of people is available to us through our computers and smartphones. With the communities we belong to, we can continuously make friends. Staying in touch, however, is a different beast. I started using a Personal CRM and hosted a Ness Labs community meetup earlier this year to discuss the subject. The hour-long meetup was an excellent opportunity to demonstrate technical setups. Still, it wasn’t nearly enough time to dive into the “Why?” behind our social networks and reaching out to people. To give the philosophical side of it the time it deserves, I teamed up with Vajresh Balaji, and we co-hosted a three-hour Interintellect salon. We titled it “Cheating on Dunbar”, cheekily referring to the popular Dunbar number that states that we can only maintain around 150 people in our heads.
With nine participants, the salon was one of the more intimate ones. At least some mentioned not being good at socializing as a motivation for attending, feeling that it limits them. As an intro question, we asked them to tell an exciting or unusual story about making a new contact. We heard about someone finding a co-worker they didn’t know they were working with through Twitter. Someone else mentioned a life-long friend they made in college, even though initially thinking they had nothing in common with that person. Another story included a random encounter at an airport.
Interestingly, online communities came up quite a lot. Most of us introduced ourselves by mentioning communities in which we participate. We talked about how every community has a different feel and how even interacting through text-based media as forums and Twitter gives you many insights into other people. Each community can also be a springboard to find the next. Their advantage as social gathering spaces over schools and workplaces is that these virtual groups can stick with us over a more extended period.
On the other end of the spectrum, though, we also talked about offline activities like CampContact and improvised dancing, including physical touch and authentic relating to connecting with people. The sensual part is often missing in our interpersonal encounters, especially during the pandemic where hugs are a no-go. As a virtual replacement, some people remain on video calls during the night, and there’s even a thing called “Lullaby Club” on the Clubhouse app where people stay connected to others while they’re sleeping.
Of course, there are also offline communities we’re part of, like neighborhoods. Those are not usually the people we have most in common with, but they are necessary as a local support network. My neighbor is more likely to notice when I’ve gone missing than a person who follows me on Twitter where someone else easily captures the attention instead. Rebuilding these local bonds can be challenging after moving to a new place.
Whether online or offline, only a subset of the people you meet “graduate” into being your friends outside the community you initially met. We talked about how communities can facilitate this. Our take is that there’s a need for (pseudo-)proximity and repeating interactions, both planned and unplanned. Hence the best online communities are well-organized and have regular events or meetups as well as a space to stay connected (a forum or chat, for example). They need to provide opportunities where connections can happen. It’s also essential for deep and meaningful relationships to have a setting that allows people to let their guard down.
Can we measure the ROI (return-on-invest) for relationships and community participation? We found no framework to describe this. It’s just an intuitive thing. One problem is the timescale, considering the return may be coming much later. In general, though, friendships are not transactional, and socializing usually feels valuable. And if it meets your need, why would you look too hard at the cost?! There are also potential adverse reactions when we think of relationships, especially outside of professional contacts, in these terms.
The next part of the discussion was about note-taking. Most of us did take notes about online events and conversations. Still, we also pointed out that a lot of communication is self-documenting, e.g., in messenger apps, in social networks, or the camera roll on our phones. There’s no need to write down everything, only when it’s insightful. As one participant put it nicely, one goal in any relationship is to have conversations that are so rich and valuable that you want to take notes about them.
Even when notes only capture the surface and contain mostly facts and only a few emotions, we wouldn’t necessarily want the other person or anybody else to read them, for example, because they might include wrong impressions of a person (in line with Rockefeller). There shouldn’t be any stigma attached to note-taking as a way to invest in a relationship. We can frame it as an accessibility tool instead. Something we briefly touched upon was the danger of losing access to digital tools and how open-source and export abilities counteract those.
We also talked about reconnecting and regularly staying in touch. Reaching out on a schedule can be awkward, as the other person probably will notice you’re reaching out as an obligation, but there can still be value in it. One participant mentioned a strategic list of people she’d like to be closer with and how she could achieve it.
One of the objectives of excelling at maintaining notes about your contacts can be to connect other people, for example, when they’re looking for a job or based upon shared interests. None of us did that strategically or tracked the impact, but we relate to the joy that it brings.
Overall, the salon was an delightful conversation that, as expected, didn’t answer all our questions but probably brought us all a step closer to being better at relationships. As these free-flow discussions always turn out different than anticipated, I didn’t expect us to have such a deep focus on communities. Maybe I’m underestimating their function.
Perfectionism is a topic of interest for me, so I was pleased to learn that Anwar Al-Kandari hosts an Interintellect salon on the subject. The event time wasn’t working well for me, so I could only attend for the first one-and-a-half hours, but I found these already quite valuable. Hence, I decided to make another little salon write-up for my blog to work through my notes.
Interintellect salons typically start with an intro question. Anwar asked us how perfectionism affects various aspects of our lives. Most of us had stories to tell about the negative aspects of perfectionism, with one participant going as far as calling it a “disease”. Another one said she saw perfectionism destroy other people, which made her views turn 180 degrees. But why is perfectionism so dangerous?
The most significant risk is that nothing ever gets done. We either never even start or spend time doing research (“procrasti-learning”) instead of doing the work we need to do and learn-by-doing. Perfectionism is incompatible with finite budgets, and we all have limits. Another danger is that we become unable to celebrate small wins and only focus on our shortcomings. Quite likely, the practice of “ghosting” another person comes from applying perfectionism to communication and conversations. It can also hurt relationships when we enter them with ideas about, e.g., the “perfect marriage”.
A recurring theme of the conversation was comparisons. We tend to compare ourselves with people we want to be like, but these people are often the best in a specific field. That can set an unattainable standard. A root cause for perfectionism could be that a person develops a taste for quality within a particular area, let’s say music, before acquiring the skills to produce the same quality themselves. A critical thought from the salon that I previously expressed in my musings on “parallel focus” and “serial focus” is that you can hardly compare, for example, the results of your part-time passion for playing music with full-time professional musicians. We also talked about comparing ourselves to people who are at a different stage of their lives. An older person had more time to refine their skills while at the same time there’s some pressure on succeeding young. Competitiveness in your childhood, such as being compared with siblings, doesn’t help. From my experience, though, I can attest that the focus on age becomes less as you grow older yourself. Once it’s physically impossible to make the “30 under 30” lists, life gets more relaxed. Getting to know people who “made it” at a young age can also be eye-opening to see that not all that glitters is gold.
On top of that, what can we do to become less perfectionist? There is no simple cure, but the approach should be to set focus on the process of creation rather than the results. Try to reframe your inner critic as your inner editor. The voice inside your head doesn’t want to criticize you; it just wants you to improve. Humans are always changing and growing throughout their entire lives. Nevertheless, we also have to remind ourselves that even being our best selves is different from perfect. And be careful not to become a perfectionist about not being a perfectionist!
My friend Clo, a user experience designer specializing in mindful design, organized a salon on digital wellness. To kick off the discussion, she asked the participants to explain their methods of taking care of themselves in their digital interactions. One person talked about their experience of going off the grid, i.e., not using social media, for a full year. In contrast, others spoke about setting their phones into a do-not-disturb mode, unfollowing people (without unfriending), and tools that block the websites’ distracting parts. That is something I do, too, and I created a browser extension for this purpose called Disable Twitter Feed. However, even those of us who admit to social media’s addictiveness agreed that staying away from it in its entirety for a long time is very difficult. For example, local businesses often use Instagram as the primary channel to communicate their offers, instead of a website or a newsletter. That could be a whole discussion in itself and an exciting challenge to move small businesses towards the IndieWeb and increase their independence from social networking silos without losing their audience. Another way for individuals to improve their social media experience with discipline is to set intentions for it. The choice is to use it actively, i.e., engage with content and people, instead of passively, i.e., “doomscrolling”. One attendee said that she only opens the Twitter app on her phone with a specific goal in mind.
The discussion took a quick and unexpected turn from social media to work-life balance and the boundaries separating people and their employers, especially when working remotely. The main problem is that people use the same device to receive social notifications and messages from their work teams, combined with managers setting the expectation of always-on employees. In this regard, there are substantial cultural differences between countries and industries. For example, European companies are much more respectful (and legally obliged) about these boundaries than their US-American counterparts. Related to that is the cult of working long hours, typical in Silicon Valley, consulting firms, and the finance industry. While some people may enjoy it as a learning experience, it shouldn’t set everyone’s expectations. It’s worth improving company culture and establishing proper communication etiquette, but it is hard to do from the bottom when employees feel insecure. Leaders should set a good example and consider it a measure of employee retention to treat their teams with additional respect for their time off. One way could be scheduling messages to deliver when we expect the other person to work anyway.
For the next part of the conversation, we talked about news production and consumption and the problem of filter bubbles. Regarding news production, there is a problem with the business model and the incentives. Articles that go viral trump everything else, which drives news organizations to focus on outrageous topics. Once they’ve identified a specific niche audience, they may double down on it, and that’s how Americans got Fox News. There are better funding models such as public media, subscriptions, donations, and services like Scroll. It would be a fallacy, though, to believe that paying more and getting rid of ads would suddenly make all news enjoyable.
As consumers, we can curate our newsfeeds with different sources to avoid being locked into a single perspective. The Internet allowed us to expand our circles beyond our immediate surroundings, and we should leverage that. Of course, even a curated feed is still a manufactured reality that doesn’t represent objective reality, if such a thing even exists. On the other hand, always challenging our views is exhausting. A filter bubble is a comfort zone, and sometimes we need to retreat into one as an act of self-care. Escapism isn’t always bad, and avoiding news or politics and going into a “peaceful” mode may sometimes be the right move. Most information is irrelevant anyway or lacks the context that allows us to judge its relevancy properly. The bigger picture and valuable learning evolve from looking at history or engaging with deep-dives such as long-form writing and podcasts. As usual, engaging with current news is a trade-off, similar to focus and serendipity in general, and requires a bit of discipline. Reading on paper can also be great as there are no hyperlinks that make us jump around, so it’s easier to focus on a single piece.
The next part of the discussion was about digital privacy and business models in more general terms beyond the news industry. We talked about how it’s hard to convince tech companies to implement “humane tech” when it may hurt their bottom line. Companies provide options to customize settings but generally apply the defaults that benefit them. As a result, consumers and companies continually blame each other for the responsibility. Consumers don’t reward apps that care by favoring free-with-ads options when they exist. On the other hand, privacy appears to be a privilege when many people and organizations, especially in lower-income countries, cannot afford better, more privacy-friendly tools.
Open-source tools that give users more control don’t have a great user experience because technically-minded people build them for other technically-minded people. These people possess a “purity mindset” regarding privacy and decentralization but aren’t working with designers to make their solutions accessible. Again, it’s a funding issue, but maybe philanthropists could step in, as they do for the Signal messenger.
Near the end, Clo circled back to the beginning and asked us if there are any tools that we want to add to our toolbox. Participants mentioned time-blocking, virtual co-working for accountability, looking to contribute more on social media than consuming, stopping using devices in bed, and trying to get rid of FOMO.
Clo’s salon was a great conversation touching many topics related to digital wellness, but there’s so much more that requires a discussion. For example, how sustainability plays into it. Also, it’s crucial not just to discuss the problem but also to find solutions.
I’m looking forward to follow-up discussions, whether that’s on social media, in one-on-one chats, or another salon.
“What are the Personal CRM setups that different people use to make sense of their contacts?” That was the question that kicked off my Personal CRM meetup last Tuesday. After posting a little write-up about my experience hosting the event, I want to follow up with a written summary of the discussion.
To that initial question, there were around three groups. One group uses specialized tools like I’m using Monica (and someone in the chat mentioned clay.earth as an alternative), and a second group employs more general tools like Roam, Notion or Airtable. There was also a third group that doesn’t use any software and tries to keep it all in their head. Members of the second group heavily rely on Roam’s templates, bidirectional linking to connect people with concepts like places and topics, and daily notes to have a journal of conversations. On the other hand, the third group is either worried about the friction of introducing additional digital tools into their workflow or hasn’t found the right one yet.
After collecting these additional thoughts from the audience, I gave a demo of Monica, covering the following: dashboard, tagging contacts, profile view, the stay-in-touch feature (which I don’t use yet, but that allows you to get periodic reminders to check in with a person), activities including tagging multiple people (which is the feature I use most) and activity reports, the journal view, and, finally, all how you can customize the CRM and that you can access your data through an API and WebDAV. I skipped over the gifts section, but a curious participant had noticed it in the screencast, so I explained later that it allows you to keep track of gifts given and received, which kind of sold the system to her immediately!
A discussion followed the presentation, where different participants of the session asked questions. The first and very valid question was about the specific value that I’m getting out of using the system. I’ve had a few situations in my personal and professional life where it was beneficial to access a record of a previous conversation or activity to make it easier to follow up where we left off. However, as I had to admit, I’m still trying to figure out the value, and I’m collecting some data on the hunch that it may be useful in the future without clearly knowing why. Related to that question is how much time one should spend maintaining the CRM relative to its utility. I usually take a few minutes to note down conversations, so it’s not a huge burden. Still, adding new contacts sometimes takes a while, not just because of the CRM but also because of researching a person you met, looking at their website or social media profiles, and following up. If that’s too much effort, the solution is to filter who you want to add. It all boils down to your networking philosophy and your intentions. Do you wish to be a well-networked person that can eventually facilitate connections between other people, or are you just focusing on your most important contacts? It’s tough to assess your network’s value, though, because nothing comes out of most ties, whereas others might lead you to a perfect job/investment/dating opportunity. That was the unsatisfactory answer that I had to give to a follow-up question on the ROI (return-on-investment) of a Personal CRM. I also find it hard to pin-point a single use case or a personal success story for networking as a high-value activity.
Another question, which begs much more broadly than just for Personal CRM but for all software and services, is whether to use specialized or generalized tools. I like having structured data and technical features, like using WebDAV to sync contacts with my phone, but I’m very sympathetic to using things like Roam as a low-barrier way to get started. For those who use Notion, someone shared a great template in the chat. Monica’s downside compared to note-taking tools is that there’s no full-text search for notes, so finding people based on attributes that you haven’t explicitly set up as tags is hard. Roam or Notion win here.
Another participant asked about merging contacts and duplicates, which I consider one of Monica’s missing features. Nevertheless, if you add contacts manually instead of importing from multiple sources, you don’t get as many duplicates. Talking about import and export, yes, Monica allows that, but moving data between systems always involves some friction.
One crucial question was related to maintenance and purging old contacts from the system. My take on this is that the whole idea of a CRM is that you maintain everyone you met because that person may appear in your life again or prove valuable as a “weak tie”, and that’s where it’s worthwhile to have the record. The only reason to purge a contact is if it’s a business relationship covered under privacy regulation that gives the other person a right to be forgotten (do not take this paragraph as legal advice, though). Talking about privacy, I generally trust Monica’s developers to be protective of my data, as they don’t engage in any data-based or advertising-based business model. Still, there might be a security hole, so if you trust yourselves more to operate a secure server, you can always get their open-source edition and host yourself.
The final question was about managing and keeping track of conversations in different channels, especially fast-faced communications that don’t allow you to mark them unread again. There are multi-messenger browsers like Franz and open communication protocols with bridges like Matrix, or you could rely on old-fashioned email notifications. We agreed that this is an unsolved problem and that there might be some approaches that use APIs to integrate multiple channels with a Personal CRM, but there’s not a perfect solution for it yet.
Reaching the end of the second write-up, I want to thank again everybody who attended the session. To repeat the ending of the previous post, I have a few ideas for follow-up events. I may do a follow-up session that will not have a presentation to become a free-flow discussion. I could also imagine teaming up with someone as a co-host who uses a different tool and wants to present their setup. Also, I believe Personal CRM and networking involve many general, strategic, or philosophical questions besides tools. For that purpose, I may host an Interintellect salon to give the topic the mental space it deserves. Stay tuned to my blog and/or Twitter for specific announcements.
On Tuesday, I hosted a meetup on the subject of Personal CRM systems. I believe that digital tools can help us organize our growing social networks, and I’m using a software called Monica to do precisely that. I’ve also heard from other people who use Roam or Airtable to stay in touch with their contacts. While I diligently insert information into the system, I’m not sure that I already use it in the best and most efficient way.
For a while, I had this idea in mind of hosting a discussion about the topic. Still, I didn’t get around to organize one until I learned about the Creator Spark mini-accelerator that Anne-Laure LeCunff runs inside her Ness Labs community. In a nutshell, Anne-Laure encourages her members to run events within the group, i.e., lending them her audience. Afterward, members should publish a write-up about them to kick-start online creation and complete the accelerator. I hosted the event already, and today I’m posting the write-up.
Since I mostly write shorter posts on this blog, I’ve decided to focus only on my experience hosting the event and then write a second post after a few days centering on the subject matter. In other words, this is not a post about Personal CRM but a “meta” post about hosting virtual events. I’m not new to giving talks and demos, and I’ve previously MCed a virtual API the Docs meetup. However, this time was the first time I did it all on my own and not having a team to back me up.
I used luma to create an event signup page and shared it on the Ness Labs events and announcements forum nearly two weeks before the meetup. I tweeted about it once but didn’t do any additional promotion. Still, I got 78 signups. Of course, every free event has no-shows, but 38 attendees at the peak were almost twice the turnout that I expected, and I’m grateful for the vast interest in the subject. I guess it also shows the value of communities of like-minded people as a great way of gathering an audience. As a side note, the announcement post had a lot less likes and comments, which shows that most people on forums are lurkers.
As the event started, I had to split my attention between giving a welcome speech and handling the Zoom waiting room as more people arrived. I should probably have turned it off. On the other hand, that allowed Yina Huang to volunteer as my co-host. She didn’t just help me with the waiting room and managing attendees but also kept an eye on the chat and collected questions and feedback from the audience. I cannot stress the value of having a co-host for admin work enough, and I’m sending a big thanks to Yina!
I planned to use the first 15 minutes to introduce the topic and ask the crowd about their own CRM setup and their motivations for attending the event. Then, I wanted to give a Monica live demo to show the software itself and how I use it, taking probably another 15 minutes. Both went well and as planned.
For the second half of the one-hour event, I intended to have an open discussion about the motivations behind building a Personal CRM and alternative concepts, workflows, and tools. What I didn’t expect to happen was that this turned into a Q&A session with me that put me in the expert seat to answer the audience’s questions. Of course, I had given a presentation right before it, but I don’t perceive myself as a subject matter expert, and I ran the session not just to share what I’m doing but also to learn from others. Not to complain, but I slightly missed that goal.
What will happen next? First of all, I will publish a second write-up based on my presentation and the Q&A session, as there seems to be some value in sharing my setup. Then, I have a few ideas for follow-up events. One is merely repeating the event for those who couldn’t attend. Another is a follow-up session that will not have a presentation and be more of a free-flow discussion. I could also imagine teaming up with someone as a co-host who uses a different tool and wants to present their setup and take the expert seat next time. Finally, I believe Personal CRM and networking raise many general, strategic, or philosophical questions besides tools. For that purpose, I may host an Interintellect salon to give the topic the space of three hours that it deserves. Stay tuned to my blog and/or Twitter for specific announcements.
One of the reasons I love APIs is that they provide technology access and empower people to build products that they wouldn’t create otherwise. That includes people who don’t consider themselves developers but have some basic knowledge and can leverage APIs in low-code or no-code environments. I have voiced this sentiment previously on this blog and a 100-tweet-thread on Twitter.
Talking about Twitter: Vensy Krishna dragged me into a conversation started by Doc Williams. He was looking for an API introduction targeted at non-developers. I know that some API providers active in this area, such as Vonage who host a “low-code” hour with Julia Biro on their Twitch account (here’s an example recording. However, the fact that I couldn’t immediately name more resources may indicate a lack of such. I have previously created some internal material for a client who wanted to teach their employees how to use Postman as a non-developer and consume APIs in Microsoft Excel. On the public web, though, a quick Google search didn’t reveal much (granted, that may also be due to not using the right search terms). There are some high-level API explanations, and I found one more hands-on tutorial.
If we want to fulfill APIs’ vision, we probably need more developer content targeted at beginners and no-code and low-code users. It’s also an area in which I’d love to do more. However, I’m wondering about the crucial aspects and potential roadblocks of an API beginner’s journey. Therefore, I have decided to make a special offer: I will provide a one-on-one consulting/mentoring/co-working Zoom-call of 30 to 60 minutes to five aspiring API users who are coding beginners or working with no-code/low-code tools, free-of-charge. If you are in the target audience, this can be a great chance to get a head-start to build something or solve a problem you’re facing. Why am I doing this? Apart from providing a service to the community, I can get back into the beginner’s mind and learn what helps me improve the writing and API design I do for my clients and projects. So, it’s a win-win! I will also evaluate whether there’s a market for a paid mentoring/consulting offer or an info product in this area.
If you are interested in having a free session with me, please apply by sending me an email or a DM on Twitter, describing what you’re attempting to do and what issues you have. I will then send you a calendar link to schedule the session. If there are more interested applicants than I can serve, I will choose at my discretion. I am looking forward to hearing from you!
Yesterday’s post on “Exploration vs. Exploitation” was mostly inspired by my struggle with unlimited optionality and being over-inspired. I want to expand on these thoughts, but I recommend going back and reading the previous post, if you haven’t, before reading this.
My argument that communities are biased towards exploration, which makes them a double-edged sword for people who want to focus on exploitation, extends beyond communities. There’s a whole industry of people selling inspiration in the form of courses, blogs, newsletters, and podcasts. There’s no doubt enormous value in educating yourself, but how many people would have benefitted from trying, let’s say, a marketing strategy themselves instead of reading the hundredth take on what made others successful? There’s also great self-help books, but they wouldn’t nearly sell as many copies if people understood that they could not purchase aspirational goals off the shelf.
Somewhat ironically, the latest article from Ness Labs founder Anne-Laure LeCunff talks about scaling down and choosing quality over quantity, not over-ambitiously trying to do and experience more for the sake of it. Of course, even a focus on quality could make you stick in perpetual exploration and jumping away from your current commitments into seemingly higher-value opportunities whenever possible. That may be the right move sometimes, but again there’s tremendous value in being consistent with your goals and plans over time.
However, my main inspiration for this follow-up post was Michael Ashcroft’s tweet, who said he quit his job to have more time and headspace to engage with communities like Interintellect. Multiple replies from Interintellect members like Rick Benger or Vidhika Bansal echoed the sentiment. I see the value of working less to make space for individual pursuits and taking sabbaticals to figure out your next move and leverage communities to help with it. It’s also vital to connect with people and ideas outside your line of work and current comfort zone and have “white space” for thinking. Still, I can’t help but feel that these people might be falling into a trap. I could be wrong, of course, but I know how bad FOMO can be and that continuously chasing additional inspiration, input, and more options don’t make me happy. It doesn’t mean I have the feelings under control, but I know that I have to work towards it, and against the industry I mentioned before, who’s trying to sell me that inspiration. I feel like I should help others avoid the trap.
I’m slightly worried about posting this as it could come controversial and offensive to some. Still, another of my new year’s resolutions is trying to be bolder and more opinionated in the things I say, so I’ve decided to publish it nevertheless.
“Exploration” and “Exploitation” are two broad buckets for work-related activities and also for phases of our professional and personal lives. Exploration is about generalized learning, discovering opportunities, generating ideas, and playfully experimenting with them. In contrast, exploitation is about staying focused on implementing your vision and creating value based on what you know without getting distracted by the next shiny idea. These concepts work on different scales. For example, if you need to find an API or a tool for your work, you might spend a day researching and trying out other options and then implement the chosen one on the next day. On a broader scale, you may take a few weeks or months off to find a new career opportunity that you plan to stay in for a few years or even decades.
On any level, you need to find the right balance. There can be a huge benefit in using a fair amount of time to find the best option. On the other hand, sometimes exploration, learning, and research is merely procrastination by another name. You feel like not having enough information when the hidden truth is that you’re just not willing to make a choice, as that means saying “No” to other options. Overdosing on inspiration and serendipity can be a poison for productivity.
During the pandemic, I actively participated in the Ness Labs and Interintellect online communities, which gave me a lot of exposure to new ideas and people. I expressed gratitude for them in my first post this year. And while I am genuinely grateful for this experience, I have to look at them critically as well. Communities like these that cover broad or meta topics have a bias towards exploration. There’s a constant influx of new members, and many people join them at turning points in their life when they want to figure out what to do and need inspiration or when they need to implement a “restart” in a new career and learn new skills. In other words, the most active members are in the exploration phase, and that’s a potential distraction when you’re in an exploitation phase. Or worse, it creates the illusion that life is about perpetual exploration and infinite optionality, which it isn’t, at least not if you want to build something meaningful and innovative.
Exploration is a fun and seemingly low-risk activity. It is also a great way to connect with new people and keep an open mind, fulfilling our innate needs for human connection and intellectual stimulation at the same time. It can even be a high-value activity, but it can be low-value as well, and that makes it a risk if it takes time and energy away from higher-value activities. I am an introvert who realizes that socializing draws from the same energy reserves that I need for individual creative pursuits, requiring me to be especially mindful about it.
If you’ve read until here, you may expect an announcement that I’m leaving a community. I have no such plans, but I want to pay more attention to my interactions in 2021, as I have the intention to improve my focus, something with which I struggle.
Stepping away from digital media for some time can be incredibly helpful, and even though I realize that, I don’t do it quite often enough. I wrote about taking a #DigitalDetox a while ago, but it wasn’t something that became a regular part of my schedule. Still, stepping away helps with creativity, mindfulness, and introspection. It also helps in making time for off-screen activities, like reading actual books or observing my surroundings. The fact that I found myself “doomscrolling” instead of doing some yearly planning in the early days of 2021 and Taylor Reneau’s recent video “Why You Should Quit Social Media” have given me additional motivation to do this again. So, here’s my plan:
Following this schedule is my monthly goal for January. I’ll let you know how it worked.
Also, I’ll keep the Disable Twitter Feed add-on that I created for Firefox enabled on my computer. By the way, the same add-on is now available as a Chrome extension.
Perfectionism is a double-edged sword. The problem is that striving for perfection is not always appropriate. I touched on this earlier in my musings about “parallel focus”, where the key to having multiple priorities is knowing which of them need perfection and which don’t. My friend Mischa Hildebrand also has a good article about perfectionism, which I recommend if you want to dive deeper into the two sides of it. Today, I want to talk about one specific area where perfectionism may not just be unnecessary but an unattainable goal - organizing your digital creations and possessions.
Jim McGee, who I met in a Zoom breakout room in Anne-Laure LeCunff’s “Collector to Creator” course, wrote an article called “Embrace the mess if you want to do better knowledge work”. He reminds us of the argument between “neats and scruffies” that was part of early Artificial Intelligence research discourse and is coming up again in the knowledge management space. The “neat” philosophy believes in transparent, elegant, and orderly systems, whereas “scruffies” assume that the real world is inherently too messy for these systems, and it’s okay to hack your way into approximate solutions.
There’s a famous German figure of speech called “Ordnung ist das halbe Leben”. Its literal translation is “tidiness is one half of life”. Interestingly, Linguee provides “A tidy house, a tidy mind” as the English equivalent. On the other hand, if a cluttered desk was a sign of a cluttered mind, isn’t an empty desk a sign of an empty mind? Does creativity even demand a bit of chaos?
If you look at computing, you’ll see that neat structures adopted from the physical realm like files and folders are increasingly getting replaced or overlaid with things like tagging and full-text search. Knowledge work relies on networked thinking, which is incompatible with hierarchical structures. It also includes ideas that exist in different stages, some of which will never be fully-formed.
My point, and the one Jim McGee tried to make, is that the answer is: Yes, creative knowledge work relies on a certain level of chaos. Things will never be in perfect order. The sooner you accept that the happier and more productive you’ll be.
Proverbs like those I quoted earlier come from a time where the order was necessary because there were no devices that could help you make sense of it. We have thus learned that it is a value and virtue of its own. I still agree with physical objects, but I don’t think the same applies in the virtual world. The ability to find the data you need when you need it is more important than it being part of an elegant and consistent structure. The systems you design and implement to organize your life must optimize for the former, not the latter.
I tend to obsess over small details in the consistency of the data and information I collect, which aren’t necessarily valuable. I also feel that every unpolished thought and every information ever collected is a to-do item, which is equally wrong because some ideas that seemed important once are not worth following up. Sure, there might be joy in organizing and cleaning stuff, but that’s probably not where I create a lot of value. I fear that the belief in the “neat” philosophy is just the digital equivalent of “procrasti-cleaning”.
If I wanted to name one realization from the past year (although I’ve been thinking about it for much longer), it would be that. Building a perfect and clean system of thoughts isn’t a prerequisite for achieving something meaningful. And neither for being a happy and well-rounded person. It’s not that I necessarily spend a lot of time trying to build that system, but it’s that I feel like a failure for not doing so, even though it’s impossible. And I’m pretty sure that’s holding me back. One of my resolutions for the coming year is to try and be more lenient about this. As long as I am doing creative and intellectual work, my mind garden and its implementation won’t be a zen garden, and that’s okay.
Happy New Year! We just turned our calendars from 2020 to 2021, hoping that one of the worst years for many of us came to an end and whatever the next year brings will be better. Looking back on 2020 for myself, I have to acknowledge that I’m among the privileged few that were barely affected, at least professionally. Only one client didn’t extend a project for pandemic-related reasons, but I could quickly fill my time with other work. Outside of work, though, a lot of plans had to be adjusted, mainly travel-related. And all the social activities, both work-related like meetups and conferences, and personal, like board game nights, no longer took place. A lot of these moved online.
Spending even more time on the Internet than I did before this year, I became quite an active participant in online communities, mainly Ness Labs and Interintellect. Through them, I got to know many different people and participated in a variety of activities. To improve work productivity and motivation, I joined a weekly accountability group and regular virtual co-working sessions. I started tackling Hofstadter’s Gödel Escher Bach with a reading group. Outside of work and intellectual activities, I hosted my first two virtual werewolf game nights and had my first stab at trying D&D roleplaying. I also upped my note-taking game by diving into Roam Research, which has many fans in both communities. I’m very grateful for these fantastic groups, their founders, and all their great and lovely members. Sending a round of applause, or, if you consent, a big virtual hug!
When you’re testing an API, or really any kind of software, functional testing and performance testing are available. These two types of tests are not an either/or-choice, but adequate software quality assurance needs them both to cover different surface areas and requirements. My latest article for my client BlazeMeter is called “Functional Testing vs. Performance Testing and the Value of Using Both”. After comparing API testing and API monitoring in general, I took a deeper dive into testing now. I’m always happy to get feedback on my articles and I’m open to new technical writing contracts as well - please check out my Writing page.
Disclosure: This work was paid for by BlazeMeter.
Another API the Docs virtual meetup took place last night, the third one of the second season. Michael Meng, Lorna Mitchell, and Patrick Hammond shared their thoughts on API documentation. As for the first and second meetup in the season, I’ll provide a little personal recap.
Michael Meng, a professor at Merseburg university, talked about research-backed ways to improve API documentation. The key questions are, which information should you present, and how? Previous research indicated different strategies in the way developers access documentation. There is the opportunistic, or exploratory, strategy, and the systematic strategy where developers try to gain a broad understanding first (a pragmatic approach combines both). In general, they access documentation in a task-oriented manner, focused on code examples (which backs up nicely what Milecia McGregor said about code samples at a previous meetup). It’s also vital to explain underlying concepts, but best integrate them into use cases as developers often don’t read separate concept docs. Michael’s team created guidelines for enabling efficient access and facilitating initial entry into the API and then rewrote documentation for an existing API based on those guidelines. They invited 22 developers and asked them to complete a task. Half of the group got the original documentation. The other half got the optimized version. What I found interesting is that the group who got the optimized documentation performed more accurately, but only slightly faster. However, they did spend more time in the documentation, which indicates that good documentation motivates developers to understand first and then act where they would otherwise spend time in trial-and-error experimentation. Michael was careful about his study’s replicability and said there needs to be more research to disentangle different optimizations. The paper is available as open-access research.
Lorna Mitchell started her talk by quoting the Postman State of the API report, which maintains that the top issue with APIs is documentation, just as the research Michael mentioned. She said: “It’s not an API if it doesn’t have (reference) documentation.” I also liked how she compared various improvements to API documentation with a restaurant menu. Even though a customer doesn’t order everything at once, every menu item improves the whole thing. She mentioned a list of those improvements, with “Getting Started Content” being the first, reminding us that “every API is someone’s first”. Hence, you shouldn’t be afraid to go overboard in the documentation and make sure to link additional resources. It seems obvious, but also Adam DuVander said many companies don’t have a “Getting Started” guide. Examples are “worth many words”, and OpenAPI helps. Lorna also explained their docs-as-code setup where they use separate standalone files included in the docs through custom wiring (again, the approach that Milecia suggested as well). Their code snippets are parts of longer files with full examples stored on GitHub.
Lorna mentioned another type of content: “HowTo: X with Y” guides, where X is a common task, and Y is a tech stack. They can be blog-type content but also part of documentation and should be end-to-end guides. If developers use them and some read nothing else, they should be fine. Along with those go demo apps, where you should mix up different tech stacks. I was happy she mentioned these two types of content as I enjoy creating those for my clients. Finally, she included troubleshooting guides (which people can find searching for error messages) and recommendations of related tools (that the company uses internally but can also help API consumers). One of these tools is Postman, and Lorna added that releasing Postman collections provides additional value, even if Postman can import OpenAPI. Also, SDKs are helpful, even if they are just a thin layer over the API. However, only ship what you can support! Lorna recently wrote an article on SDKs. Also, check out my summary of an interview with Lorna if you’re looking for more nuggets of API-related wisdom from her.
The third talk was by Patrick Hammond, who explained the docs-as-code/DocOps approach at Adyen. Sadly I had to leave halfway through the presentation for another meeting, so, unfortunately, I can’t provide you a summary this time.
API testing and API monitoring are vital parts of a successful API program, just like API design and API documentation. However, what is the difference between testing and monitoring, considering some overlap in approach and tooling? My take on this is that testing is primarily a part of building APIs, whereas monitoring is mainly about running APIs in production. I published the extended version of my comparison as a new article on the BlazeMeter blog, called “API Testing and API Monitoring: The Complete Guide”. I’m happy to continue my previous partnership with their company to explore and write about API life cycle topics. You can find additional articles I wrote for them and other clients on my Writing page, and I’m open to new writing contracts as well.
Disclosure: This work was paid for by BlazeMeter.
Releasing an API without any authentication is often a bad idea, but managing users and API keys is too much effort for smaller APIs, for example, for side projects. However, CloudObjects has a method to distribute shared secrets between domains. You can leverage it for API authentication. How? I have written a tutorial-style article where I explain shared secrets and give a practical example of how you can implement them in an API. You can read my post on adding lightweight authentication to your API with CloudObjects shared secrets on the CloudObjects blog.
The second episode of the second season of the API the Docs virtual meetup series was all about API Design First, a topic that’s very dear to me. The two speakers of the evening, Ivana Isadora Devcic and Jeremy Glassenberg, approached the subject from different angles.
Ivana, a translator and technical writer who recently joined Redocly, talked about advocating for the API Design First approach. She reiterated that it helps with collaboration, getting early feedback, and automation, emphasizing that it unblocks technical writers who can get involved sooner in the process. The extraordinary thing about her talk is that she framed the API advocate as the hero of a role-playing-game and followed that theme in her slides, providing different items that help the hero fulfill their quest. API design is a business problem, not a documentation problem. You can sell it to management using “magic words” while educating your peers by showing them available tools. You should take the role of a leader but empathize with those who don’t immediately jump on the bandwagon. Ivana said that things can still go wrong, for example, due to bad timing and communication, citing her previous company as an example, which is a refreshingly honest approach. It’s good that we are becoming more able to talk about failure, as seen in events like “fuck up nights”.
Jeremy took the Silicon Valley perspective and started by talking about investors. The VC (venture capital) community is becoming increasingly interested in companies having APIs and those building the tools around the API lifecycle. Next, Jeremy talked about the history of APIs. A decade ago, REST started to take over from SOAP, but tooling was terrible, so APIs weren’t that good either. There was WADL, but many developers didn’t like XML. APIs became better and more popular as JSON replaced XML, and the first version of Swagger (eventually becoming OpenAPI) entered the stage, enabling a platform for additional tooling. The first tools focused on autogenerating APIs, causing developers to ship their database schema as an API. However, that wasn’t enough to convince people to use these APIs, so we had to think of APIs as products, and the role of the API product manager emerged. Jeremy showed various types of tools, making the distinction between those that generate OpenAPI (like IDEs) and those that use it, either for building (API gateways and server stub generation) or for developer experience (API documentation, developer portals, SDKs and mocks). We should think of these tools as a tech stack. He ended his talk by hinting at future opportunities, including CRUD endpoint autogeneration from models, enhanced visual IDEs, app marketplace frameworks, and more sophisticated back-end generation. Another exciting concept he mentioned was the integration of API tools (especially monitoring) with customer support, evolving CRM (customer relationship management) into DRM (developer relationship management).
Altogether, both talks have mentioned excellent cases of APIs’ potential when we apply API Design First and build automation, a point that Josh Ponelat and I also try to make in our book “Designing APIs with Swagger and OpenAPI”.
You can also read my recap of the first API the Docs event of the second season.
“System change, not climate change” is one of the banners you can typically see at a Fridays for Future strike. I’m not a fan of that slogan, because while “not climate change” is something we should all agree upon, there’s no further definition of what “system change” entails. It leaves room for interpretation. What is the “system”? Do these young people want to abolish democracy to establish a “climate dictatorship”, as some right-wingers claim?
There’s another banner I’ve seen at climate protests: “Burn capitalism, not coal.” Again, I think we can agree on “not coal”, but why “Burn capitalism”? And probably capitalism is what they meant by the word “system” on their previous banner.
Of course, I’m fully aware that slogans have to be short and to the point. However, it reminds me of something that has been on my mind quite often lately. It is a problem for the discussions in society as we talk about ways to avert the climate crisis and effectively solve other issues, for example, around social justice.
Friday night, Luisa Neubauer, one of the Fridays for Future movement’s leaders and public figures, was on German public television in the ZDF show Aspekte. Being asked about system change, she said that we have to get away from “the dichotomy of capitalism and socialism”. That’s precisely what I’ve been thinking, too! Instead, she argued, we have to design an economic system compatible with the Paris agreement’s climate targets, but it’s not her expertise to describe or even name that system. It’s also noteworthy that she never said anything against capitalism per se but always qualified it as “fossil capitalism” or “this capitalism”, which is a good start.
Many people speaking out in favor of capitalism often argue that we have a choice between either what we have right now (or an even more neoliberal version of it) or the failure that was Soviet-style state socialism. Since nobody wants the latter, we can’t mess around with the system.
On the other hand, people use capitalism as a one-word explanation for everything they deem unfair or wrong in society, a system designed around exploiting people and the planet for the sole benefit of a few rich people.
I don’t want to go too deep into it right now, but if you look at studies and statistics around human progress, the world tends to get better. For example, we have improved health and education and reduced poverty around the world. In most metrics except for CO2 levels in the atmosphere, things look optimistic, but the latter could ruin everything else. I’d say it’s tough to argue that the positive developments have happened despite instead of because of our capitalist economy. I personally believe in markets and the power of entrepreneurship as a motor for innovation. However, I don’t believe in unlimited growth, monopolies, and extreme inequality. We have to adapt our economy to reap the benefits and mitigate the downsides of capitalism, for example, through regulation and redefining our goals for success outside of GDP growth.
Just like Luisa, I don’t claim I have the solution. I’m not a subject matter expert, only a curious software developer and IT entrepreneur cosplaying as a public intellectual. However, the one thing I’m confident about is that we won’t redesign our economy for the 21st century if we continue arguing between capitalism and socialism.
Milecia talked about why technical documentation for APIs and developer products matters. She emphasized that code snippets in documents are of utmost importance because many developers are primarily looking for these. They don’t want to read all prose in detail and copy and paste examples instead. Hence, you lose some of your developers if the snippets don’t work, and if they have lousy quality, it reflects on your overall product. Milecia had an interesting suggestion to assure the quality of your code snippets. First, you separate them from your docs. If you’re using docs-as-code, don’t use inline code blocks but add references instead. She showed an example in Gatsy, which supports including the samples. Once you separate them into individual code files, you can write unit tests and run them as part of your CI pipeline.
Louis talked about audience segmentation for developer portals, emphasizing that “developers” is too broad of a term to describe your audience accurately. He suggested creating various personas, which can industry-specific. Create a one-pager defining each persona, even including information that doesn’t seem immediately relevant, to make them good fictional characters. You can brainstorm with your team in creating the personas and, once done, distribute them internally and use them whenever you create content. Louis showed a practical example, including one developer persona that reflected the exact copy-paster-type that Milecia described in her talk.
Both speakers, but Milecia in particular, made the point that I also make a lot, that developer content, and especially technical developer content with code appropriate for your audience, is vital to run a successful API program developer portal. It’s an excellent opportunity to remind you that I also offer consulting, development, and technical writing services to assist companies with this kind of content. Please contact me to learn more.
Also, if you’re interested in future API the Docs events, you can join them for free, thanks to the sponsors, but you have to sign up here.
Before the pandemic started, I used to run board game meetups frequently. One of the highlights of those gaming nights was a party game called “Werewolves”, which some of you may also know as “Mafia”. I often led sessions as a narrator. When Anna Gát of The Interintellect wanted to run a virtual gaming night on Zoom, I quickly volunteered for that. I mostly based my approach towards implementing a virtual game on Anjuan Simmons’ “How to Play Werewolf Over Zoom” guide, but a day before it, I decided I had to add some code, API, and no-code stuff to it. Here’s a quick high-level overview of how I did it.
First, I created a new base in Airtable and a table for the game. Inside the table, every player gets a row. I added several columns for the characters, elimination status, and free-text fields for notes that I could take during the game to assist with the narration (for example, whether the Witch has used her potions). With Airtable’s grouping feature, I arranged the view to list villagers and werewolves separately and hide eliminated players to remove clutter. Another benefit of Airtable is that after the game, I could share a private link to the table so players can see what happened.
Then, I wrote some custom PHP code as a phpMAE class for two purposes. One is to assign characters randomly. The function takes a list of role cards, fills up the deck’s remainder with regular villagers, shuffles it, and updates every row in Airtable with the card’s character. While I did this with PHP due to personal preference (and to “selfdogfood” phpMAE), I think this is also a great use case to build with the new Airtable Apps they announced lately.
The second purpose is player registration and role reveal. Using phpMAE and Twig templates, I created a minimalist HTML website for players to enter their names. The PHP code calls Airtable’s API and adds a row for the player, returning the ID for the created record and a secure hash to the frontend. After I announce that I have dealt the cards, players can click a button on the website. If the hash is valid, it fetches their player record from Airtable and displays their role without revealing additional information. You can see the source code for both here, but it partly relies on undocumented or invite-only phpMAE and CloudObjects features. Contact me if you’re interested in those.
Most interactions throughout the game occur on Zoom voice chat, and communication with particular roles during the night uses private messages. For the werewolves, I created a separate group chat to interact in ways that Zoom doesn’t allow. For this game, we used Interintellect’s Mattermost instance, but any group chat tool works. When it comes to voting at the end of the day phase, I asked everyone to paste their decision in the public chat and hit send at once. However, counting the votes was the most tedious task of the narration, so if I add any additional gameplay features to my custom app, it would probably be voting.
It was not just the first time I narrated a werewolves game over Zoom but also the first time I did so in English (instead of my native language, German). Therefore, I also spent some preparation time writing a script with how and when I wanted to explain everything. Its primary purpose was not to forget to call anyone. I even flexed my creative muscles and added some color to the narration. All in all, running this game was a great experience that let me combine many things I enjoy, and I’ll probably do it again.
Airtable, the spreadsheet-database-hybrid and fan favorite of the no-code community, has announced a $185M VC funding round and a set of new features. I’m often concerned about large funding rounds. If a VC-driven company doesn’t live up to their hype, they either fold or end up in a larger tech giant’s portfolio. In the case of Airtable, however, I strongly believe in the product and its potential. I have used Airtable in a client project before to replace a home-grown CRM. It’s part of the phpMAE-driven email handling setup I mentioned in my last post. In another current project, most non-personal data resides in Airtable so that their interface can act as an admin interface, saving implementation time for internal tooling.
fetch(), which means you can already integrate with everything that has an API.
The third feature is Sync and, as far as I understood it, allows mirroring data between different bases in Airtable. I won’t go into more detail here.
With the combination of Apps and Automations, Airtable fits perfectly into a product development philosophy of minimum coding, or an efficiencer mindset. It shows that developing applications with code and a no-code approach aren’t at odds. First, you start with existing tools and try to map your workflows in them. Then, build iPaaS-style no-code integrations to connect the tools for more advanced workflows. Then, once you reach that stage, write custom code to extend your tools with plugins and set up advanced integrations.
One of the reasons I’m excited about APIs is their role as a bridge between the worlds of software development and no-code app building. I believe this will become increasingly important, and we’re not talking about it enough yet. It will have implications for many stakeholders, including business owners, software engineers, API designers, and technical writers. I’m still searching for ways to understand these developments and articulate my understanding. Every post on this blog is a step in that direction.
I wanted to follow up on my last post about “serial focus” and “parallel focus” by expanding on the idea that doing multiple things doesn’t mean you can do everything, and you can’t approach everything with full-scale perfectionism.
Yes, you can be the person who runs two companies at once. Still, you probably can’t be the person who runs two companies at once, has a perfectly tidy house, cooks excellent meals from scratch every day, and never forgets a single birthday of an acquaintance or family member. And if you believe that it’s important to remember birthdays, you reasonably send your contacts a text message instead of a hand-drawn postcard. And it’s okay. You have chosen the path of the entrepreneur, and it comes with trade-offs. Of course, that applies to every other set of priorities. You may value your personal life and hobbies over your career, and that’s also okay.
The problem is that we see high achievers in the press and on social media, and we believe they’re perfect in every way, but every successful person probably has at least one area in their life at which they suck. However, they likely have people who have their back to provide the perfect appearance, or they communicate only their strengths while hiding their weaknesses.
There’s another aspect to it. I came across a tweet from Tiago of Forte Labs. He tweeted: “I really value conforming in most areas of work and life, so that in the few you don’t, you can create something truly new and beautiful. If you try to innovate on everything, you end up innovating on nothing”.
That tweet hit me because it’s related to perfectionism for me. I often feel it as the need to do things differently. For example, I have a set of custom-coded phpMAE classes that handle incoming email. But I’m not running an email service. Email is one of the things that should work so I can communicate with clients, business partners, and friends. Of course, experimenting and innovation are excellent, and using phpMAE for this is “selfdogfooding”. It still means I sometimes have to debug code when I just want to read an email. One related area where I’ve made the other choice is to use a micro.blog-hosted blog instead of rolling my own.
More generally, and to return to the high achiever from above, they are presumably quite dull in many areas of their life. Unless they are an eccentric millionaire celebrity, they probably live in a regular house, have a normal relationship and family, and buy and use the same items and tools as the rest of us (or their premium versions). The backdrop of everyday life allows them to make their achievements. It’s something worth thinking about more often.
It’s time to make an announcement that I’ve been holding back for a while: I’m working on a book! The name of the book is “Designing APIs with Swagger and OpenAPI”. I’m co-authoring the book with Josh Ponelat, a developer for SmartBear software, the maintainers of the Swagger suite of OpenAPI tools. Manning Publications release the book, and it’s already available as a live preview on MEAP, the Manning Early Access Program.
As I joined the project as a co-author later when Josh had already worked on and published some chapters individually, I wanted to wait to announce my co-authorship until Manning added the first of my work to MEAP. They did it last week, so I’m now happy to make this post.
I’ve done a bit of technical writing for clients and my projects and blogs, and I work on API documentation as a freelancer, but all of that is short-form writing such as articles and tutorials. A technical book is a challenge on another level because you have to have an overarching idea of the material that you want to teach and then plan how to present the material. It’s an excellent opportunity to learn and improve as a writer and experience a professional publishing process. I gladly accepted that challenge when Manning contacted me and asked me if I wish to join the project.
The book is for everyone who wants to get into designing APIs. The first part of the book explains the basics of APIs and the OpenAPI specification. The second part, which we’ve started to publish now, walks through an API Design First web application project with a fictional development team. Together we’re going from idea collection through domain modeling and user stories to a well-designed API in CRUD style that connects frontend and backend of the web application. We’re also exploring the ways to implement this design as code and the challenges along the way. The third part of the book will extend and scale this project’s API, and the fourth part covers various advanced OpenAPI and API life cycle topics. Josh and I are eagerly working on these parts, and we’re looking forward to delivering the full book to you as soon as possible.
You can preorder the book “Designing APIs with Swagger and OpenAPI” on Manning’s website now, get immediate access to MEAP and receive a full ebook or physical book later.