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.
Sometimes people talk about the death of television. Who needs TV when we have Amazon Prime Video? However, we also still have printed newspapers and magazines, and we nevertheless have broadcast radio. Admittedly, each of these media has gone through a transformation and is less relevant as it used to be, but they are far from dead. The same thing is happening with TV. Even though I have no professional relationship with that field, I find it extremely interesting to observe the TV market.
First of all, to clarify our terms, I think that TV covers three things: Broadcast technology (in opposition to streaming), linearly scheduled programming (as opposed to on-demand access), and traditional brands and corporations. In some ways, these will prevail, at least partially.
Broadcast technology is energy efficient since there is only one signal sent for multiple subscribers. It is also reliable and doesn’t go down with spikes in viewership. Most of all, it is private. Websites and smart TVs track you with ad-tech, but nobody knows whether you’ve tuned into a broadcast. What makes it difficult for broadcasters to know their audience is a win for privacy. Therefore, even with all advances in streaming, I don’t think it’s a good idea to get rid of broadcast technology, at least as a fall-back; in the same way, we may want to preserve the POTS (plain old telephone system) even though we have VoIP.
Linearly scheduled programming looks like a downside at first, but live streams are a huge trend when you observe social media. Whether it’s TikTok, Instagram, or YouTube, every platform has a live streaming feature. Twitch thrives exclusively on them. In business, we sign up for webinars. In developer relations, two companies have recently launched video portals with developer content that mimic TV stations, Cloudflare TV, and Microsoft Learn TV (and I’m glossing over those with regular Twitch schedules). We even sync on-demand content through Netflix Party. It seems that we still like to watch things as they happen and at the same time as other people experience them.
When looking at traditional brands and corporations, it’s interesting to see how they try to transform into the digital age. There will undoubtedly be winners and losers. TV stations and content owners are launching streaming services and joining the “streaming wars”, Disney Plus being the most prominent and successful example so far.
In Germany, where I live, the two public broadcasters ARD and ZDF, funded by mandatory household media licenses, have invested a lot into turning their websites and apps into Netflix-esque on-demand libraries. They also launched funk, a content network that produces videos mostly for younger audiences, that they exclusively distribute online, mostly on commercial social media platforms and YouTube. While some might frame this as a desperate attempt at staying relevant, the best German-speaking YouTube content is now often made by funk (I admit to being a huge fan of Philipp Walulis’ work).
German private broadcaster RTL has launched TVNOW, whereas other private broadcasters have teamed up to build Joyn. The latter is particularly exciting because it features both on-demand and live content, including streams for almost all public and private channels (except those that RTL owns, whose live feeds are on TVNOW). In some ways, Joyn is similar to Hulu in the US. They try to establish a brand itself while simultaneously showcasing the brands of the TV stations that deliver the content. They also include content libraries from other online publishers, and their Joyn originals often feature influencers or YouTube personalities. Again, this might seem like a mash-up of unrelated things, but it could also be the perfect strategy to bridge the gap between the old and the new worlds of entertainment. I sincerely root for their success, because I think we need a German or European-owned Netflix. If Joyn plays their cards right, they can play that role.
Kin Lane, the API Evangelist, wrote about API providers being API matchmakers. I believe that idea goes along very well with content marketing for developers through tutorial-style developer content. In the article, which I discovered on APIscene, but Kin originally posted on his blog earlier this year, he claims that the value of a single API is limited, or at least not very visible. The real power comes from the combination of multiple different APIs. API providers need to know how their API fits into the broader landscape of APIs that their customers already use or might want to use. That awareness helps to communicate the value of your product. Kin suggests that API providers should have integration pages and making sure their API is also available on iPaaS providers (think IFTTT or Zapier).
While I agree that a presence on iPaaS providers should be a milestone in every API program and that integration pages are an essential element of developer portals, they are not enough. Kin writes about playing with different APIs in Postman and finding connections. Some of an API provider’s customers might need a little hand-holding to do that. That’s where developer tutorials come in. In their basic form, they typically show how to use an API in a specific programming language or framework. However, they can cover more than that and show integrations with other APIs as well. A good current example is “Build a Workout Tracker with GraphCMS, Auth0 and Hasura” from Jesse Martin of GraphCMS, where he showcases the value of GraphCMS by connecting the product with Auth0 and Hasura.
The great thing about what could be called a combinational developer tutorial is that it adds value for all products and APIs involved. Developer content like this piques the interest of multiple developer communities. It builds bridges, thus making it a piece of content with substantial value and a great, shareable marketing tool.
You read this and have some ideas for integrations between APIs and developer products but lack the time or skills to write a tutorial? Then, come and learn about my developer content production services on my website and contact me to find out how we can work together.
The Interintellect is, according to its Twitter bio, a “global community and talent platform for public intellectuals”. I discovered the Interintellect a while ago through its ties with Ness Labs and the Roam Research user community and read its manifesto. While I could personally relate to some of the things written in it, I found it initially hard to wrap my head around what the community is.
The Interintellect offers virtual salons on the Zoom videoconferencing app. Each of these three hour-long group discussions (10-20 people) has a specific topic. I joined three of them already. My first was about entrepreneurship, specifically asking whether there are too many entrepreneurs in the world. The second salon dealt with slow and fast thinking, as in Daniel Kahneman’s model. Finally, the third conversation was about reputation and how it works in our globally connected world. I enjoyed listening in and adding my comments and left each of these discussions with new insights.
A few days later, there was an exchange on Twitter where Seyi Taylor, one of the other participants, wondered why discussions at these salons “are so devoid of ego”. He subsequently pointed to an episode of the MetaLearn podcast in which Anna Gát, the founder of the Interintellect, was interviewed. The things Anna said in the interview and the discussion on Twitter gave a few pointers, but one central aspect is probably the type of people that the community attracts. According to Anna, there’s enormous diversity, not just between the people but also that most individuals are multidisciplinary. Folks are very open to new ideas. Many of them have some notion of otherness (e.g., because they are migrants), and others are “restarters”. They are givers instead of takers. What everyone has in common is that they want to nurture their “intellectual life”, an aspect that is often left behind work, family, and other aspects of life.
Without trying to take anything away from the Interintellect or diminish Anna’s skill as a host and leader, these exchanges are not exclusive to that community. I experienced similar discussions in a philosophical group I had with friends in college or right now in my Effective Altruists’ local group. There are places for a genuine exchange where people come to learn and exchange ideas. I believe it also helps that they are non-competitive, which means they are deliberately designed as an incubator, not as a “battlefield” of ideas, and also that the participants do not compete outside the space, for example, for jobs or research grants. The latter being a direct result of diversity.
I want to add another related thought: in these virtual or physical spaces, you realize that everyone present is smart and thoughtful and capable of understanding various notions, but each individual’s expertise and experience is different. They all are impressive in their way. That is not a place to impress others with what you know. Still, after going through an initial “imposter’s syndrome feeling” being among these fantastic people, you find out that you also have something unique to yourself to add to the table. And that’s where the magic happens!
Adam DuVander is a journalist turned developer-focused company content strategist. I recently listened to an interview with Adam, which was part of the Sprinklr Coffee Club series. On this blog, I’ve previously posted short summaries of talks, podcasts, or books by Stephanie Morillo, Lauren Lee, Hiten Shah, and Lorna Mitchell, combined with my thoughts on the respective subjects. In a similar format, I want to reiterate some of Adam’s ideas as well.
To motivate the work on developer content, Adam said that content marketing as a part of developer marketing or developer relations (DevRel) scales better than sending developers to conferences and meetups. If you’re just getting started, you can experiment with blog posts. However, he noted that many APIs don’t even have a real “Getting Started” guide as part of their API documentation, so that’s also an excellent place to start.
A central piece of content should be “a definitive guide on what the company knows”. Often, it is a downloadable e-book or whitepaper, but Adam said to be wary of gating access (e.g., with email signup). He calls this “signature content”. I recently saw another content marketer describing a similar approach who called it “cornerstone content”. The idea is to show your full expertise and demonstrate thought leadership. It ties in with the intention of content reuse and multiplication, where one piece of content leads to many derivatives. I’ve seen a lot of examples of those, such as infographics, social media posts, transcripts of podcasts, and many more. The “signature content” can be the foundation of everything else.
Content is a long game (it is one of the truths that Hiten Shah also emphasized in his talk). And it is crucial to be aware of it to avoid overblown expectations. No respectable content marketer or SEO agency can promise overnight success! You have to plant a lot of seeds, evaluate, and double down on what works. It’s also a good idea to have a mix of evergreen content and short-term content that has viral potential.
Another great thought from Adam, who previously worked at ProgrammableWeb, was that producing a high volume of content is essential when advertisers fund you. For everyone else, including most dev-focused SaaS companies, high quality and relevance are way more important than quantity. And remember, the goal of technical writing is to “share knowledge, not features”.
At the end of the post, I wanted to let you know I’m happy to talk about your developer content. Send me an email and let’s find out how we can work together.
I’ve been using the Pomodoro technique for most of my work for a couple of years, which has been a great productivity tool. Working in time-boxed blocks helps me keep focused without distractions. I recently learned about Work Cycles, which is a similar but even more structured technique. In addition to 30-minute blocks of focused work followed by 10-minute breaks, it includes specific questions for more mindful productivity, such as setting goals and evaluating one’s energy levels. The system also works great when combined with social accountability, and that’s how I learned about it.
Being a subscriber to the NessLabs newsletter already, I decided to support their community with a paid membership and joined their forum lately as well. In the “Events” section, I saw a thread about Work Cycles, calling it “a group Pomodoro work session”, a description that piqued my interest. I signed up for the first Saturday event, as I thought I could use some motivation to catch up with work over the weekend and joined the call yesterday.
There were six of us in a Zoom call. Kristijan, our host, asked each of us what we wanted to tackle in the session. Coincidentally, all of us were planning on doing something on a tech-related topic: learning, writing, or coding. I usually don’t have a problem working on my own and motivating myself (otherwise, it would be tough when you’re self-employed). Seeing this group of yet strangers working on something similar on their Saturday, however, immediately made me change my morale rating from three up to five out of five.
We went through three 30-minute blocks. Kristijan always gave us two minutes for preparation and evaluation, which we were allowed but not obligated to share, and set the timer for work. He also led the conversation about our experiences during breaks and in the debrief following the session. At least one other participant had experience with the Pomodoro technique, whereas another person meant they’re usually working in longer blocks. We also talked about a service called Focusmate that offers a similar format in a one-on-one setting.
I don’t think this is something I would do every day. Still, I can very much imagine doing it weekly to get some additional motivation, connect with people, and talk productivity.
There are various formats to describe data models. One of my favorite approaches is Linked Data based on RDF. That is why I based CloudObjects on this technology. My idea was to use RDF to describe APIs and the configuration of various application components. I quickly realized that a semantic web platform with built-in distribution and access controls has more use cases.
For a more approachable start, I’ve created a demonstration of CloudObjects Core using, wait for it, pizza! You can check out my latest post, “Pizza Time! Using CloudObjects Core for Domain Models”, on the CloudObjects Blog. As always, I’m happy for any feedback on the article!
Also, in case you didn’t know, I create developer content for third-party companies as a freelancer. If you liked the style and content of my tutorial linked above, hit me up, and we can discuss how I can create something similar for your product.
Yesterday, I made a little experiment; the first baby step into what is known as a #DigitalDetox or #DigitalSabbath. I switched off my laptop, phone, and other devices in the afternoon, and I didn’t switch on again until this morning. A while ago, I found a Digital Sabbath website that explains why turning of technology for some time is healthy and useful because most of the technology we use follows addictive design patterns. Those can be harmful if we’re no longer in control, and instead, the technology is in control of us. On top of that, because we have non-stop access to entertaining content, we rarely experience boredom. A bored mind is often a prerequisite to a creative process. The website poses it as a challenge to make it one day for three months. I haven’t signed up for it yet, because I’m not sure where it fits best into my week, but I’m planning to take breaks more often.
Apart from that website, I also watched a video on YouTube this week titled “How I Tricked My Brain To Like Doing Hard Things” that describes a similar phenomenon, and I can highly recommend that video. It suggests something that goes beyond the digital detox, a “dopamine detox”. The method includes not just refraining from technology but also things like junk food or offline pleasure activities. It was another motivation for me to try this.
Don’t get me wrong. I love technology and social media and entertainment, and everything else this modern world has to offer. I talked about my relationship with social media already in the first post this year. It might sound hypocritical for me, as a technologist, to advocate for less. At the same time, I believe that what they say, sometimes “less is more”, is accurate as well. I used my time off to play a bit on the piano and also finally start reading one of the books that were waiting for me on the shelf for a long time and made progress in another. There’s more time to do the things you always wanted to do if you don’t spend time mindlessly scrolling on Twitter or browsing Netflix without actually deciding to watch a show.
My primary programming language is PHP, which means that I am coding in something that 80% of web servers use and what 80% of developers hate. It is one of the languages with the worst reputation. Today, I read another piece trying to deal with the question “Why developers hate PHP”.
The article does an excellent job of explaining the origins of PHP. And it also shows the recent advancements and how much the language has improved. The author argues that many developers have made up their minds based on older versions of the language and have not updated their opinion in the light of new developments. Also, most widely deployed things are controversial, and it’s easier to hate on something everyone knows rather than something more obscure.
However, you have to be aware that the consumers of your APIs come with all sorts of languages and frameworks in which they will integrate your API. Your support and developer relationship teams will receive questions about all of them, and due to its popularity, PHP will be among them. In my opinion, no API program and developer portal are complete without code samples and tutorials covering PHP usage. If you offer SDKs, you need to have one for PHP.
So, if you are a Java shop that’s too “enterprisey” for PHP or a hip startup too cool to hire PHP developers, that’s where you can go to outsourcing. And guess what, I can help you. I code in PHP for almost two decades, and my current focus is creating developer content around APIs. I can also tap into the freelance talent pool to build content in all sorts of languages. Let’s talk about how I can support your customers from the PHP world.
I read Stephanie Morillo’s “The Developer’s Guide to Content Creation”, an e-book with a self-explanatory title. I can recommend it to everyone who’s getting into technical writing because it covers a lot of ground. In terms of its objective, it is similar to Lauren Lee’s “The Art Of Technical Writing” talk I wrote about last week, though it’s more extensive (obviously) and covers a few different areas.
Stephanie writes about defining your goals and generating content ideas, going through the planning, writing, and editing stages, talks about titles, call-to-actions, and resources, promoting content, and, finally, using analytics to iterate and improve.
For today, I want to focus on the first step, defining your goals. This post is inspired by the chapter in the book but contains additional thoughts and ideas from me. Writing and content creation can have many different purposes, and just creating something for a personal blog because you want to practice is a valid reason. Nevertheless, you have to think more strategically if you are a developer-focused company or are creating and sharing, for example, an open-source library with the world.
Every written piece of content, even your API reference, appears in search engines and thus is part of your marketing material. It may be the first part of your product someone sees. It doesn’t mean, however, that you must optimize everything for newbies or overinvest in SEO. There is a lot of value in creating content for advanced users of your product. Even documenting edge cases can pay off if it takes some load off your support.
Whenever you write something, think of your target audience. What do the developers know? Where are they in your funnel? Do you want to inspire them to start trying your product, or are they already sold and need some help? Often it is helpful to make up “personas”, which are fictional readers for whom you write. The most important thing to consider, though, is that you are not your target audience. You have already solved a problem that others still have, and you present your solution.
Also, think about your content strategy as part of the overall product strategy. For example, if you have an API with a wide range of applications, but your content only features use cases from a specific vertical, you will mainly attract developers from that vertical. Is that what you want?
Now that you have some things to consider when it comes to content marketing for developers, here’s my regular reminder that I’m available for hire for contract work. We can plan and create your developer content together. I’m looking forward to hearing from you!
Last night I joined the Vonage Developer Day live stream for a single presentation, Lauren Lee’s “The Art of Technical Writing”. Her talk’s objective was to motivate developers to write technical tutorials and provide them with the basics they need to get started. Lauren has an unusual background because she was a high school teacher before switching to a technical career, so this means she knows a thing or two about education.
The talk was incredibly fast-paced due to her passion and energy, so I had a hard time keeping up with writing notes, nevertheless I want to give you a little (subjective) summary.
Lauren says developer content should be instructional, non-assuming, timely, correct, and concise. The crucial points here are non-assuming because we often make wrong assumptions about what common knowledge entails and timely because technical content may get outdated soon. If you don’t know what to write about, “write the article you wish you found when you googled something.”
When it comes to creating tutorials, she suggests getting early feedback on an outline before starting to code and write. Then, implement the application and keep a journal or good commit comments that form the basis of your writing. After coding, move on to writing as soon as possible, so the memories of your challenges are still fresh. Edit later. Take time for the revisions and, again, get feedback.
A developer tutorial should start with an introduction, set a goal, explain the prerequisites, and then go through the necessary steps. It’s not required to document the whole codebase, just the essential parts. Include screenshots or animations. Put a summary at the end, and don’t worry about repetition; some of your readers reach here after skipping over other parts.
Some of Lauren’s general writing advice includes using a conversational tone without simplification words, inclusive language, and avoiding references that might be outdated soon (something I wrote about lately, too). And, of course, practice!
Once you’ve published your piece, share it loudly. Send it to people and look for cross-posting opportunities. Analytics tools are your friends to find out what works.
I enjoyed this talk. Though I have a lot of experience writing on this blog, the CloudObjects blog, and creating content for my clients, there were still some new or good aspects to hear about again, that will help me get better at my craft.
So, what are you waiting for? Go and create some amazing developer content! Or, if you don’t want to do it yourself, hire me for a contract.
One of the biggest and most unexpected news from the tech world this week was the acquisition of Keybase by Zoom. Video communications app Zoom is one of the big winners of the current COVID-19 pandemic but received criticism with regards to privacy and security. In contrast, Keybase has done a lot of exciting things in the realm of zero-knowledge, end-to-end encrypted tools for individuals and businesses alike, but appears stuck in their nerd and crypto niche.
I found out about the acquisition on Twitter, where a lot of people have negative attitudes and loudly proclaim deleting their Keybase accounts. The Keybase blog post doesn’t sound overly optimistic in terms of its future, and many expect the app to land in the Incredible Journey graveyard in the foreseeable future.
Selling their startup is a decision that I don’t assume any founder takes lightly, so I am very wary of accusing anybody of being a sell-out. At the same time, I am worried because every M&A activity decreases the number of independent players on the market, and loss of competition generally hurts consumers, so I always feel a little sad. A good counter-argument, however, is that we have a strong dominance of the so-called GAFAM - Google, Apple, Facebook, Amazon, and Microsoft. Two independent players teaming up stand a better chance against the behemoths.
I am cautiously optimistic here. Zoom’s biggest competitors are Microsoft (with both MS Teams and Skype) and Google (Meet), both of which are part of a business application suite. Keybase has a team product with team chat and file storage, all end-to-end encrypted. Zoom could merge with this to move beyond video calls and offer a full zero-knowledge collaboration suite for businesses. Also, even if it doesn’t play out like this, bringing encryption to mainstream Zoom is a huge win.
I don’t expect the Keybase app to shut down soon as I assume it’s not too costly to keep it up, and last but not least, the Stellar foundation might step up. We could even end up with an open-source Keybase server. Their client-side code is already open-source. Still, I’d love to hear more about their plans soon to get a bit of confidence before investing time and effort in using Keybase.
While going through older stuff saved in Pocket, I found a talk titled “Building A Content Marketing Machine” by Hiten Shah, which he gave at HeavyBit, a company accelerator targeting developer-focused startups. While the video is a few years old, I think there are a lot of good points made around content marketing for developers that still apply today.
If you look at the traffic for developer content such as blog posts, organic search is the primary source. Social media like Twitter is fantastic for engaging with developers but typically not a huge source of traffic. Hence, SEO (search engine optimization) is essential, but there are no shady tricks in SEO anymore. The only formula that works is to produce both quantity and quality and be patient. Content is a long game.
You should always be aware of your audience. Targeting developers at startups and CTOs at enterprises is entirely different. And you have to remember that the primary purpose of content is to provide something of value for them, not just, for example, show off your company culture.
Also, don’t just invest in content production, but also promotion. Influencer marketing works well for developers, so reach out to relevant people directly. Repurposing content in different formats, such as a blog post about a conference talk or a podcast, is worth it because you can increase the reach of your content without investing in something new every time.
Finally, the outsourcing of content production is possible. Hiten gave the example of Kissmetrics, who, at some point, had 99% of blog posts written by guest authors.
To summarize, you need both quantity and quality in technical content, tailored to your audience, and you can tap into external talents to create it. And guess what, I provide precisely this kind of service through my consulting business. Contact me to learn more!
There is a lot of buzz around “no-code” tools that empower people to build things without writing code. Website builders like Wix fall in this category, and so do IPaaS like IFTTT or Zapier. Makerpad is a community where people can learn how to launch a business with only those tools and without having to be or hire a developer. While I love and use some of those tools myself, they are also limited and don’t possess the full power of programming.
Anil Dash is the CEO of Glitch, a web-based IDE with a cloud-based runtime where people can write code and connect with a community of developers. He recently published an article on LinkedIn about a concept called “Yes Code”. Anil has similar sentiments about the potential of being able to code and believes that we should also empower people to learn that instead of just hiding the code behind the abstraction layers of “no-code” tools. He goes on about coding as a superpower and how it can help us build a better, “new human web” when we include more people in this process. I don’t want to repeat his points, so go and read his article.
For me, Anil’s thoughts are a good reminder of why I’m passionate about excellent API design and unique developer content. Yes, we need good material to teach the basics of programming, but we also need to make our APIs and SDKs and (open-source) libraries accessible and beginner-friendly. It is not only the right thing to do if you care about being inclusive, but it also makes good business sense to extend your audience and help a guy or girl building their next independent business on top of your API.
I can help you improve your API design to make it better for everyone, not just beginners, and I can create additional content to teach your API or developer product. Send me an email or fill out this form to learn more about my services.
It’s May 4th today. Happy Star Wars Day!
In case you didn’t know why this is Star Wars day, think of the famous quote from the movies: “may the force be with you”. Well, doesn’t “may the force …” sound a bit like “May, the fourth”? It’s a pop-cultural reference, and not everybody gets it. That made me think about whether or not to use cultural references in technical writing and developer content.
On the one hand, there is a particular set of famous cultural works that are associated with “nerds”, and being a software developer is considered being a part of the same (sub)culture. Developers can bond over shared interests in movies, music, etc. in the same way as they can bond (or playfully fight) over their favorite programming language or text editor. Fictional worlds provide engaging scenarios away from the mundane daily (home) office life, adding color and depth to sample code and tutorials. Why not take your first steps into the world of APIs with the Star Wars API?
On the other hand, referencing works from the Western male-dominated nerd culture could backfire and make women and people from different cultural backgrounds feel excluded. I firmly believe that writing code and participating in the API economy is for everyone. Hence, we should be accomodating to folks from all walks of life.
Additionally, an issue that might arise is that heavy use of references to commercial works of art could be considered copyright infringement. It is something especially larger companies should think of (and consult their legal department) before they lean on these works too heavily.
That said, are you looking for additional tutorials for your API, with or without cultural references? Check out my website for developer content production offers and talk to me about them. I am looking forward to hearing from you.
In my corner of the Internet (or dare I say “filter bubble”), I’ve seen a lot of recent conversations resurfacing the “garden vs. stream” metaphor for the web. There was also a virtual IndieWebCamp popup session about the topic, which I sadly only heard about after the fact.
To those unaware of the metaphor, its origin seems to be a 2015 keynote (or its transcript) by Mike Caulfield, “The Garden and the Stream: A Technopastoral”. It compares most of the current web to a stream where content primarily appears in chronological order. In contrast, the garden is a hyperlinked, timeless representation of connected content.
People running personal websites as blogs are turning to wikis as a way to represent information. Anne-Laure Le Cunff of NessLabs, who was one of the main motivations for me to try Roam to organize my thoughts and research, has started Mental Nodes as her “mind garden”. It is a site based on TiddlyWiki as the published counterpart of the private research notebook. The garden metaphor and “tend to your garden” expression, both apply to hyperlinked web content as much as they do to the mind itself.
It seems to me that many people are nostalgic about the pre-blog-era web, where individual homepages served as an informal outlet for their creators. However, I think there are good reasons that the stream dominates as the primary mechanism for content creation and consumption, especially in the mainstream (pun intended!).
While our human brains are capable of networked thinking, I believe that it is an art to connect the dots of multiple areas of your life and the world around you. It is even harder to dive into the networked thoughts of another person because there is no clear path. I’m not saying it’s impossible or disagree about its value, but it’s much harder than tapping into a stream or appending your current thoughts to said stream.
People love stories and storytelling. And by that, I don’t just mean fiction, but even the kind of stories that journalists create from real-life events and those that marketers use to sell us products. A story may require some background information, but it is a coherent piece of its own. Every story we hear or read adds to our mental model of the world, even if we don’t consciously make the connections, and yet if we don’t, we can still enjoy it in itself when it appears on the stream.
Every blog post, every tweet, everything we create can be considered a snapshot of our thoughts and ideas. These are, however, polished versions, not just raw dumps. It might be pretentious to call a post like this a story or even art. However, I hope it has some value, more than what I believe access to my notes in wiki-form could provide. And it is clear that it is a snapshot of myself in May 2020, and that adds relevant context in case my opinions evolve or change in the future.
Therefore, I’m unlikely to publish a mind garden for myself, but I’m happy to continue streaming stories to you.