Universal Basic Income (UBI) is the idea that every citizen should receive a monthly sum of money with no strings attached, regardless of other income sources. The idea isn’t exactly new, and it has supporters and opponents anywhere on the political spectrum. It also featured prominently during the pandemic. So far, no country has implemented it, but there are a variety of experiments. None of these reflect the universality of a basic income, but they’re helpful nonetheless. I hosted an Interintellect salon - my debut as a solo host after my Personal CRM salon co-hosted with Vajresh Balaji - to discuss the idea with fellow curious minds.
As is usual with salons, I asked an intro question, which was: “Who do you think would benefit from UBI?” We talked about cash transfers for low-income countries through charities like GiveDirectly, an approach popular in the Effective Altruism community. We also mentioned creative and innovative people in rich countries who may not currently have the freedom to invent or express their creativity as they’re stuck in their jobs. It reminded me of the description of basic income as “venture capital for the people”.
How high should basic income be? Public discussion centers around round numbers like $1000/month or a minimum livable wage equivalent. An alternative would be defining it as the percentage of the average or median income. The definition of what a minimum livable wage is may change, so tying it to existing wages avoids the discussion. Another idea is to look at current government spending per person and pay it out directly. The latter leads to another question, whose answer seems to depend on whether you’re more on the left side of the political spectrum or more libertarian. Which public services can and should basic income replace? Should we even see it as a replacement or more as an add-on to the current services? While large infrastructure projects such as flood defense should probably remain with the government, they could privatize communal services like swimming pools. Of course, it’s too early to propose anything specific, so we didn’t spend a lot of time discussing this point. There should be more research first.
If there was a way to implement basic income on a global scale, it could give people additional opportunities to move around the world and find the life that fits them. Even though it’s a fascinating idea, it’s probably even further away than national basic income. There are, however, exciting approaches for voluntary funded basic income that doesn’t stop at national borders. Most use blockchain and cryptocurrencies. Examples include Circles and GoodDollar. We’re not yet fully convinced, especially since these often create custom coins that don’t have serious trade value, so they need a lot of trust and buy-in into their currency first. How far can voluntary approaches go anyway, in terms of funding basic income or other worthy causes? High-income countries and businesses could do more to drive people to give to charity, for example, by offering benefits in exchange for (zero-knowledge) proofs of donation. They could also give people more say in where their tax dollars go, although that may be unfair and undemocratic when it gives high-income individuals more influence on the state’s budget.
A common criticism against basic income is that it’s people’s fault when they’re poor. Therefore, we shouldn’t give to “undeserving” people. However, we believe that poverty is mostly the cause of bad decisions, not its outcome. We should also look at the future where society benefits when we allow people to recover and grow. Another point of criticism is that, because basic income is a substantial money redistribution machine, it gives too much power to the state. The government might eventually use that as an excuse to increase demands on their citizens. Asking how basic income influences the job market, people are forced to take any job to survive without it. As a result, it currently creates pay rates below market rates, leading to an unfair market. That would change.
Our last point of discussion was whether technological unemployment would become so common that it’s a solid argument to make basic income necessary? We’re unsure. On the one hand, there is no precedence for new technologies destroying more jobs than they create. On the other hand, it’s much more likely now, primarily due to the differences between manual work and knowledge work.
Overall, the salon was a good discussion and exchange of ideas and thoughts. I’m looking forward to continuing the conversation some other time.
Racket is an exciting new social audio platform. Unlike other recently hyped real-time social audio apps such as Clubhouse, which Twitter copied with its Spaces product, Racket is a fresh take on podcasting. If you wanted to make an “X for Y” pitch for the product, you could call it Twitter for podcasting. Twitter is micro-blogging, and Racket is micro-casting. Every podcast episode, if you even want to call it that, on Racket has a limit of nine minutes. That makes them great to listen to during a short break. They don’t require the time commitment to listen to an hour-long podcast. Recording on Racket is an excellent exercise in bringing your message across in a world with short attention spans, as the medium forces you to be concise with your spoken word.
I have shared my thoughts about Racket and audio as a medium in my first solo recording and a conversation with my friend Clo. And that brings me to the second advantage of the platform. It makes recording podcasts with multiple people as easy as it can be. You can record directly on their website with the studio feature, and you can share the URL to that studio page with anyone. When they go to that page, and you approve them, you’re immediately connected. First, you can have an unrecorded conversation to get ready. Then, the studio owner hits the Record button, and the recording starts.
At the end of the recording, your podcast episode goes live immediately. If you recorded with two or more people, it appears on everyone’s profile. The latter feature improves discovery because people following just one of the participants can discover another person and their profile from this recording. It also solves the use case that some people have voiced about finding and listening to interviews with the same person on different podcasts. Of course, it works just within the walled garden that is Racket and not throughout the whole decentralized podcast ecosystem, but it’s a start.
Even though Racket takes out the complexity of recording conversations and interviews, you still have to schedule time for them. That’s where another appealing feature comes in: “Ask me anything”. Every Racket user has an AMA page where others can record a question for them. The user can then decide that they want to answer. Racket stitches question and answer together into one recording. Here’s my AMA page, and here’s the first question I received and the answer I’ve given. There’s also a related feature called “Volley” where multiple people can answer the same question, but I haven’t tried that and won’t comment on it.
My main concern with the platform right now is that I don’t see a business model yet. Will there be pre-roll ads or subscription fees? There’s no information yet, and a conversation I had with Stu from Racket wasn’t reassuring. I’m generally enthusiastic about new social media platforms (even centralized ones) because they stir things up and provide new means of expression outside the existing platforms like Twitter and Facebook. Without a sustainable business model, though, there’s always the chance that the company will get acquired (and listed on “Our Incredible Journey”), and their network ends up as a feature of a larger platform that boosts its dominant position that way. Although, to be fair, acquisitions happen even for companies that have found their product-market fit and are profitable, so that’s always a risk when you put time into a social network.
Mishka Orakzai is the founder of thiscodeWorks, a Pinterest-inspired website for developers to share snippets of code. Lately, she hosted an Interintellect salon about coding to discuss the strong push towards learning to code. That coding literacy movement includes, for example, coding boot camps and events like Hour of Code. In our conversation at the salon, we took a step back first and tried to establish the meaning of coding literacy.
One way to describe coding literacy is thinking of it as a spectrum, with no-code being the low floor and advanced software engineering the high ceiling. The first and foremost goal is to demystify computing and develop a judgment of what’s even possible. Also, coding is a way of thinking, which I like to describe as algorithmic (or computational) thinking: being specific enough in your instructions to a dumb machine. Computers are deterministic and cannot understand ambiguity like humans. It’s possible to establish this mindset with a bit of self-taught coding without becoming a developer yourself. One participant mentioned he’s doing a “coder dojo” with his 10- and 12-year old kids. Even “toy programming” (think Roblox and Scratch) is still “real programming”, which makes it exciting, especially compared to other forms of building.
We talked about the education system as well. Compared to other subjects, high school computer science is relatively young, and the way it’s taught isn’t always good and sometimes doesn’t even cover coding. It may explain why few kids are excited about coding. On the other hand, maybe we’re expecting too much. Most children learn to pass tests and not because they’re passionate about every subject and want to continue learning in their free time. And nobody should feel guilty about not wanting to code. A more project-based way of teaching could improve education, though.
What’s the benefit of coding? Is the coding literacy movement’s purpose solely filling the demands of the growing tech sector? While that’s possibly true, coding can have additional benefits even when you don’t become a developer. For example, people in marketing can benefit from HTML knowledge. Again, the way of thinking can help in various ways. In the API sector, which is my primary field of work, there’s a lot of conversation about making the technical capabilities of APIs accessible to non-developers and more mainstream (lovely quote: “business developers are developers, too”). These capabilities can go beyond what the API provider intended. Coding can be a creative tool to unlock new possibilities (think of using a cup as a paperweight instead of a cup). However, it’s not the only one.
People like to have a creative outlet. It can be coding, sometimes it’s something else like homemaking, and for others, it’s creating TikTok videos. Sometimes we tend to think that previous generations were more creative, and our modern devices (like the iPad) are primarily consumption machines. For us nerds, it’s often the nostalgia of 90s websites. It’s important to remember, though, that in any community, it’s always few who create for a majority of consumers (look at the 90-9-1 rule). We believe that coding is an excellent outlet for creative building because you don’t need physical tools and material, driving the marginal costs to zero. That makes it accessible. Builders can avert the downside of non-tangible results with hybrid forms where digital things manifest physically, for example, through 3D printing.
Going beyond coding, Mishka had Marc Andreesen’s article “It’s time to build” on her reading list for the salon. Andreesen complains about a lack of desire to build stuff to solve problems in the world. We believe that there’s certain laziness and comfort in the Western world, and we make things for sufficiency rather than resilience. COVID-19 was a good wake-up call. Countries like Israel who are in a perpetual crisis mode were more capable of handling the pandemic than the West who’s invested in the good-enough status quo. Some people may have thought of themselves and their country as limited in the developing world, but remote work, often including coding, helps them grow out of that.
At the end of the salon, we discussed whether coding would remain an in-demand skill. We believe that digital transformation will change everything. No-code automation may make coding less critical, but related roles like user experience or management are growing. With artificially intelligent systems, new skills will become necessary. One participant described coming up with good prompts for GPT-3 as a coding-adjacent skill but more like writing magic spells. Interdisciplinary thinking becomes increasingly important, and the mindset learned through coding can help combine things and assist in learning other skills.
In summary, coding remains an excellent skill to have, but it’s not the most critical skill. Building the future is more than building apps. However, the coding literacy movement could provide a good blueprint for other fields to teach their skillset to a broader public.
Dominic Duffin’s recent Interintellect salon had the title “Time versus Space: The Geographies of a Digital World”. After having a good time at Dominic’s previous salon about our spaces on the Internet, which I summarized on my blog, I wanted to participate in this follow-up conversation. Once again, it was a smaller group of participants, which I found astonishing, considering how important the topic is, in my opinion. The pandemic has driven us to spend more time in digital spaces. As the world, or at least parts of it, slowly return to normal, it will be fascinating to observe the next transition.
Before writing about the salon, I want to mention another conversation I recently had with members from different effective altruism local groups in the GSA/DACH region. Group events had moved online with COVID-19, and most members can’t wait to meet in person again. On the other hand, there are certain benefits to virtual meetups. You don’t have to find a space, you save time going there, and it’s much easier to bring in guests and speakers from different places. The theory is that interest-based groups will eventually operate in a hybrid model, with events focused on working and learning happening online and social get-togethers happening offline. We see that happen with Interintellect as well. Most topic-based salons and series are still online, and the first IRL meetups are less topic-bound and more social. Since some salons are very niche, it may be hard to find enough interested participants in a single location, and you’d lose the benefits of international exchange.
Now back to Dominic’s salon on virtual geographies. His intro question was: “How relevant are your physical location and your timezone to your online life?” Timezones are the big differentiator and remind us that we don’t live in a single global village but on a round planet, even online. A participant from the US west coast remarked that the big political news of the day has always already happened by the time he wakes up. However, timezones can be an advantage, too, by distributing work shifts around the globe and providing 24/7 support even in a small team with everyone having regular workdays. Big global business used to be 24/7 for a while, and now it seems that it’s happening for all, leaving us to wonder why stock markets still have opening hours.
Even though the salon description used the analogy of a city where many activities happened, interestingly, most of our discussion at the salon focused on remote work. The pandemic has accelerated the information age. The upcoming significant difference after remote, on-site, and hybrid work is synchronous versus asynchronous work. Not every company can work in either model, but it can have vast advantages to implement the asynchronous model. Pieter Levels described the benefits for individuals in one of his articles, and we talked about hand-off between different timezones, which suits the asynchronous model well. It requires other tools and a distinct skillset, mainly writing. That leads us to the next topic, language.
Regarding languages, a participant from India gave us fascinating insights into their country. India has many local languages, and people are proud and protective of their native tongue. That makes it difficult to establish a shared Indian identity, for example, when the prime minister gives speeches in Hindi, a language that not all of his citizens understand. English is the standard business language in metropolitan cities, but language creates a division outside of them. As India’s relevance as a market for international companies grows, they’re increasingly localizing their products in Indian languages instead of just English.
Culture is another crucial aspect. For those spending a lot of time online, the global Internet culture can override local culture for the individual, especially younger generations. It can also influence local culture in general. Currently, global Internet culture’s strongest influences come from the US, but that’s changing as more people from other countries appear online. That change comes from countries with large English-speaking populations, though, like India and Nigeria. So far, we don’t see any attempts from China to push Chinese culture into global culture. They appear more focused on isolating themselves.
Is the Internet a single digital megacity or multiple cities? While there are overlapping spheres, filter bubbles are a real thing. The Internet influences what happens offline, for example, when a Facebook post causes people to form violent mobs in the real world. The division itself isn’t an online thing, though. In the US, self-division happens, and people choose to live in either conservative or liberal areas. How important is it to have diversity, though? Just bringing in different people is not sufficient. They also have to be willing to listen to each other. Something you always have to be aware of is that the loudest voices aren’t necessarily representative.
Later in the salon, we went back to COVID-19 and how it will change things. We believe that the “genie is out of the bottle” for remote work, and nobody can put it back in. There will be more options and more flexibility. However, remote work may affect those who can’t work remotely as well. If white-collar work happens remotely within the same organization, whereas blue-collar work happens on-site, it can create a divide between these groups. However, if we’re honest, often this divide already exists. Outside of work, we believe that arts and culture will go back to taking place in the real world, but movie theaters may no longer be the only place for the first screening of a new movie.
One participant mentioned that he wouldn’t have joined Interintellect salons offline. The online events allow for a broader range of backgrounds and viewpoints, and some conversations and connections probably wouldn’t have happened outside the Internet. However, there is still some division between digital natives and those who feel less comfortable using digital technologies.
At the end of the salon, we briefly mentioned relevant topics that we didn’t touch. Remote worker compensation and digital tools in government are just two of them. Maybe Dominic will host another salon for them. For now, he has planned “Digital Collectibles: Ownership and Scarcity; Infinity and Ephemerality?”.
Browsers restrict API requests to the same origin domain. CORS, or cross-origin-resource-sharing, is a method to overcome this restriction in a well-defined manner. If you’re on the receiving end of a CORS request, or, in other words, if you want your API to receive requests from different origins, you need to configure CORS in your web application framework. Assuming your framework is Laravel, you can read my introduction piece, “Laravel CORS Guide: What It Is and How to Enable It”, which I wrote as a guest post for the StackHawk blog (my first for them!). In it, I cover what CORS is, whether you need it, whether Laravel is the right place to control it (e.g., instead of a reverse proxy), and where to enable it in different versions of the framework. My emphasis is on minimizing the exposed surface. Check out the article now.
Disclosure: This work was paid for by StackHawk.
Interintellect member Dominic Duffin hosted his first salon. The topic was “Our Spaces on the Internet: Personal Websites and Social Media”. I was curious about this discussion, considering my engagement in various social networking apps, communities, and the IndieWeb. We started the salon, one of the smaller ones, by sharing our online spaces. Some of us had websites. Others were active social media users, and some just curious.
Within the group, there seemed to be a trend towards a unification of our online identity. One participant mentioned two websites, another had three Twitter accounts, but they want to combine them. I’m not sure if this trend is general, but people are willing to show a more holistic image instead of limiting them to one aspect. Undoubtedly, the Interintellect, with its emphasis on multifaceted people and interdisciplinary thinking, is to blame.
However, the ability to bring your whole self to the Internet is a privilege and depends on your risk budget. For example, you need to decide whether or not to show less proud parts of your past. There is a cultural difference in how much, for example, employers are will to accept. Also, you’re less likely to experience adverse effects from your non-professional online activities in an in-demand industry.
In other parts, the online presence became more sanitized, more corporate, with people trying to establish a professional identity. That is in stark contrast with the Internet of the 90ies which was a wild west that had no professional aspects for most people. Of course, people still build purely personal websites, but they are comparatively rare. Enormous social media companies, now turned cultural forces, drove standardization of online representation. However, can Facebook and Instagram represent us? And should Silicon Valley have that much power?
The IndieWeb and decentralized social networks like Mastodon can be a solution. However, it’s almost impossible to avoid mainstream social media in some professions and industries, so you have to use them even if you don’t love them. And there’s value in them for networking because they provide additional context compared to, let’s say, a cold email when reaching out to people. Next, you can leverage these networks and funnel your audience into a place you control. The IndieWeb community, for example, promotes POSSE: Publish On (Your) Own Site, Syndicate Elsewhere.
When it comes to the spaces under our control, we talked about building websites that are fun to explore and feel like the person they represent but are still cohesive. It’s nice to put some fun elements and show off what you can do. However, that begs the question of how website building skills create a divide between those who have them and the rest. Hiring a developer doesn’t seem to have a good track record. Doing it yourself using no-code tools like Squarespace and WordPress seems to be better. It’s also crucial to only build what you can maintain. Otherwise, your website becomes stale.
Our personal spaces also suffer from decreasing attention spans and instant gratification from social media. Asking our audiences to jump from a social media app to our websites can already be too much friction. That’s an unsolved problem.
Finally, we talked about real names and pseudonyms. The loss of pseudo-anonymity has been a massive issue with the expectation of using real names online in public spaces. That’s why the cozy web, the parts of our online lives hidden from the public, is growing as well. To explain the naming shift, I suggested a model of three generations. The first is online-only, a parallel world where the first nerds interacted solely through pseudonyms - from early BBS to IRC. The second generation is offline-first, where online spaces primarily represent our offline social circles - think Facebook. The third generation is hybrid communities, where people virtually interact under their real identities and may eventually meet in the real world. Online and offline is no longer a different sphere but just two different modes of interaction.
Dominic may be following up with other salons on related topics, so make sure you stay tuned to the Interintellect.
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.