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.
Last night, the API the Docs community started their second season of regular virtual events. We had Milecia McGregor and Louis Debatte-Monroy in the speaker lineup for the first meetup.
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.
So, what are the new features? With Apps, Airtable renamed the existing Blocks feature and opened it to the broader development community. They are HTML- and Javascript-based widgets positioned in the sidebar next to the table, and they provide additional ways to interact with or enhance the data. The features are excellent for internal tools because the apps can fill the gap where the spreadsheet interface is too limited, but a fully-blown frontend isn’t worth developing. I’m looking forward to investigating the possibilities for my projects.
Another feature that was silently launched a few weeks ago but is part of the announcement is Automations. It works like IFTTT or Zapier. Based on a trigger, such as a new row in the table, you can launch an action, such as sending an email. As I just found out, it even works the other way. For example, you can have external triggering events in apps like Google Calendar. I find it a little unusual that there’s no action to post to an arbitrary webhook URL yet. Still, you can run serverless Javascript on their infrastructure to issue a 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.
In 2012, Evgeny Morozov wrote an opinion piece in the New York Times titled “The Death of the Cyberflâneur”, of which I no longer remember if I encountered it back then. Recently, however, I learned the concept of flânerie in online interaction with self-proclaimed flâneuse Patricia Hurducas. She pointed me to this article. (By the way, I also covered another article by Morozov on this blog last year.)
If you’re not familiar with the concept: in a nutshell, a flâneur goes for strolls in urban places, which he experiences as a mindful outside observer. He doesn’t blend in and doesn’t follow a specific goal or purpose. His limited interactions are the result of serendipity and not a plan. The concept often appears in literature and is associated with an early metropolis like 19th century Paris.
The Internet (or, more specifically, the world wide web), with its millions of individual websites, would be a paradise for people to “surf” through, as we used to call it back in the day. Today, however, most online interactions are commercial and either optimized to get things done as quickly as possible or let ourselves distract as smoothly as possible. Unlike the flâneur, who performs his pursuit in solitude, many online activities are social. (That is, if I may add, also in stark contrast to how we pictured the first explorers of the online world as nerds without a social life, not realizing that even early BBS, the Usenet, IRC, etc. were social. We didn’t have the bandwidth and computation power for audio and video streams, but text interactions between people happened.)
In some ways, Morozov’s eight-year-old article is outdated. For example, he talks about Facebook’s vision of frictionless sharing. They had this idea that you’d log in with your Facebook account to apps and websites that would send everything you do back to the mothership. Facebook would aggregate and package that information and show you what your friends are reading, listening to, cooking, or whatever. Today we know that this idea didn’t take off, and Facebook did a 180° turn and locked their posting API completely. Nobody can automatically feed information to personal Facebook profiles anymore. Even Zuckerberg had to realize people want some privacy and do things without being continuously connected to their friends. Of course, talking about privacy, we hardly encounter websites without tracking codes (even I added one lately) anymore. Still, these generate anonymous profiles that rarely surface directly in our social sphere. And I feel we have a renaissance of smaller communities and dedicated places for social exchange disconnected from the rest of our (professional) online lives.
In other ways, however, Morozov is still right. We don’t “surf” the web anymore but mostly read chronological or algorithmic news feeds. It’s effortless and triggers the release of dopamine through its constant novelty. There is, however, still a web outside social media and large commercial estates. Some people write blogs (like me) that are still chronological but less noisy than social media updates. Other people create personal websites in the form of digital gardens to share their knowledge. The IndieWeb community is a place for creators of a diverse web. I wrote about the subject two months ago when I argued why I like blogging but not publishing a digital garden.
However, very often, the discussion centers around creation and not consumption. Even then, IndieWeb readers and RSS clients often mimic feeds and emphasize the efficient access to sources we already follow. Let’s look at our patterns of content consumption and bake some time for serendipitous discoveries into it. When was the last time you “surfed” the web, starting with some personal website, following links, almost getting lost, but finding something interesting in the process? I think it has been a while.
We should sometimes turn off social media and go outside in the physical world. But we should also sometimes turn off social media but stay online and become cyberflâneurs again!
I’ve struggled a bit with the question of whether I should set up some analytics on my blog and profile website. So far, I had none, and Google Analytics, the obvious choice, was a no-go. I think Google already has a lot of power and data, and I didn’t want to feed them if I could avoid it. On the other hand, I write this blog not just for myself, but I also consider it a marketing tool for my freelance business and other professional and entrepreneurial goals. I have shared what other people think about content marketing for developers, and at least two have emphasized the importance of analytics. Having some insights into whether someone reads this at all would certainly be helpful. If I can support an independent, privacy-focused small business in the process, it’s even better.
There are a few of these smaller analytics providers. My choice was to go with Plausible Analytics. Their product is minimalist, but with all the essential features. They are fully open-source, hosted in Europe, and work without cookies. Also, out of its competitors, it’s probably the most affordable option, starting at $48 per year (I want to support an independent founder but also have to mind my business expenses).
As you may know, my blog is hosted by micro.blog. And Manton, the founder of micro.blog, recently added a plug-in feature based on Hugo themes. Therefore, instead of just modifying my blog theme, I decided that I could build a tiny plug-in to simplify installation for me and others. It’s just a few lines of code and configuration, and you can find the plug-in source code on GitHub. It took me a single Pomodoro session to develop.
Within less than 24 hours, Manton shared it and added it to the plug-in directory, and also Plausible listed it as integration in their documentation. Also, there is at least one member of micro.blog that started the free trial of Plausible Analytics.
Last but not least, I have decided to be fully transparent and make my analytics page public so that you can have insights into this blog, too.
Adam DuVander talks a lot about the idea of “signature content”. I recently published my recap of an interview with Adam, where he mentioned that term, and since then, I came across another great piece from him. He calls it the “developer content mind trick”. The idea is that companies should not just publish content about using and integrating their APIs and products, but also explain how they built their service and how they solved the underlying problems.
Now, one might argue that this is giving away valuable intellectual property and allows people to copy you more easily. And, indeed, it can happen, but it probably would even if you didn’t publish. In the developer space, a significant competitor for every product is that a potential customer builds it instead of buying an existing solution. It’s the NIH syndrome - “not invented here”. Developers often see a product and think, “yeah, I could build that in a weekend”. It is where the mind trick comes in. You show how much effort went into the product and all the little corner cases that you’ve thought of that the potential consumer hasn’t. Hence, you demonstrate your expertise as a company and the value of your product.
In my last article, I mentioned the term “cornerstone content”. It comes from Jake Jorgovan, an entrepreneur running marketing agencies for lead generation. He is not in the developer space, yet a lot of his ideas are similar. Let me add two quotes from his e-book, “The consultant’s path to thought leadership”.
“By giving our secrets away, we established ourselves as the leaders in the field. This built incredible trust among clients and referrals from our audience.”
“For a small firm, your trade secrets can create far more value as marketing materials than you can by holding them close to your chest. You can teach everything you know, and use that to attract more deals and opportunities your way.”
It doesn’t matter if you call it signature content or cornerstone content. Two examples from different areas show how powerful it can be to produce great content about what your company does and how you do it and then leverage it to drive sales. To some extent, I’m doing something similar on this blog. I write about developer tutorials and content marketing, and I quote experts in the field, probably driving some of my readers to learn writing or hire them instead of me. But I bet that I can demonstrate my expertise in aggregating knowledge and connecting the dots between different ideas, and people want to work with me because of that.
And that is where you’ve reached my sales pitch. One thing I do is helping companies with developer marketing by creating technical content. Talk to me, and we’ll find out if I can help you.