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.
In my last post, I wrote about micro focus and macro focus, and how I feel I’m good at micro but bad at macro focus, whereas I observed the opposite in many people. Today I want to follow up and share another observation that is related to macro focus. I call it “serial focus” and “parallel focus”, for lack of better terms (if you have any, please share).
Some people have this one big idea, the main thing about their life. They have figured out their macro focus. Other people have multiple ambitious plans, but they apply serial focus, which means they focus on one thing at a time. The serial entrepreneur is the most famous example. These people pour all their expertise and dedication into an idea and either make it successful or find the right point to pivot or give up and change their focus. Once a project has reached a certain level of success, they sell it and start the next venture. Of course, they may have overlapping periods or prepare their next big idea, but they know their macro focus for a given time. Outside of entrepreneurship, it is also the nature of the stereotypical geek who can get obsessed with something and learn everything before the next obsession kicks in.
The opposite, “parallel focus”, is an oxymoron, because the very definition of focus is to limit oneself to a single thing. There are too many exciting things, and it’s hard to decide, so the person with parallel focus tries to make everything a priority at once. Quite often, I am that person. Again, there’s the example of the parallel entrepreneur. I’ve seen that term used for people involved in multiple ventures as a founder and for people who bootstrap a company while having a regular job or a contract. And there are successful examples of those, so is it possible to maintain parallel focus after all? I believe some considerations are vital unless you want to be on the highway to burnout.
Focusing on multiple things at the same time doesn’t mean you can do everything. You still have to say “No” some times. And I feel saying “No” is now even more difficult because adding a fourth item to a list of three seems less of a deal than removing your single macro focus. Also, approach your goals and the perfectionism about achievements and results realistically. You cannot compare a side project to something that another person dedicated their life and resources to. Finally, understand that there cannot be a perfect balance. Priorities change over time. You cannot expect to make progress in every area every single day.
So if like me, you’re struggling with missing macro focus and find yourself unable to serialize your priorities and approach them one after another as serial focus, I wish you good luck at maintaining parallel focus. Still, please be aware of the consequences and limitations.
In the realm of productivity, I think there are two types of focus. You could call them “micro focus” and “macro focus”. I came up with the distinction as it has been on my mind a lot lately. A quick search before I started writing showed me that I’m not the only one making this distinction. What I found intriguing is that William Webb, the author of that article, said that he’s much better at macro focus than at micro focus. It has been my observation that most people are like him, but it’s been a different experience for me.
But first, let’s define our terms, and my definition might be slightly different from his. For me, micro focus is about being able to choose a task, ignore others that are not relevant at that moment, and get “in the zone” where you can perform without getting distracted easily. Macro focus is about having goals and clear priorities and not holding too many projects and responsibilities at once.
I am good at micro focus. Using the Pomodoro technique was very helpful in getting there. Of course, I sometimes procrastinate when I am not sure how to proceed, but once I’m tackling a project, I stay on it. I’ve seen so many people for whom the incoming email, the person walking outside the window, etc. is always more exciting than the thing they’re doing, or who switch from one task or topic to another the moment they feel like it.
On the other hand, I think that many people have a better macro focus. They decide on a job or a personal priority or a side-project and then either keep at it or drop it after a deliberate decision that other things are more important. For me, so many projects sound exciting, and I want to be a part of them. Few things are good enough that I want to focus exclusively on them, though, not even for days or weeks. And there’s practically nothing that I’m doing that I want to get rid of entirely, probably because of a sunken cost fallacy but also the optionality fallacy and keeping all options open forever (which isn’t very sustainable)..
It is one reason I’m freelancing with multiple customers and doing other projects simultaneously: having options, and not buying into one thing too much. I guess my fascination with the world of APIs comes from a similar sentiment. I’ve always been an “and” person, not an “or” person. Cooperation between competition. The choice, comparison, and flamewars between technologies or tools A and B aren’t remotely as exciting as the integrations and standards that build bridges between the two.
As part of CloudObjects, I’m working on phpMAE. The PHP Micro API Engine is an opinionated serverless framework. One of its features is that it exposes any class methods as JSON RPC API calls. For public APIs, there’s a new way to make those calls to test a phpMAE class: straight from the CloudObjects directory. It may be a toy feature right now, but I consider it one of the first building blocks for unlocking the future potential of phpMAE.
To demonstrate the functionality, I made an ASCII Art sign generator as a small example. You can view its source code and try it on its directory page. If you are curious to learn more about this new phpMAE feature and how to create your public PHP class, read the full article “ Playing with public phpMAE classes in the directory” on the CloudObjects blog.
One of my topics of interest is the future of work. I believe that digital transformation fundamentally changes the way we work. Two of the aspects often mentioned are the rise of remote work and more arrangements outside of traditional salaried employment. So far, I mostly considered these as independent developments that are aspects of increased flexibility when it comes to working. Then, however, I read an article titled “The Workforce Is About to Change Dramatically”.
The piece in The Atlantic covers multiple aspects. For example, how the increase in remote work could either hurt or transform the travel and hospitality industries. However, my key takeaway from the article was the connection the author drew between a rise in micro-entrepreneurship and working from home.
When you work remotely as an employee, it changes the relationship with your co-workers. I don’t want to say “weaken”. Interactions on Slack or Zoom can be intense, but it’s different. More importantly, however, online communications flatten the world, because it doesn’t make a difference whether the person sits in the next room or on the other side of the world. And it isn’t relevant whether they work on your team or whether you interact with them in a different community, such as a personal or professional shared interest group. On the Internet, you can pick your tribe instead of having to mingle with the folks you share an office them.
If you are sitting in your home, you’re first and foremost alone and working on your own, but your virtual connections can go anywhere. You may realize that there isn’t a significant difference in whether you do your work for your team or sell it on an open marketplace where you might enjoy even more freedom, flexibility, and additional money. Of course, concepts like the gig economy or passion economy are not only fueled by people sitting at home and having time to rethink their relationship with their employer, but I agree with the author that it’s a crucial aspect of it.
My relationship with social media in general and Twitter, in particular, has been a recurring topic on this blog. I like discovering people and stuff through my news feeds, but a lot of the time, they are just a big timesink that drives FOMO and keeps me from doing other things.
According to RescueTime (⇠ referral link), I spent nearly 30 hours on websites in the Social Networking category last month, with around 22 hours dedicated to Twitter alone. (If you feel the total number isn’t too high, consider that it’s only desktop usage during working hours and doesn’t include using the phone under the blanket.)
Facebook, on the other hand, accounts for less than an hour. You could argue that the people and topics on Facebook are just dull, but the primary reason is that I’m no longer reading the news feed. I log in to Facebook only to see my notifications or directly interact with people. To facilitate that, I use a Firefox add-on called “Disable Facebook News Feed”, a minimalist tool that takes the feed out.
There was no similar add-on for Twitter, so I created one for myself. I had used the Facebook add-on for inspiration, but Twitter’s latest redesign doesn’t allow a simple CSS rule for feed removal. So I had to do something more sophisticated; if you’re interested in the solution, see the source on GitHub.
If you are curious about trying this add-on, you can get “Disable Twitter Feed” from the Firefox add-on directory. I marked it as experimental as it’s an early version that probably needs some fixes and improvements. Let me know what you think about it. If there’s sufficient demand, I’ll look into testing and submit it to other browsers, too.
To all the people that I follow on Twitter: I still love you! Feel free to tag me in conversations or DM me, and I’ll probably see it. At the moment, however, I have to prioritize my sanity and productivity over your great thoughts and interesting links.