I’ve been in developer relations for about a year now. Actually, I’ve only known that “develop relations” and “developer advocate” have been specific things for that long. The first time I consciously encountered these titles was when I was offered the role as "Head of developer relations" with my current job at Sanity.io. It seemed to encapsulate with what I could contribute with.

Even though I had never worn such titles before, I had experience in teaching, mentoring, and dissemination, and I had been promoting aspiring developers before. I have a lot of training from teaching theory and methodology at University, I have run web development courses for retirees and beginners, and I have been writing about technology for a long time. I just didn’t know that that was a dedicated job in tech, and not the least, a “scene”. With T-shirts, stickers, books, and Slack groups. With the title, I was also joining a community and a discourse.

1. Find yourself a team that cares

I joined Sanity when they mostly were the developers from the original Bengler team. They  made the platform because they wanted a real-time content backend for OMA’s website. In 2017, they converted Bengler into a startup for Sanity. Since I joined, I had to figure out how to do the developer relations part, but also contribute to how we should communicate Sanity in general. I’m very fortunate to be working with some fantastic people, both in terms of talent and experience, who also give an excellent mix of constructive feedback and praise.

That’s perhaps the most crucial part of what motivates me as a developer advocate: It's much more fun when you and your colleagues feel that there’s a stake, that there‘re care and attention given to almost every detail of what we do. I get the sense that we have made this cool thing that we want people to use, because we think it makes their day better, and they will make cool things with it. If you want to work as a developer advocate, be on the lookout of a team that cares. It’s easy enough to forget if the product has a cool flair, or the perks are awesome.

2. Learn to take feedback

That stake, and care, comes with a challenging side too. There will be a lot of opinions, inclinations, ideas, and feedback on whatever you do. The feedback may even be conflicting or just not feasible to follow up. Your job is to mediate the feedback that you get within the company, with that you get outside, and turn it into something constructive and actionable.

I try my best to communicate why we are doing what we do in the weekly all-staff meetings. I also make sure to include nice things people have said about our work to remind the team that they’re doing work that's appreciated by real people. That's the “relations” part of the job.

I give much consideration to the feedback I get from my colleagues, but I don’t always follow it. That's partly having to follow my gut-feelings from all the impressions and observations I've, being "out there", and partly because the advice you're given is for inaction (“We shouldn't do x, y, z”).

I remember that we had a lot of discussion and indecisiveness around creating a new developer community. All the services had drawbacks for sure. My job then was just to pick something, and get it going. So I did. A year after we’re over 1.100 developers in our Slack. Yes, the message retention sucks, yes, it would have been handy to have all our answers indexed by Google. At the same time, the feedback, enthusiasm, and all the questions have been invaluable. We don’t regret it.

3. Talk less, listen more

Speaking of the community Slack. I also remember being super worried about trolls and people that would object to our Code of Conduct. It’s super interesting to see that many of us in tech are occupied with figuring out how we can make sure that people feel welcome, included, and safe. Since I became more aware of people’s shitty experiences, and my own mostly hassle-free experience in tech, I must admit that I many times have been afraid of inadvertently saying something that may cause someone discomfort.

Because I used(?) to be much more of a "here’s my five cents”-guy on Twitter and such (well 600 words in, I guess I still kinda am), but I have consciously abstained from posting and replying to stuff that may have irritated me. I use two thought technologies (which I picked up from the Back to Work podcast). The first is saying out loud: "I will not let this bother me." The second is to question "Is this the hill I want to die on?". They actually work — most of the time.

Instead of being such a smart ass, I have been trying to observe and listen instead. It is something I still work on being better at. I have been listening in two ways. First, I have made sure to follow a more diverse cast of people, and I have been trying to take in the stories of those who display concerns about the inclusiveness of tech. I’ve also tried to contribute with some thoughts and took part in organizing Global Diversity Call For Papers Day. And it has been humbling. And frankly, it’s nice not being the one offering the hot take or glib tweet (well, there’s still some occasional ones).

4. Learn how to take time off

Honestly, I’m still rubbish at this. So I write this as much as advice for myself as for you. Thing is, there’s an infinite amount of tasks you can do as developer advocate: there’s always another talk proposal, demo, blog, or some documentation you could improve. There are always people that need help with something. So you have to draw some lines. Now, it’s hard to offer exactly what those lines should be because it also is highly dependent on where you live, whom you live with, if you have a family, how old you are, etc.

I’m fortunate in having gotten professional help for recurring depressions, and have mostly figured out how to live with it (CBT worked for me). I’ve been through a burn-out experience when I did my Ph.D. studies at University and got into tech after that – where I felt much more at home. I’m also fortunate in having a spouse that rides dressage. I often tag along to the stables to get some honest off-screen time with our two horses and help her out with grooming, and the many tasks and sorts that you have to do there. I also do my best to get some exercise, jogging and such. Doing something completely different seems essential.

Taking time off is partly on you, but having a workplace that understands that highly motivated people often need help with setting boundaries and be reminded that they need to take time off to not burn out at the office, is important as well. We’re regularly reminded of this at Sanity, and we’re trying to build structures (everything from how projects are planned, to setting expectations) that enable and ensure this as well.

I also think it’s vital for us that has the roles of being a developer advocate to communicate this as well, and to our own discretion share those part of the daily life. It’s easy enough to feed into people’s impostor syndromes and impression that you have to work all the time to belong in tech.

5. Take it seriously, but don’t be too serious

As a developer advocate, you do an important job. You’re both responsible that other people are successful at what they try to do, and on relaying back to your team what you learn. You are inevitably tied to your workplace and — excuse the marketing term — its brand. If you are approachable and helpful, that will contribute a lot to your company’s success. Even if I had put “opinions are my own” in my twitter bio, my behavior will reflect something back on people’s impression of Sanity, and the work being done there. So I owe to my team to be mindful of how I act and communicate. This position is very different from coming from the Humanities, where you are much more your own agent (at least, this was the case where I was studying).

This connection that you have with your workplace, and the fact, lets be honest, that much of what you’re doing can fall in under the term marketing, also means that people will have certain reasonable expectations of your biases. The serious part is not trying to be coy with whom and what you are representing, and be transparent when you’re discussing things where you obviously have an interest if promoting whatever you do.

At the same time, you are also a person with all the flaws and particularities that comes with that. Sometimes, people will say disparaging things about whatever you’re working on. Or they will dismiss you as a just a biased representative of where you work. That is the time where you shouldn’t be tempted to go into arguments or make a big fuzz. Try to distill whatever legit criticism can be found, and move on.

---

Being a developer advocate is probably the most exciting job I have ever had. The range of different things you can do and the people you encounter is ideal if you’re motivated by learning new things and are excited by learning what other people are creating. It has been an absolute blast being part of launching the developer community for Sanity, and we have a pretty interesting year ahead of us opening a new office in San Francisco, hiring more people, and preparing for the next step.

I look forward to looking back at the coming year with a new blog post like this. Stay tuned (e.g., by subscribing to the RSS feed)!

Honestly, I wasn’t fully prepared to roam amongst 900+ handsome people towards the end of a pretty busy week, in a pretty busy start of the year. I instantly felt my introvertism blossom arriving at the venue on The Midway. I got it somewhat tempered by caffeinating on the Diet Coke I fell back on because of endless coffee lines. Fortunately, I had a conference buddy, and the overall mood was super friendly.

Having been somewhat involved in Webdagene (Norway’s largest web conference that turned into Y Oslo), I know how hard it is to organize these things. There should have been more coffee stations, some re-thinking of the people logistics, and pre-signup with limited attendees to the workshop sessions. That being said, I’m super impressed with what the Figma team managed to pull together for their first conference. I have high expectations for next year! (because there will be one next year, right?)

Following are my take-aways from some of the talks I attended. As of now, only the live-stream from the first keynotes is out, but I’ll add the rest of the videos once they’re published.

Welcome to a new decade of design, Dylan Field

Watch on YouTube

My first real-life encounter with Dylan, the CEO/Founder of Figma, was actually when a couple of colleagues and me got to visit their HQs back in August 2019. We were already starry-eyed when we ringed the front-door. This super-friendly eerily familiar person let us in and found our host there. The shy Scandinavians that we were, and honestly, a bit nervous, we forgot to introduce ourselves properly. Not before after did I realized that we were let in by Dylan (I blame his artsy Twitter avatar).

Dylan opened Config pretty much the same way. He set the mood with a down-to-earth approach and a lot of humor that made the floor filled with 900 ambitious and highly skilled people, that’s also aware of the other ambitious and highly skilled people, a bit more relaxed. Of course, he was there to launch some neat features, like better font-pickers (it’s fascinating how “small” improvements may save so many people a lot of time), and new auto-layout gizmos (huge cheer), and deep-linking to make it easier to get your collaborators to the right places.

Link to Dylan‘s keynote with timestamp

Dylan also included a highly appriciated throwback to @fat’s legendary Pencil Tool video.

View on Twitter

Adding scaffolding to collaboration for deep work, Craig Mod

Watch on YouTube

Dylan was followed by another friendly guy, that introduced a bit of vulnerability and self-reflection on the stage. My inner monologue watching Craig was a mix of “dammit, that’s clever, I wish I had thought of that” and “this is so relatable!”. I think everyone felt it when he talked about making a humongous book out of all the design comps and git commits from the Flipbook development. And a bit of envy from his long-ass walk from south of Tokyo to Kyoto.

Craig’s talk made me reflect more about how you should actively set healthy constraints for how you approach work, especially creative work. With the constant influx of notifications, it’s sometimes tempting to go full Luddite. What I liked about Craig’s approach, is that he considered how he could use technology and certain rules to both improve the mental environment, but also create other, and perhaps more interesting connections with people. Playing around with synchronicity and asynchronicity.

Link to Craig’s keynote with timestamp

I pressed ⌘B. You wouldn’t believe what happened next, Marcin Wichary

Watch on YouTube

There was a lot of buzz around this talk upfront. With good reason. This was probably the highlight of the conference. Partly because what Marcin brought to the stage is so very relatable for someone who works in a product company. Namely, the complex work that may behind the seemingly simple features. This is especially true when you work with a product that’s real-time and collaborative. 

Marcin is brutally honest and equally funny. And the slides were brilliant too. I can't really reveal much more of this talk, because it has some spoilers. I guess you just have to see it when it's out.

States; a product love language, Lucas Smith

Watch on YouTube

Lucas Smith’s musings about state in product design resonated with something I many times have felt as a frontend developer. Especially back in the days when I got handed stills from photoshop and such. I believe it’s also some of the motivation behind the “designers should code” thing. His distinctions between imperative and declarative modes of working with the design made a lot of sense too. There’s a negotiation between “how it looks” and “how it should work”. I believe it’s mighty helpful to both aware and to communicate this when you present design and ask for feedback.

Open source design. Design is the future of open source., Soleio

Watch on YouTube

I didn’t expect to feel as much at “home” at this conference as I did. Because I’m more of a developer than a (visually oriented) designer (cue the “everyone is a designer” debate). But I really connected with most of the talks because there so many concerns that are in common. Open source is one of them, and it was interesting to hear Soleio talk about his views on open source. Not just inherently interesting, but also because Soleio is founder and partner at the VC fund Combine. As someone working at a startup, I seek to understand the weltanschauung of those investing in technology and design.

Soleio suggested that open source is perhaps less about the access to the material (i.e., the code, or the vectors), and more about that it allows people to reshape what it can be used for. His prime example was the invention of spreadsheets for budgeting and calculus, and how it was reshaped by the Shitty Media Men List and the #metoo movement.

I also appreciated the rush of nostalgia when Soleio brought forth Joshua Davis’ PrayStation CD-ROM, released back in the days when Flash was a thing.

Open source design. Designing with the Community., Miguel Solorio

Watch on YouTube

Miguel is the only designer in the surprisingly small team behind VS Code. He told us how his team involved the community in their design processes. And by the community, we’re talking one of, if not the, most popular code editor. That seems like a stupendous amount of pressure when you have to make design decisions that affect a tool that millions of people use for their work every day. Again, talks are always more interesting when they talk about hard-earned lessons, and they came improved from it. Definitively one of the talks I’ll revisit for inspiration on how we can get better at involving Sanity’s community when we’re figuring out new stuff.

Joyful Subversions, May-Li Khoe

Watch on YouTube

It’s not often I get teary-eyes at conferences. But May-Li subverted my professional conference attendance posture and dug right down to both existentialism and humanity. It’s so easy to get bogged down in all the bubbly concerns in growing a startup, that it’s easy to forget that what you are making and spending time on realizing, may be used to improve people’s lives in small and big ways.

I was amused to learn that the turntable icon that I chose for my mac’s user account because I didn’t have any selfies at the time, and never bothered to change it, was made by May-Li.

I think I’ll just keep indefinitely.

Then it changed. Medium needed to find a way to make our writing and your reading their business. I guess that’s better than making our attention and behaviour their business, although I suspect that this is the case too. So Medium has put up nag screens reminding us that we need to pay them. Fair enough. But I don’t want my readers to have to pay for my blogging, or click through pop-ups. So I’m moving back to my own little corner of the web.

I put up my first self-made website on the internet in year 2000. Back then I blogged in hand-written HTML, before I got into PHP and fiddled around with early CMSs before adopting Wordpress. I’ve been on LiveJournal and blogger too. When I pushed code for money, mainly building Wordpress sites,  I started using Squarespace for my own blog, partly because I wanted to try it out, and partly because I wanted my space to be hassle-free (I was sysadmining enough Wordpress sites as it where).

This post is published on my own blog on knutmelvaer.no, and then, as the last gesture, imported into Medium giving it the proper canonical URL while that still is possible. From here on, if you want to follow my writing, you have to visit the webpage, subscribe to the RSS when I have gotten that fully up and running, follow me on dev.to (where I’ll syndicate my posts), or just pay half-attention to my twitter feed.

There hasn’t been much writing on my own part the last year either. Mostly because I’ve been occupied by figuring out how to be a developer advocate in my new job at sanity.io. But I figured it’s time again. My new blog is made from the JAMstack Sanity.io + Gatsby + Netlify starter. I’ve started tweaking it to make it my own, it feels very much as the exciting early years of my web development adventures.

I have also started implementing microformats2 and webmentions.io, which I’m excited to learn more about. Expect that other nifty features will enter this little web realm of mine too.

See you in cyberspace!

10x what? Context, please.

View on Twitter

Investor Shekar Kirani recently posted a thread on twitter about the traits to an alleged type of engineers/programmers. I think it's safe to say that they are a combination of stereotypes that many people find toxic and problematic in a work environment. The ethos of the tweet seems to be that there are these people that don't fit in with the normal expectations of the workplace (“they don’t like meetings” etc), but will be these efficient, high performing workers that will give you, the founder, an advantage in the race that is product development.

I'll leave it to others to rebuke each and every argument in this thread (just dive into the replies to get an idea), but let me just point out that the best coders I know have tended to be really nice people that have happily shared their knowledge, gone to meetings, had family obligations, and all sorts of desktop backgrounds.

I piled some wood on the bonfire

So Shekar’s tweets struck a nerve and the reactions were plentiful. People were tired by the whole 10x thing before two hours had gone. The sentiment among the outspoken programmers and tech people were pretty unified against the idea that the profile the tweets painted had any basis in reality, and were a collection of traits that had no business being in tech or a workplace. There were also worry that these tweets rehearsed and perpetrated ideas that are shared among founders and investors. Some of the generalizations also made it really easy to mock and satirize the twitter thread.

As I've written before, I'm sometimes tempted to do the hot take or go for the satirical smartass comment on Twitter. Shekar’s thread got to me, both because here was this investor promoting something I deeply disagree with, but also because it seemed so out of place to do so in an environment that's just ready to pile on people that seemingly work against making tech a healthier and more inclusive place.

So I tweeted something to the effect that I think it's weird that an investor would say these things publicly, and should have known the response it would get. It simply doesn't seem like a strategic move, even though if one means it. Only I choose to put emphasis on what these tweets said about Shekar as a person, and by “quote tweeting” him. Making the recipients my audience, and engaging him directly.

I got my likes and replies and moved on with the day. I was one of many hundreds, if not more, that more or less mocking wrote Shekar and his thread off. As one does on Twitter, right?

Is this the person I want to be?

And then I got some feedback. A person, whose opinions I care about, told me that I came off arrogant and with little respect to a person I disagreed with, who I didn’t know, on the basis on some tweets. My first reaction was to become a bit annoyed. I just did what you do on Twitter, right? Here's this investor saying outrageous stuff, and I was sticking it to the man. But then I had to reconsider the critique because it came from a place of concern.

I don't know Shekar. I don't know much about the context he's working on in India. But I know that the respect and humanity I found lacking in the ideas behind his tweets were a bit lacking in mine as well. I didn't tweet what I did because I hoped to change anyone's mind or educate them.

I tweeted what I did because I wanted to look smart and part of “good team“. I was virtue signaling. And doing so by throwing timber on a bonfire to a person that probably didn't expect how this thread would blow up. That's not a person I want to be, and I don't think I really was helping promote the ideas and practices we so dearly want in tech.

So I deleted my tweets.

I’m not done thinking about how I approach Twitter

My reconsideration of how I approach Twitter can easily be read as a value judgment of others’ satirical or mocking replies to Shekar’s tweets. This is where I’m ambivalent. Because I do mean and appreciate that there is a place of satire, humor, and jestful creativity to counter destructive ideas put forth by people in power. The site 1x Engineer is a good example of this.

There’s also another side of this, which is that of privilege. I have, as a Norwegian guy in my early 30s, very little reason to feel particularly angry or hurt based on my experiences growing up in one of the safest environments on this planet. But other people have plenty of good reasons to feel and express both.

That’s why I explicitly am framing these thoughts as the reevaluation I’ve done for my own behavior, and put them here in a way to think loudly in public, and to hold my self accountable. So this is how I'll try to approach critique on the web going forward. And frankly, most of these points are not original and have been made by many others before me:

• I'll consider that I’m responding to a real person.
• I’ll comment on the actions and ideas represented in the tweets.
• I’ll consider that the person may have English as a secondary language (as I do), and are not aware of nuances and the implications that certain word choices may have.
• I’ll consider what I want to achieve: Is it providing nuance or reconsideration? Is it just blowing off steam? Is it marking a stance?
• I will to the best of my ability, try to make it possible for the person to reconsider, or engage me in a discussion.

I believe I know what you’re thinking: What about trolls and people with extreme and hurtful opinions? I don’t really think all people on Twitter is there for “enlightened discourse”, which the points above are aiming for. And obviously, many people know what they’re doing when they say hurtful stuff. As for now, I’ll probably not grant them much of my attention and counter with promoting ideas and activities that make tech a safer and more inclusive (for example, Making tech surviveable: What can men do?).

---

Is there something I have failed to consider here? Did this make you think about how you use Twitter? I’d love to hear about it!

So, early disclaimer: I work for Sanity.io, where we're making what we call the platform for structured content. It replaces your CMS, but it also gives you more power and flexibility when it comes to how to interact with that content, not just in terms of distribution. It lets you treat content as data. That's the key.

So, of course, read this as content marketing if you want, but I hope you can get something out of it if you're interested in content management. And yeah, if Deane can be strategic director over at Episerver while writing this guide (he started it before taking on this position, I believe), I think it's OK for me to see their writing through the lens of Sanity.

This post makes most sense if you have at least scrolled through their chapter beforehand, but I'll try my best to give enough context to make sense. This also why I follow the same structure in terms of headings. With that out of the way, let's jump into it!

Most CMSs can publish content in some form out-of-the-box, but they have to be...persuaded to do it in a way that fulfills your requirements.

I went ahead and initiated a new project with the “clean templates”, which comes with no content types at all. So little persuasion needed, in fact, Sanity.io is designed not to have to be persuaded into being what you want, but exactly the opposite, it's built to be configured and customized to precisely what you need (you can give yourself a head start though).

Model implementation

The model implementation is your content model working inside your chosen CMS.

With Sanity.io you get an open-source application that functions as the CMS in most cases. You do model implementation by describing schemas in simple JavaScript objects. This is somewhat different compared to most CMSs where you do it with forms in a graphical interface. It may seem more difficult, but it lets developers and people with some JavaScript skills to version control schemas, and have a short way to do more advanced stuff like custom field validation and code-based generation of schemas. It also makes the distance to customizing input components much shorter.

The guide mentions that a model is a combination Types, Attributes, and Validation Rules, and uses an “Article” (type) with “Title” and "Publication Date" (attributes), and “minimum length” (validation) as an example. If you run npm i -g @sanity/cli && sanity init and go through the steps, you'll be ready to make the content model within a couple of minutes. Here's how you make the minimal article example with Sanity:

// article.js

export default {
  name: 'article',
  type: 'document',
  title: 'Article',
  fields: [
    {
      name: 'title',
      type: 'string',
      title: 'Title',
      validation: Rule => Rule.min(10).warning('The title should be longer')
    },
    {
      name: 'publishedAt',
      type: 'datetime',
      title: 'Publish date',
      description: 'Choose a date for when the article should be published'
    }
  ]
}

When you run the studio (it's a single page application built with React) this code will generate a user interface that looks like this:

So far, so good. Where it gets interesting is when it comes to content model limitations. Sanity.io is built for structured content, so we have gone far to make it as flexible as possible.

Limitations?

However, sometimes you just can’t wrap a CMS around your model requirements.

Here the authors come with two examples:

• The model supports linking the Article object to an Author object, but it doesn't let you go in the other direction, i.e. the link isn't bi-directional.
• Your model requires a Meeting object to have sub-objects for Topics. Each Topic is also a content object.

Bi-directionality

Let's add an author type and a new field to the article which is an array of references to the author type (because you want multi-author support, don't you?):

// author.js

export default {
  name: 'author',
  type: 'document',
  title: 'Author',
  fields: [
    {
      name: 'name',
      type: 'string',
      title: 'Author',
    },
  ],
}

export default {
  name: 'article',
  type: 'document',
  title: 'Article',
  fields: [
    // the other fields,
    {
      name: 'authors',
      type: 'array',
      title: 'Authors',
      of: [
        {
          type: 'reference',
          to: [{ type: 'author' }],
        },
      ],
    },
  ],
}

When using the reference attribute/field, Sanity will index those references bi-directionally. So if you wanted to query all authors with their articles although the field is set in the article object, it can be done like this with GROQ using joins (actual example):

*[_type == "author"]{
  name,
  "posts": *[_type == "article" && references(^._id)]{
    title
  }
}

This query can also be baked into the Sanity Studio using split panes to show “incoming references”. This is a minimal example (and of course, you can use the same logic to show “related” documents by pretty much any logic):

// deskStructure.js
import React, { Fragment } from 'react';
import S from '@sanity/desk-tool/structure-builder';
import QueryContainer from 'part:@sanity/base/query-container';
import Spinner from 'part:@sanity/components/loading/spinner';
import Preview from 'part:@sanity/base/preview';
import schema from 'part:@sanity/base/schema';

const Incoming = ({ document }) => (
  <QueryContainer
    query="*[references($id)]"
    params={{ id: document.displayed._id }}
  >
    {({ result, loading }) =>
      loading ? (
        <Spinner center message="Loading items…" />
      ) : (
        result && (
          <div>
            {result.documents.map(document => (
              <Fragment key={document._id}>
                <Preview value={document} type={schema.get(document._type)} />
              </Fragment>
            ))}
          </div>
        )
      )
    }
  </QueryContainer>
);

export const getDefaultDocumentNode = () =>
  S.document().views([
    S.view.form(),
    S.view.component(Incoming).title('Incoming references'),
  ]);

export default S.defaults();

This will produce this interface, and by the way, it's real-time, so if someone adds this author to another article, it will appear in the right list without requiring reloading.

Nested structures

The second limitation has to do with nested structures (parent-child). Personally, I tend to avoid putting too much hierarchy into content models, and I suspect it often comes from “sitemap” and “nested menu” thinking where you structure content to make navigation. I prefer representing navigation as a separate content structure with references because that lets us more quickly iterate on navigation structures, but also have different content trees for different presentation layers and purposes. But I digress, let's look at the example:

Your model requires a Meeting object to have sub-objects for Topics. Each Topic is also a content object. To do this, you need to connect a Topic to a Meeting in a parent-child model. However, your CMS doesn’t have a content tree that would allow this, nor does it allow nested objects. You can link a Topic to a Meeting, but someone else could link another Meeting to the same Topic (not allowed by the model), and it doesn’t stop the Meeting from being deleted and “orphaning” a bunch of Topics (also verboten).

There are mainly two approaches to this with Sanity, you can either just embed the topic object model in the meeting model because the schema allows for nested objects. You would still be able to query for only topics, and you will never have this orphanage or multiple meetings tied to the same topic, which in this case is unwanted. Here is a simple example:

// topic.js
export default {
  name: 'topic',
  type: 'object',
  title: 'Meeting topic',
  fields: [
    {
      name: 'name',
      type: 'string',
      title: 'Topic name',
    },
    {
      name: 'description',
      type: 'text',
      title: 'Description',
    },
  ],
}

// meeting.js
export default {
  name: 'meeting',
  type: 'document',
  title: 'Meeting',
  fields: [
    {
      name: 'date',
      type: 'date',
      title: 'Meeting date',
    },
    {
      name: 'topic',
      type: 'topic',
      title: 'Meeting topic',
    },
  ]
}

Notice how I have described topic as an object type here, and how I refer to this type in the meeting schema. The interface for this will look like this:

And the data structure will end up like this:

{
  "_createdAt": "2020-04-09T11:21:22Z",
  "_id": "d9996973-58aa-44be-8a8a-c24c7df61b6e",
  "_rev": "lwxf4peCy8NTOg4fhvBuIK",
  "_type": "meeting",
  "_updatedAt": "2020-04-09T11:21:22Z",
  "date": "2020-04-09",
  "topic": {
    "_type": "topic",
    "description": "This is a nested object.",
    "name": "A unique topic tied to this meeting"
  }
}

And if I wanted to query all meetings and return just the topics in my dataset, I could do it with this GROQ query: *[_type == "meeting"].topic.

Now, let's make this a bit more interesting, and say that we wanted to implement topic as a dedicated document type, and use references to tie them to meetings. If we want to avoid orphan topics, we need to put the reference on the topic side. If a topic has a reference to a meeting, you can't delete that meeting without removing either the topic or the reference first. Granted, the UI for this flow can (and will get) a bit smoother. But here's how to do it:

// topic.js
export default {
  name: 'topic',
  type: 'document',
  title: 'Meeting topic',
  fields: [
    {
      name: 'name',
      type: 'string',
      title: 'Topic name',
    },
    {
      name: 'description',
      type: 'text',
      title: 'Description',
    },
    {
      name: 'meeting',
      type: 'reference',
      title: 'Meeting',
      to: [{ type: 'meeting' }],
    },
  ],
}

This will produce this interface:

And if you now try to delete the referenced meeting, you'll get this warning:

Sidenote: You can define references as _weak: true if you explicitly don't want this integrity check.

Editorial Experience

The authors discuss the concepts of Data Coercion and Data Validation, in other words, making sure that it's easy to let editors put in content in the correct format, and validate the content if it's possible to enter it incorrectly. The first example is adding a publish date field for an article, where it doesn't have a time stamp, and the date shouldn't be in the future. Here's how to do exactly that with Sanity:

{
  name: 'publishedAt',
  type: 'date',
  title: 'Publish date',
  description: "Choose a publish date. Can't be in the future",
  validation: Rule =>
    Rule.custom(
      date =>
        date =< new Date().toISOString().split('T')[0] ||
        `This shouldn't be in the future`
    ),
}

Sidenote: The validation property also supports promises and any logic you can express in JavaScript, which means that you can validate fields via APIs and whatnot. All fields come with common validation rules out-of-the-box.

The next example is rich text editing, but with constraints on formatting. Sanity’s rich text editor is configurable and extendable. It also saves the text into a structured and syntax agnostic format called Portable Text, so that even if you had formatting that you didn't want in your presentation layer, it is pretty easy to ignore it in the implementation. A rich text field with only bold (or strong) italics (or emphasis) and linking looks like this:

// simpleRichText.js
export default {
  name: 'simpleRichText',
  type: 'array',
  title: 'Body',
  of: [
    {
      type: 'block',
      styles: [],
      lists: [],
      marks: {
        decorators: [
          { title: 'Strong', value: 'strong' },
          { title: 'Emphasis', value: 'em' }
        ]
      }
    }
  ]
}

Moving on, adding a description to the title field explaining it's used as the fall back SEO title, is also pretty effortless. And of course, you can have fields called title with different descriptions throughout the CMS:

{
  name: 'title',
  type: 'string',
  title: 'Title',
  description: `Used as the fallback if the SEO title isn't set`,
  validation: Rule =>
    Rule.min(10).warning('The title should be longer'),
}

The last example is affordances for grouping fields into tabs or sets to lessen the cognitive load. Sanity comes with fieldsets out of the box, and somebody has made a plugin that expresses these as tabs.

// article.js
export default {
  name: 'article',
  type: 'document',
  title: 'Article',
  fieldsets: [
    {
      name: 'meta',
      title: 'Metadata',
      options: { collapsed: true, collapsible: true },
    },
  ],
  fields: [
    // the fields
  ]
}

All in all, it seems like Sanity meets all the examples given for content modelling and the examples mentioned. And we've just scraped the top of the ice-berg of what's possible in terms of catering to an awesome editoral experience. Because, it's true as the authors write:

Cater to your editors. Implement your content model at a level that allows the CMS to help them. The happier they are, the better your content will be, and the longer your CMS implementation will last.

The Sanity Studio comes with a lot of field types out of the box, and lets you make your own custom input components if you have special data coercion needs, and as we touched on, you can do field validation with promises and JavaScript.

Aggregations

Since the underlying data for Sanity.io are JSON documents, that can be queried and join on pretty much any key/value the need to explictly author aggregation descreases (want an implementation to group any document that starts with "F" in it's title field (if it has one), no problem: *[defined(title) && title match "F*"].

But there are perfectly sound reasons to make explicit aggregations of content, so let's go through the different types mentioned by the authors.

A Content Tree

A very common pattern is a “tree” of content, where you have a "root" object with a hierarchy of descendants below it. Every object is a child of another object, and might have one or more children of its own.

As I previously mentioned, I'm not a big a fan of structure content deeply into a hierarchy. Soon enough editors are required to be “hiearchy janitors”, and there almost always comes a point where you want to break out of that hiearchy or do it differently. But sometimes you actually need to put content into parent-child-like structures where they also have order. For those times, I tend to make another document type with fields to express hierarchies.

A practical example is how the documentation and its table of contents is done on sanity.io/docs. The articles is a flat list of the article type, while the menu is made as a document type called toc (as in Table of Contents):

// toc.js
const tocSection = {
  name: 'toc.section',
  type: 'object',
  title: 'Section',
  fields: [
    {
      type: 'reference',
      name: 'target',
      title: 'Target article',
      to: [{ type: 'article' }],
    },
    {
      type: 'string',
      name: 'title',
      title: 'Title',
    },
    {
      type: 'array',
      name: 'links',
      title: 'Links',
      of: [{ type: 'toc.link' }],
    },
  ],
};

const tocLink = {
  name: 'toc.link',
  type: 'object',
  title: 'Link',
  preview: {
    select: {
      title: 'title',
      targetTitle: 'target.title',
    },
    prepare: ({ title, targetTitle }) => ({
      title: title || targetTitle,
    }),
  },
  fields: [
    {
      type: 'reference',
      name: 'target',
      title: 'Target article',
      to: [{ type: 'article' }],
      description: 'No target article turns the item into a subheading.',
    },
    {
      type: 'string',
      name: 'title',
      title: 'Title',
      description: 'Override title from the target article.',
    },
    {
      type: 'array',
      name: 'children',
      title: 'Children',
      of: [{ type: 'toc.link' }],
    },
  ],
};


const toc = {
  name: 'toc',
  type: 'document',
  title: 'Table of Contents',
  fields: [
    {
      type: 'string',
      name: 'name',
      title: 'Name',
    },
    {
      type: 'string',
      name: 'title',
      title: 'Title',
    },
    {
      type: 'array',
      name: 'sections',
      title: 'Sections',
      of: [{ type: 'toc.section' }],
    },
  ],
};

export default { tocSection, tocLink, toc };

This is a bit of code, but notice that this is also recursive, meaning that you can make sub-sections. We can also use Structure builder to query this structure and group the documents accordingly in other views, which also allows you to browse the same documents by different criteria depending on what you're doing.

This makes it very easy for us to both test and change the navigation structure if we want to. We could even A/B-test it, if we thought that was a good idea (probably not). Another nice byproduct is that since these are references, we can't outright delete an article that's put into a table of contents. So we keep content integrity even though this system doesn't “know” about its presentation.

Folders

Sanity doesn't have folders in the traditional sense, so folder like organization happens like the approach above. That being said, someone could totally make a folder tool to give people that affordance. But I'm not sure it's worth the time?

Menus or Collections

This is pretty much covered by the example above.

Tags or Categories

You can implement categories using the reference field, and you can get ad hoc tags via the string field:

// tags.js
export default {
  name: 'tags',
  type: 'array',
  title: 'Tags',
  of: [{type: 'string'}],
  options: {
    layout: 'tags',
  }
}

Aggregation as content model or as editor experience?

What I think it's good with the way we approach content modelling at Sanity.io is that aggregation can be done either as an implementation detail through queries, as a content model concern through references, or as a workflow mode through structure builder. And these can be done independently.

Content Rough-In

It sometimes takes a bit of actual building, and some back-n-forth to get the content model right. Preferably, you have done some prior work before diving into the technical implementation. That being said, it's so easy to iterate and test things out with the studio, that I often find myself just coding up fields while I discuss with my team how things should work. In that group there will be the ones who are actually making the presentation layer, as well as the people who will work with the content.

So although the authors explicitly state that the “rough-in” is not about migration, in my experience, if you go by a content-first approach, you'll almost always need to move some stuff around early on.

We always try to get real content into the system as early as possible. That's where the learning and the uncovering of the unknowns are. And almost always, you'll discover that you need to structure something differently or rename a field. That's where migration scripts or simply exporting your whole dataset and use find/replace-all and importing it again moves you along. Since your content comes as JSON documents, it's a cakewalk to migrate compared to SQL tables with join tables and whatnot.

Templating and Output

The authors does a decent job of exemplifying how you integrate your content using a template language. In traditional CMSs you'll get a built-in HTML rendering system, with a chosen templating language. With Sanity, the content will be available through APIs, which let you integrate with any front-end framework (and other things that's not even of the web). The approach is fairly similar though you'll have accessible “placeholders” (aka variables) that you can map out, iterate over, build logic from, and so on. The starter projects over at sanity.io/create will give you a sense of how it can be put together.

Templating languages

It's interesting that in the author‘s list of templating languages, there is a glaring lacuna: JavaScript (I guess there's a certain headless CMS blindspot here?) But common templating languages, or front-end frameworks in the JavaScript world are:

• React, and site-builders like Next.js and Gatsby.js
• Vue, and site-builders like Nuxt, Gridsome, and VuePress
• Angular, and site-builders like Scully
• Svelte, and site-builders like Sapper
• Node.js based site builders like 11ty which offer a range of templating languages

We are talking about some fairly large ecosystems here, and approaches like JAMstack, which has taken the idea of generating websites from content over APIs to the modern web.

The authors of the web project book also offer some reflections on using PHP directly to generate output (as the worlds largest CMS does, Wordpress) and why you wouldn't want to do that:

• Templating languages are “safer” in terms of not giving frontend developers powers to accidentally break the whole website
• Templating languages are usually simpler
• Generating output with full programming languages are “crude and unpleasant in most cases”

There are some sweeping generalizations here that I suspect many front-end developers would disagree with. Using JavaScript along with a templating language in React or Vue gives you both pleasant ways of building the markup, but also pleasant ways of building interactivity and managing state. Interactive user experiences is often a demand, which involves having to deal with state. Following the author‘s advice, you often have to tack that on after the fact, which can lead to breakage and messy projects as well.

If you use a modern site-builder like Gatsby, it will, in most cases, catch errors and tell you when you're rebuilding the site. And you will not be victim to closed database connections and rouge plugins typical for the CMSes that comes with built-in templating languages (yes, I know you can put caching layers onto those too).

There is no lack of testimonials of people that enjoy building the web using JavaScript, PHP (also using frameworks like Laravel), or whatnot. I don't think it's fair to say that it is “crude and unpleasant in most cases” anymore.

Other Development Tasks

Users, Groups, and Permissions

Although you can get pretty flexible access control, I prefer to emphasise trust and accountability when it comes to permissions for people who work with content. With great field description, and validation, and document actions, you can create affordances that remove bureaucracy while giving editors the safe-guards they need.

Workflows and Content Operations

Using features like Structure Builder and Document Actions you can create different groupings and sortings of your document, based on everything from what they contain to kanban flows, or even user-specific document listings.

Localization

With Sanity, localization is an aspect of content modelling, rather than its own dedicated feature. That's a bit unusual, but when you take a closer look it makes sense: It means that you're free to choose between field, document, or even dataset level localization (or a mix). It means you're able to combine personalisation (segmentation) and localization relatively easily (if you think of it, they're two sides of the same coin).

Marketing Tools

As mentioned above, you can write schemas that let you create specific content for specific groups or markets. You can use Sanity to handle routes on your website (or voice assistant or whatever), which can contain multiple versions of the same content and weights that your system for A/B-testing can use. You can also integrate with Mailchimp, Marketo, Hubspot, or Salesforce if you want to either push or pull content or data from those.

Page Composition

We tend to promote that you structure your content by not tying it to a specific presentation, but following the mental and operational models in your organization (hence, don't organize it in product pages, but as products). Hence, page composition (or layout) should be a concern of the presentation layer, in most cases, the frontend. Then again, the ability to build landing pages of different modules and content types is a frequent request. Dean and Corey remark in a footnote, that:

Dynamic page composition is exciting to see in a demo, but editorial teams usually never use it to the level they imagine they will.

I suspect that they have a point, then again, if you have a productive marketing team, chances are that you are making landing pages to improve SEO and Adwords campaigns on a fairly regular basis.

With Sanity, you can have page composition, while still keeping it fairly structured. If you build with a design system and create components and modules with a decent level of abstraction. The usual pattern is to create an array-field, and compose dedicated object types to it. You can try this simple example on sanity.io/create, where the field looks like this:

export default  {
  name: 'content',
  type: 'array',
  title: 'Page sections',
  of: [
    { type: 'hero' },
    { type: 'imageSection' },
    { type: 'mailchimp' },
    { type: 'textSection' },
  ]
}

And here's the field in actions, with an example front-end.

Watch on YouTube

Search, reporting, arching, integrations, and forms

The authors also mention search, reporting, archiving, integration, and forms. With Sanity, you can choose to integrate with search services like Algolia and lets you customize search inside of the Studio. Using Structure builder you can set up lists with custom filters that let you get an overview (aka report) of unused assets, or content with publishDate from last year, or whatever you need. You can even use the Google Analytics plugin to get a list of content with a high bounce rate, in order words, actually use that data for something actionable.

Sanity keeps the patch  history of your documents (like Google Docs) if you want to rewind and restore older versions. You can have an external archive by utilising the export endpoint if you prefer to delete documents, or you can add it as a boolean field and “soft delete” documents. Integrations are a huge topic, where the benefit of being real-time comes to shine: Set up services to path, augment and create content without having to deal with document locking on race-conditions.

If you need forms, you can do that too. Check out this example with Netlify, or this implementation that let's you use Sanity to also build forms that can be serialized and used in a frontend. This is the power of having versatile APIs, and being a content platform, rather than the old CMS conventions but with APIs and an webapp you can't customize as you need.

The big picture

I wholeheartly agree with Deane and Corey when they assert that “back-end and front-end implementations often run in parallel”. However, their following line isn't necessarily true longer, at leats not with Sanity: “There’s a lot that a back-end team can do before they need the front-end team’s output for templating.“

If you have empowered your frontend-team to pick modern frontend technologies, they can start building at any time. With Sanity, they will not strictly need a “back-end team” to get the content APIs they need on day 1. Your frontend developers can use the same skills as they do with the frontend. In fact, if you put your developers, your designers, and your content people together in a two hour workshop, they should be able to be working with real content with Sanity Studio, while setting up the shell implementation of the presentation layer, and start sketching out which components and modules that needs to be designed.

In other words, it's feasable to avoid having to coordinate “two teams”, but rather, have one team that works inter-displinary and focused on rapid and continous iteration. You still may need “back-end engineers” if you need to integrate with other services and back-office systems. They are usually happy because they don't need to deal with the CMS and get powerful APIs that makes their work pleasant.

And this is not just consultant speak or my content marketing. I have been part of these processes using other systems, but also Sanity. Rather, it's because this approach worke so well for me and my teams, I was happy to join Sanity.io to help other developers work better with content.

Knut 
06:42 i was hoping for Runtime Wrapped, @fil. Want to see how many recursions I caused.
06:43 "This is your year in stacks"
06:43 "Your favorite triggers are ['create', 'update']"

Fil 
06:43 can you imagine if your CLI tools did this kinda s**t

Knut
06:43 yes
06:43 i expect someone to

Fil
06:44 "you sent 1,300 POSTs with curl this past year!" f**k off
06:44 "you rage-typed sudo 100 times - you naughty boy!"

Magnus
06:44 "you still haven't learnt how to use tar I see"

Jack
06:44 npm wrapped: "you introduced 12,834 garbage transient
dependencies and caused your security team 14 different migranes"

Knut
06:45 knut from marketing here. i like this idea

Jack
06:45 :homer-disappearing-into-bushes:

Fil
06:45 ive made a terrible mistake

Then I thought: I could build that.

40 minutes later, I had a working prototype.

Watch on YouTube

A few hours after that, it had AI-powered roasts and shareable images. By the end of the day, it was on GitHub.

This is probably the best vibe coding experience I had so far. And I’m not sure how to feel about it.

Anyways.

Introducing CLI wrapped

CLI Wrapped reads your shell history and shows you stats about your year in the terminal: top commands, time patterns, git activity, typos, and those moments where you ran a command, it failed, and you immediately tried again with sudo.

Optionally, You can add an API key and have Claude roast you for each statistic.

It's a silly project. But the way I built it isn't.

Let's clear up the magic trick

When people hear "vibe coding" or "AI-assisted development," I imagine they often picture someone typing "make me an app" and watching code appear. That's not what happened here. That's also not particularly useful for anything beyond throwaway prototypes.

What actually happened was more like pair programming with a very fast, very tireless partner who happens to know every library and pattern but needs you to make the actual decisions.

The parts that stayed human

Before I wrote any code - or asked Claude to - I had to think through:

• What's interesting about shell history? Not just "most used commands" - that's boring. The fun is in the patterns: when do you code? What typos do you make? When do you rage-quit and try sudo?
• What should the experience feel like? I wanted it to feel interactive, one stat at a time, with personality. Not a wall of text.
• What about privacy? Shell history can contain secrets. If I'm sending anything to a third-party AI service for roasts, it can only be aggregate stats - command names and counts, never arguments or paths.
• What tech makes sense? Just copy the stack Claude Code uses. Bun for speed and simplicity. React with Ink for terminal UI (because I know React). Satori for shareable images.

None of these decisions came from Claude. They came from thinking about what would make this actually fun to use. (But we all know Claude could probably have figured out that too).

Claude's actual job description

Once I had the design in my head, I opened Claude Code (Opus 4.5) and described what I wanted. Not "build me a CLI tool" but something like: "I want to parse zsh history files, extract timestamps and commands, and calculate stats like most-used commands, hourly patterns, and common typos."

Claude planned the implementation, I reviewed the plan, and then it executed. When something wasn't right - and things weren't always right - I'd describe the problem and we'd iterate. I was acting as the project manager, telling it about the user experience I wanted, security concerns, compatibility for different shells, how to make as easy as possible to run etc.

Claude is incredibly fast at the mechanical parts of programming. Parsing file formats, wiring up components, remembering the exact API for a library I haven't used in months. The stuff that usually slows me down.

But it doesn't know what would be fun. It doesn't know that detecting rage-sudo moments is funnier than showing raw command counts. It doesn't know that the roasts should be sarcastic but not mean. That's taste, and taste is still human.

When the font file was an error page

It was actually the social image sharing feature where we had the most problems and it took some back’n’forth and tokens to resolve.

Error: Unsupported OpenType signature <!DO

That's Satori trying to parse an HTML error page as a font file. Classic. I had no idea what was wrong, but Claude figured out the font URL was returning a 404. Debugging was still debugging.

At some point I had Claude build more testing so it could do more of the debugging loops itself. Should have just had it do that from the start.

Real users find real bugs

Within minutes of sharing the install link, a colleague ran it and got this:

Daily Activity:

 Sunday                          0
 Monday                          0
 Tuesday                         0
 Wednesday  ████████████████████ 20 ← Peak
 Thursday                        0
 Friday                          0
 Saturday                        0

🔥 Most active day: 2025-12-17 with 20 commands!

His entire shell history was apparently 20 commands from that morning. Turns out his terminal was clearing history and he didn't even know it. This led to adding a FAQ section about shell history retention and checking ~/.zsh_sessions/ for macOS users.

The first version I shared also broke interactive mode entirely when run via the curl installer. It worked fine locally. The TTY handling was wrong. These are the kinds of bugs that AI doesn't magically prevent - you still ship broken things, you still get bug reports, you still fix them (or have the AI do it).

What Claude thinks I learned

I asked Claude to look back on this project and what we built and this is what it claims that I learned:

1. Design first, code second. The better I could articulate what I wanted, the better the results. Vague prompts got vague code. Doh.
2. Iterate in conversation. When something wasn't right, I'd describe why, not just what. "This works but it's not funny enough" led to better solutions than "change this." Doh.
3. Know what you're building. I could have built this without understanding React, terminal UIs, and API design. But I have a feeling that it turned out better because I did know things. So Claude amplified my knowledge; it didn't replace it. Doh.
4. Ship fast, then polish. The first version had bugs. I shipped it anyway, got feedback, and fixed things. The speed made that iteration loop possible. Doh.

All of these are true, and… bleeding obvious. Principles that have been rehearsed many times.

The knowledge that didn't stick

I don’t really know how to build CLI apps with Ink. I’m not better at hand coding images with React and Satori either.

What I actually learned

There’s one I thing that I actually learned, that Claude didn’t catch (well, how could it, since I didn’t tell it).

I did learn how to parse the history of different shells though, and how to change the retention. This was the part of the program I felt I had to review and understand to make sure it actually didn’t pass sensitive information

Velocity as feature

What made this different from side projects pre AI tools actually becoming good?

Normally, I'd have the idea, think "that would be cool," and then reality would set in. I'd remember I don't know the zsh history format off the top of my head. I'd have to learn how to build with Ink. I'd spend an hour just on setup. By the time I got to the interesting parts, my enthusiasm would be gone and I'd have other things to do.

With Claude, the gap between "I have an idea" and "I can see if the idea is good" collapsed. 40 minutes to a working prototype means I could validate the concept while I was still excited about it.

I think?

On the one side it’s fun to move at the speed of your ideas instead of the speed of your debugging.

But on the other side, I don’t feel super attached to this creation.

Your turn to feel weird about it

Here's the thing I didn't expect: I did make something. It works. People ran it, found bugs, I fixed them. That's real.

And yet I kept circling back to that feeling: not quite satisfaction, not quite disappointment. Something in between.

I realized: I build things because I learn through building them. Not just "how to use a library" learning, but the deeper kind: understanding why something matters, what makes it work, where the edges are. The kind of knowledge that mostly comes from wrestling with a problem yourself.

Vibe coding compressed that loop. I got the thing without the wrestling. And in doing so, I learned something I couldn't have learned any other way: that the wrestling is often the point.

The irony isn't lost on me: I learned this through vibe coding. I did learn how to use Claude Code better. I did learn about shell history formats and TTY handling, the parts I had to understand to trust the output. The tool taught me something by showing me what it couldn't teach me.

So is this good or bad? I don't know. It's fast. It's useful. It works. But it also reveals something uncomfortable about what we value in the act of creation and I'm not sure we've figured out what to do with that yet.

Dare try it yourself

If you want to see what your terminal year looked like. Just uncritically execute this code from the Internet in your terminal:

bash <(curl -fsSL https://raw.githubusercontent.com/kmelve/cli-wrapped/main/install.sh)

The code is on GitHub.

You should probably read through it (or have Claude do it) first.

And tag me (@kmelve) on social if you do!

I got started on my webmentions journey by reading Chris’ Building Gatsby Plugin Webmentions and Chad’s Embracing the IndieWeb. Both works were helpful to get started, but they left some details out that may have made it a bit easier to grok. I’ll walk you through all the steps, but do check out their stuff as well.

What is Webmentions?

You can read more about it on the IndieWeb wiki, but shortly put: Webmentions is an open source project and a service to send and receive messages and pingbacks between sites. Like we all did with Wordpress back in the day.

The difference are that Webmentions are federated, meaning that you can collect and send mentions from multiple sources. In this tutorial, I’ll start by pulling in twitter mentions via a service called brid.gy.

How to get started with Webmentions

To get started with Webmentions you need to sign in on webmention.io. And to sign in you need to authenticate. And to authenticate you need to put some markup on your Gatsby site that tells webmention.io which service it can use. As per instructions you can add the following using either Twitter, GitHub, email, your PGP key, or you own IndieAuth server. I added Twitter and Github:

<p>
  Follow <a class="h-card" rel="me" href="https://www.knutmelvaer.no/">Knut</a> on <a href='https://twitter.com/kmelve' rel='me'>Twitter (@kmelve)</a>, <a href='https://github.com/kmelve' rel='me'>GitHub</a>, or send him an <a class="u-email" href='mailto:knut.melvaer@gmail.com' rel='me'>email</a>
</p>

So this pretty much looks like your regular piece of HTML. If you look a little closer there is some rel="me" attribute as well as some class names (h-card, u-email). These are microformats (TK), which is an important part of getting webmentions to work. When you publish your site with this markup, you tell webmention that those social accounts are tied to whomever is control of the domain the site is on, and lets you log in via their oAuth-integrations.

As you can see in the figure above, I have a list of webmentions there that you probably don’t have (yet). We’ll return to how to get that list populated with stuff from twitter, but first, we have to add some microformats to our site, to make it webmention friendly.

Adding microformats2 to your posts

Webmentions use a specification called microformats2 to make sense of contents on a webpage. We’ve already started implementing it in the code snippet above. There’s a lot to microformats that I haven’t unpacked for myself yet, but it’s easy enough to get started. You mainly do so by adding some specified class names to HTML elements that have the specific content that webmention use to populate its fields. For example:

<article class="h-card">
  <header>
    <img class="u-photo" src="http://...">
    <h1 class="p-name">The Title</h1>
  </header>
  <p class="p-summary e-content">The summary</p>
  <footer>
    <a class="u-url p-name" href="http://...">The author</a>
  </footer>
</article>

You can use IndieWebify.me or pin13.net to validate your markup. I took a couple of tries for me to get it right. When a webmention service read your page, it will parse the HTML and extract this information into a JSON structure, that may look something like this:

{
  "items": [
    {
      "type": [
        "h-card"
      ],
      "properties": {
        "name": [
          "The Title",
          "The author"
        ],
        "summary": [
          "The summary"
        ],
        "photo": [
          "http://..."
        ],
        "url": [
          "http://..."
        ],
        "content": [
            {
              "html": "The summary",
              "value": "The summary"
            }
        ]
      }
    }
  ],
  "rels": {},
  "rel-urls": {}
}

I ended up implementing these “microformated” elements in my post template and hiding them with display: none. Mainly because I didn’t want an ISO8601 formatted datetime stamp visible on the site. I could probably have used a library like date-fns to format the timestamp, but this did the trick without any dependencies. This is for example how it looks in my Gatsby blog’s React code:

<time 
  className={styles.hidden + " dt-published"} 
  itemprop="datepublished" 
  datetime={publishedAt}
>
  {
    new Date(publishedAt)
      .toISOString()
      .replace('Z', '') + "+01:00"
  
  }
</time>

Now, let’s head over to the interesting part, namely, getting webmentions into Gatsby.

Installing gatsby-plugin-webmention

The easiest way to get webmentions into a Gatsby site is to install the gatsby-plugin-webmention plugin:

npm install gatsby-plugin-webmention
# or
yarn add gatsby-plugin-webmention

Now you can add the following config to the plugins array in gatsby-config.js (obviously replacing my information with your own):

{
  resolve: `gatsby-plugin-webmention`,
  options: {
    username: 'www.knutmelvaer.no', // webmention.io username
    identity: {
      github: 'kmelve',
      twitter: 'kmelve' // no @
    },
    mentions: true,
    pingbacks: true,
    domain: 'www.knutmelvaer.no',
    token: process.env.WEBMENTIONS_TOKEN
  }
}

The webmentions token is the one that you find under "API key" when you’re logged into https://webmention.io/settings. Remember to also add it to the environment where you build your Gatsby site to production (for example on Netlify). If all went well, you’ll be able to query your webmentions in the Gatsby GraphQL API.

In order to get page specific webmentions I did two things:

1. Generate and put the post’s URL into context from gatsby-node.js
2. Filter the allWebMentionEntry with the URL aka "the permalink"

There’s probably a handful of ways to do this, but I ended up with just generating the full URL in gatsby-node.js, and passing it in via context, so that I could use it as a query param:

postEdges
  .filter(edge => !isFuture(edge.node.publishedAt))
  .forEach((edge, index) => {
    const { id, slug = {}, publishedAt } = edge.node
    const dateSegment = format(publishedAt, 'YYYY/MM')
    const path = `/blog/${dateSegment}/${slug.current}/`

    createPage({
      path,
      component: require.resolve('./src/templates/blog-post.js'),
      context: { 
        id, 
        permalink: `https://www.knutmelvaer.no${path}`
      }
    })

    createPageDependency({ path, nodeId: id })
  })

And the GraphQL query:

allWebMentionEntry(filter: {wmTarget: {eq: $permalink}}) {
  edges {
    node {
      wmTarget
      wmSource
      wmProperty
      wmId
      type
      url
      likeOf
      author {
        url
        type
        photo
        name
      }
      content {
        text
      }
    }
  }
}

The properties of this query will be pretty self-explanatory when you start to get webmentions data. You can use it to list people who have liked, replied, or reposted your post.

The simplest way to get some webmentions going is to use a service called brid.gy to bring in mentions of your website on Twitter.

Connecting brid.gy

Head over to brid.gy and connect your accounts, I think Twitter makes the most sense, at least at first. Enable the listening for responses. There need to be some tweets that mention your site (by domain name) to there being responses. You can, of course, just tweet your self to get something going.

If you (re)start your Gatsby site in dev mode, you’ll be able to see the same response data in your GraphQL layer. This will make it a bit easier to implement in your frontend template.

Implementing webmentions in your Gatsby frontend

I’m not going to cover much detail here, this is the creative part! It’s pretty much straight forward though. For example, to filter out all the "likes" and show some avatars with links to the "liker", you can do something along these lines (not saying that this is the definitive way to do it):

import React from 'react'

export default function WebMentions ({ edges }) {
  const likes = edges.filter(({ node }) => node.wmProperty === 'like-of')
  const likeAuthors = likes.map(
    ({ node }) => node.author && { wmId: node.wmId, ...node.author }
  )
  return (
    <div>
      <h4>
        <span>{`${likes.length} likes`}</span>
      </h4>
      <div>
        {likeAuthors.map(author => (
          <a href={author.url}>
            <img alt={author.name} src={author.photo} key={author.wmId} />
          </a>
        ))}
      </div>
  )
}

You can use this component where you query for webmentions, by sending the allWebMentionEntry object into it <WebMentions {...allWebmentionEntry} />.

Triggering a new build on a new mention

If you’re like me, you’re impatient and want new mentions to appear when they happen. If you are patient, you can be satisfied by having the new mentions appear whenever you rebuild your site. But if you host your Gatsby site with let's say Netlify, you can use a build trigger to automatically rebuild the site, querying the newest mentions. First, you’ll have to add a new build trigger on Netlify. Copy this, and head over to the webhooks settings on Webmentions. Paste the Netlify URL into the box (no secret is needed), and hit save. And that’s it! (I realize that we can do some interesting things with this webhook, but we’ll revisit that in a later post.)

I would also recommend setting up some build notifications on Netlify so that you can keep an eye. Especially if you’re actually putting some content from the webmentions on to your site. This would be the time I told you that you can delete webmentions, and add someone to your blocklist if this is needed. Hopefully, it will not though.

Congratulations, you’re now a bit more indie!

There’re still some pieces left to the puzzle. We haven’t set our site to send webmentions or pingbacks yet. And there are more sources than Twitter that we can draw from. I’ll surely return with more fun IndieWeb + Webmentions stuff though. Meanwhile, feel free to reply to me on twitter, or even try webmentioning this post if you have constructive feedback. I’ll happily amend this post and follow up with useful insights.

I have nothing but respect for those who contribute to the MDX ecosystem. Also, I'm totally the type of person that would love MDX. I have been writing in Markdown since 2004, and one of my first GitHub projects was a jQuery based markdown-footnotes plugin for Wordpress (jeez louise don't use this!). At university, I had a whole multimarkdown-to-LaTeX setup in Sublime Text with pandoc, BibTeX, and PDF preview with Skim going for me. It was kinda great (at least for the two weeks the setup worked)

I don't think MDX should be “considered harmful”, nor that everyone should stop using it. But I think there are some things worth considering before locking your, or rather, others’ content to it. And I'm writing this knowing there might be things I've missed or not considered. Feel free to respond to me with your own blog post, or on twitter. I don't think this is the hill I want to die on though. So I'll allocate no more than 3 hours to follow up on this discussion. Use them wisely.

With that out of the way. Let's jump into this. 🏊

What is MDX?

If you go to mdxjs.com it self-defines as “an authorable format that lets you seamlessly write JSX in your Markdown documents.” For those not in the know, JSX is “an XML-like syntax extension to ECMAScript without any defined semantics.“ (at least as proposed by the draft specification). In order words, MDX, that is, the MDX precompiler, lets you combine the templating syntax usually found in React.js projects with Markdown. It looks something like this:

# Hello, *world*!

Below is an example of JSX embedded in Markdown. <br /> **Try and change
the background color!**

<div style={{ padding: '20px', backgroundColor: 'tomato' }}>
  <h3>This is JSX</h3>
</div>

It may look like HTML, because it does, but it's JSX. The intriguing part with MDX, but also the… uhm… problematic part, is that you can do stuff like this:

import { Button } from './Button'

# Hello world

Hello, I'm still a mdx file, but now I have a button component!

<Button>Click</Button>

(example from the docz.site)

Yep, you can import JSX components and embed them with your run-of-the-mill Markdown prose. If you're documenting your JSX based component library, which is what Docz let you do, this makes all the sense in the world. MDX is also used to author slide decks in mdx-deck, which is very appealing if you're tired of clicking around in Keynote/PowerPoint/Google Sheets. Which many of us are. I'm not denying the appeal or usability of MDX for certain things for certain people.

From a React developer’s standpoint that it's used to writing JSX, MDX seems to be touching on the ethos of Markdown, at least as John Gruber, it's original creator, introduce it on daringfireball.com:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Markdown has always allowed inline and block-level HTML to express things outside of the syntax. Because HTML was the end product. In that way, MDX isn't much different. Markdown's key feature though is "easy-to-read, easy-to-write". I'm not sure if MDX keeps within, or moves away from this general intent.  Gruber made a syntax that was easier to read and write for anyone not familiar with HTML. I'm not convinced that JSX solves the same problem.

What is the problem MDX tries to solve?

Markdown was designed at a time where most of the web authoring was still done in HTML. It was also designed when web content was mostly text and images. This isn't the case anymore. Web content has moved towards a much richer set of components, from embeds to interactive codeblocks, to between-paragraphs call to actions.

MDX seems like an attempt to make these components available to the author in the same syntax used in frontend development (well, as long as your frontend development uses JSX). And that's pretty much it. I think.

But this problem has been solved already. With something they call “rich text editors.”

There's plenty of content platforms with plenty of rich text editors that spew out plenty of different formats, including markdown, HTML, and abstractions as MobileDoc and Portable Text. Medium gained popularity thanks to its smooth authoring experience, Notion now seems to have taken over that hype. Void of HTML and Markdown (well, markdown-like shortcuts works, but is not a requirement), but with rich embeds. Arguably, these interfaces are more friendly and more accessible than learning Markdown, or MDX.

There had to be at least one reason for Slacks introduction of a rich text editor, yes, it wasn't very well executed, and we got Markdown back (I actually got used to the RTE), but I suspect they actually attempted to solve real user experience problems: Not everyone wants to learn Markdown.

Hey, I'm writing here!

I have written React for 20 years (that's recruiter for “since 2015”). I should know how to use my keyboard to paint beautiful JSX components with some lovely props and all that. But for some reason, when I have been made to write MDX. It. just. doesn't. work. I mess the syntax up all the time. Forget that I can't actually be writing Markdown inside of an MDX component (without wrapping it in some MDXprovider something). No syntax highlighting (this may have changed at the time you read this). No helpful error to actually point out where I forgot to close that component. Yeah, I know, but I was really supposed to be writing. Not doing debugging of frontend code.

And yeah… speaking of those components. Most times I had to use MDX, it was to contribute to someone else's documentation. So that means that I had to actually look up a bunch of documentation just to make a code example or a “note”. Sure, I could just TK'ed those parts (and I did), but again, it feels unnecessary for doing something that could be seamlessly solved with a text editor.

This is my totally subjective experience, but for now MDX is introducing a level of friction that I'm not really ok with when I'm writing. This takes me to the next section. Other people!

So, are we expecting people to use this?

I generally have hesitations dividing people into “techies” and “non-techies” (I can be persuaded if you actually identify as a Luddite). But I have been through enough projects as a consultant and have been through enough user tests to be very careful in forcing even Markdown on people who go to work to do content. Writing with a markup syntax should be opt-in, not forced upon you.

You expect a person who probably already have too much stuff to do, to:

1. Learn Markdown
2. Then learn MDX/JSX and imports
3. Internalize your component system (that never changes, right?)
4. Work with plain files
5. Use git or whatnot to actually get the stuff where it needs to go
6. Ask you how to troubleshoot their texts when it gets borked

Sure, you have managed to persuade your client to do it and that's jolly good. But I know that for most people that don't share our coding interests, this will not fly. Not the bit. Also, you're asking them to put their content into a certain format that arguably marries it to presentation. That's probably OK for a slide deck, but less OK if that content is actually describing something of value inside of your organization.

And it has nothing to do with people being "technical" or not. Most content people I know can spot an apostrophe from a grave accent after two jaegers after a seminar. They know how the syntax works. At least some of the time. It's about what we can reasonably expect people to have to deal with. Should they be learning to write JSX components, when frankly, that's your job?

“But Knut, I have this client and they love it”. Sure, that's great for you and your client! But now you have another challenge. That client may want their content elsewhere. Or well, redesign their site the year we all do everything in WebGL. Or they just want to switch out their design system with new components. Yes, I know you have an AST. But you know what's better than an AST? Not to have to use an AST.

Because it's not only moving between formats and languages, it's also how you actually structure your content by what it means, and not after the whims of a specific presentation.

You can't unmix cake

I work for a company that promotes structured content, so you should see this coming from a mile away:

For most uses of MDX, you will end up mixing specific presentation concerns with your content. This is not great.

Yeah, it kinda worked for HTML. Until something called iOS came along. And then you had an icky problem. Sure, you could parse it. But have you ever tried to parse real-world HTML? You probably rather spend your afternoon on something different.

For people working with content strategy, content is best stored as ingredients from which you can bake the things that you need when you need it. They have been preaching “structured content” for ages and fighting with CMSes that force content into WYSIWYG page builders and make editors copy-paste their texts around in small layout boxes prisons.

Yes, technically you can be really semantic with MDX too. Compose your components to be great meaningful abstractions, not get tempted to use that style attribute, and keep everything neatly separated in their own documents. But there's little in the design and practice of MDX that promotes this use. It is promoted as a way to build rich visual presentations.

Sometimes you want to make a cake, and that's fine. But you should think really hard if you could feed a lot more people for a lot less effort if you hadn't made the cake in the first place. Ok, this metaphor is pretty tired now. The point is: You should think really hard about how you want to be able to work with your content, the inclinations of whom you want to work with your content, and finally, how sustainable and flexible your structuring of it is.

The obligatory section where I try to sell you our thing

I get it. I get the tangibility of flat files. I get that it feels good to take your coding skills into your prose. But it's not the best way to work with content. Text editors with familiar affordances that produce typed rich text that can be queried and serialized into whatever you need are better. Where developers can define the data structures they need, and editors get easy-to-use tools to get their work done. Like what we're building at Sanity with Portable Text.

But it doesn't even need to be Sanity. After we launched with Portable Text, others have recognized that storing rich text in JSON structures has its advantages. No, you will never want to actually read or author the JSON, but you shouldn't need to. That what's React and JSX are best for. Namely, building the editorial experiences that don't come in the way of writing. That can be reused across frameworks, programming languages, and redesigns.

Closing remarks

(take a minute to appreciate that subtle pun)

With that out of the way, let me reiterate that I don't want to knock the people behind MDX and adjacent technologies. It obviously brings some people joy. You shouldn't feel bad for using it either, but now at least you have some counterpoints to make better decisions from. Maybe someone gets inspired to prove me wrong and make a structured content pattern library for MDX. That would at least be something. Or use some of my aforementioned allocated three hours of discussion time to tell me everything that's wrong with the Portable Text specification (I welcome it actually if it can make it better).

But do make sure you have considered if MDX solves the problem you really should be solving, or if it only tickles your developer fancy.

Since people kept asking me about how I did the webmentions stuff, and the twitter stuff, and the statistics stuff, I decided to make it public. So I did clean up the code a bit and added a disclaimer in the README.md.

To deal with the “there might there be secrets” situation, I used a handy little command line tool called BFG Repo-Cleaner. It goes through all your commits in all your branches and rewrites history to not the include the file you wish you hadn't commited:

bfg --delete-files .env

Afterwards you can git push --force to overwrite the history stored on GitHub.

To install BFG, you can follow the installation instructions, or if you are on macOS and have Homebrew installed (as you should), you can run:

brew install bfg

Where was I at the end of 2018?

Since I didn't write a retrospective last year, I'll have to construct one. At the end of 2018, I was looking back at a year where I moved from the western to the eastern part of the country, close to Oslo, Norway’s capital city. I had also changed jobs, ending my three-year tenure as a technology/UX consultant at Netlife, and starting as Head of Developer Relations at Sanity.io. It was the year where I finally sought professional help for my recurring depressions and got a new Whippet puppy.

How did I do in 2019?

I didn’t blog any goals in 2019, but there were some that emerged during the year. It became increasingly clear to me that I needed to improve my work-life balance, invest more in my personal relationships, and be more structured and focused on how I approach my work.

Work-life balance

I think of this a lot. And frankly, it’s complicated. I think we shouldn’t expect people to put in more than 40 hours a week, while I often do work more myself because I enjoy it (not because it’s expected of me). Setting boundaries is important though. During 2019 I have managed to develop the habit where I mostly manage to take weekends and holidays completely off in terms of typing on keyboards. Since a lot of my work involves staying on top of social media accounts, and the developer community, it’s hard to stay completely out of the loop, so I’ll still be checking in more or less frequently, but not participating. Deleting Slack from my phone and keeping my laptop closed and out of the way have been effective measures keeping me from “accidentally working” during my vacations. During longer periods of spare time, I keep catching up to a minimum, once in a day or a few.

On the other side: It’s fun and exciting to work at a startup like Sanity.io, especially because I thrive on learning new things and putting out stuff. There’s also always something to do. And even though I’m regularly reminded to take time off and not work too much, it’s hard not to when you’re motivated. There’s no lack of advice against burnout out there, and having previously experienced it in my past life as a Ph.D. student, I’m well aware of the mechanics. At the same time, I’m super privileged working with something I enjoy every day, and in a welfare state that gives me a lot of existential security.

More focus, more structure

A big change for me in 2019 is how I approach creative work. Previously, the process for me has usually been coming up with something based on some inspiration or idea that hit me, acting on it immediately, and getting it out. I was afraid that if I waited to act on an impulse and not get it out relatively fast, it would wither away. Although this approach has in many cases worked very well for me, it doesn’t scale well. Especially if you’re trying to do stuff more strategically with other people.

So the two things I have practiced a lot and got better on during 2019 are planning and prioritization. An important note is that I don't do this to be more productive in terms of more output, that was never the problem, but because I wanted to spend my time on the right things (or the things we wanted to check were the right things). In a way, more focus and more structure will enable me to work less and get the same amount of things done.

I really got to put my goals to the test when we planned a pretty hefty release schedule for November and December. If I hadn't been diligent with planning and prioritization, I wouldn't be able to get stuff done. The proof is in the eating (and also making) of the pudding, as they say.

Mental health and personal relationships

I also spent 2019 trying to take better care of my own mental health and paying more attention to my personal relationships. It hasn’t been just smooth sailing. I have lived with recurring depressions pretty much my whole adult life and it took a long time before I recognized what was going on. After I sought help I have been able to more quickly identify when depression hits, and I have been able to curb a lot of the behavior that comes with it. Cognitive Behavioural Therapy has worked for me, but it’s only one way to go about it. I started going to a therapist again. I’m generally doing fine, but I don’t want to get blindsided by depression again.

I have started dedicating more time and attention to the people around me: family, and friends. I realized how I avoided contact because of my own insecurities, and how I haven’t really been present when I have been around them. In 2019, I actively sought out contact and practiced being more present, open, and forthcoming. Although this has been generally a positive turn, I have also had to work with some difficult stuff in my close family that is still unresolved. I guess that will spill over as a goal for 2020.

What’s up for 2020?

I don’t think I’ll set some big life-changing goals for 2020, but rather, continue working with the goals that emerged in 2019.

• Work-life balance. Take care of our horses once a week (my partner does it for the rest of the week). Plan more hiking trips during summer. Uphold a minimal physical exercise regime. Do more with friends and colleagues outside of work.
• More focus, more structure. Practice saying “no” more. Be more diligent about putting plans to paper. Write more about what I learned about how to work (in order to “slow-think” it).
• Mental health and personal relationships. Practice recognizing negative thoughts and identifying techniques to prevent them. Be more open about how I’m actually doing to those close to me. Prioritize time with family and figure out how to be an uncle.

Looking at what I ended up writing, it hits me that all this is probably pretty demographically typical for a person in the 30s living in the democratic West. Of course, there’s a bunch of goals and ambitions that pops up when you start thinking about them, but I’ll put them on the backlog for now.

What about you then?

There seems to be no lack of people with advice and tips on self-improvement. My main source of inspiration is the Back to Work podcast with Dan Benjamin and Merlin Mann (which is way goofier than the wrapping may seem). The aforementioned Jason Lengstorf also has some resources for you in his blog post. Wherever or whoever you get inspiration from, taking the time to reflect and write about where you have been and where you want to go seems like a no-brainer. Whether you want to share it with the world, is entirely up to you.

– “I’m non-technical, so this solution doesn’t seem for me.”

– “We need to communicate to the non-technical people too.”

My “non-technical” liberal arts education would have set me up to interpret these statements to be about Luddites: protesters who denounce technology, worried that we will become slaves to the machines.

However, it’s rarely people who are prone to break your laptop in protest that’s subject to the category of “non-technical.” More often than not, it’s people that have the same expensive phone and laptop that you have. People who use e-mail, word processors, apps for all sorts of things, spreadsheets, robot vacuums, cars, and whatever back office system they have to endure at their work place.

Yeah, you probably see where I’m going with this. I don’t think the term “non-technical” is particularly helpful: Not as a self-description, not as a persona, and not as something we use to characterize other people.

In fact, to label people as “non-technical” is probably reinforcing stereotypes and implicit ideas of power. On the flip side of this label, we are giving a particular agency to the people who make software with code while stealing it away from those who don’t.

I often observe this self-description used about in a slightly self-deprecating manner: “Yeah, I don’t understand this; I’m non-technical.” If you say this about yourself, why should you be expected to have opinions and critical questions about whatever “technical” go on? In most cases, the other party hasn‘t employed enough care or empathy to jump out of their specialized lingo to communicate what‘s at stake.

And when we use “non-technical” to decide on our communication strategy, does it help us? I suspect that it most often means that you need to communicate less about the particular features and implementation details of whatever you’re selling and more about the problems that are representative of a wider group of people to whom you’re trying to sell. In probably all cases, you could say “value-based” or “customer-centered.”

Not understanding much from an article about the particularities of TypeScript’s interface for polymorphic arrays doesn’t make you more “non-technical” than not having read a tome by Tolstoj makes you illiterate. And not (yet) knowing how to program doesn’t make you less technical, as not having crawled over the English channel doesn‘t make you less of a swimmer.

I’m fairly confident I could get you started with programming in less than a day if you don’t know it already. Because you’re already “technical.” You are so technical that you already know many operational metaphors and models that go into coding. There is nothing in programming you that’s beyond you if you can read this blog post. Sure, it takes time to learn patterns, particularities, and the ins and out of debugging. Sure, some people are more and less motivated by it.

There is an important difference between assuming that you are intrinsically not able to use or understand tech and being inexperienced with certain technologies.

So I hope you think twice about what you mean the next time you reach for “non-technical” to denote someone or yourself. Who are you giving power to in the situation?

I keep seeing new ones pop up. Not just the recent WordPressesque EmDash launch by Cloudflare; if you go to Reddit’s, you’ll see that every other week someone announces a smol CMS that sits on top of some markdown files aside a web framework or sticks content into the database-service-in-vogue.

And what I’m seeing in the conversations around these, including WP Matt’s… feedback to EmDash, is that most devs are an obsession with where you can host the CMS. While I totally get the concern, worries about lock-in and wanting to deploy something into infra that you like to work with, I think the focus explains why a lot of these CMSes^[1] don’t scale well.

I’m not talking WordPress running on a Raspberry Pi not tackling inbound traffic type of scale, but scale in terms of the complexity of your content domain and the teams who are supposed to be productive with it.

A lot of CMSes, including well-established ones, starts to crackle and crumble when you throw complexity at them. When a second editor joins, when a third team needs the same content in a different format, when an AI agent needs to operate the system on behalf of someone who's never seen the admin UI. A CMS that works for one developer editing content alone is a database with a form. A CMS that works for a team, across channels, with agents in the loop, is a different kind of system entirely.

These things is what I immediately see whenever I give a CMS a spin. And I thought I should write them down as a framework for how you should approach these systems, both in evaluating and making them. I’m starting with the laws for developer experience. There are different laws for editors and for agents. Those are separate posts. (Yes, I'm committing to writing them. Hold me to it.)

A declaration of bias

So before diving in I need to address the cloud-sized elephant in the room. I work for Sanity, who has been making a content operating system for the last almost 10 years. You can read these rules as self-serving, because Sanity hits most of these (still plenty of room for improvement though).

But having a bias doesn’t mean you’re wrong. I’d argue, that my work at Sanity has given me plenty of real-life experience to talk with some authority on these things. And hitting a lot of these points where the point I started using Sanity in the first place, and eventually started to work here.

I have seen these patterns play out in practice for two decades. I've been shipping WordPress sites since 2005, worked with a wide array of CMSes as a consultant in a lot of different sectors, and over the last eight years at Sanity, I've seen implementations ranging from single-developer side projects to Fortune 50 enterprises.

The laws I keep seeing come into play are the same ones regardless of scale. They just hurt more as the team or content complexity grows.

I. Your content model belongs in code

Content models defined in code can be version controlled, reviewed in pull requests, tested locally, and generated by AI coding assistants. Content models defined in a UI can't.

This matters more now than it did five years ago. Sure, AI agents can technically click through admin interfaces (computer use is a thing). But it's slow, brittle, and burns tokens on pixel-parsing instead of actual modeling work. When your schema lives in code, content modeling becomes a development workflow: describe what you want, the AI writes the schema, you test it locally, you open a PR. When it lives in a database behind a UI, the agent spends its time navigating forms instead of solving your content modeling problem. Same outcome, ten times the cost.

If you can git diff your content model and an AI assistant can generate a working schema you can test locally before it touches production, you're in good shape. If your content model lives somewhere you can't version or diff, you've got a problem that only gets worse with scale.

II. "Page" is a content type, not an architecture

The page-centric content model is so sticky, which is understandable, but it’s the main reason folks get stuck in their CMS down the line. A CMS that organizes content around "pages" and "posts" bakes a website assumption into the data layer. That assumption breaks the moment content needs to go somewhere without a URL. Heck, it even starts to break down when you want to reuse content within a website.

Content flows to websites, apps, APIs, email, voice interfaces, and destinations that don't exist yet. And increasingly, it flows to agent contexts: an AI assistant that needs your product specs to answer a customer question, a translation agent that needs the raw content without layout markup, a personalization agent that needs to assemble content from multiple sources into a single response. None of these consumers think in "pages." A hotel description isn't a "page." A product with three pricing tiers and regional variants isn't a "post." If your CMS makes these feel like awkward afterthoughts, the architecture is page-centric. You've coupled your content to one presentation context and now every other context requires workarounds.

Try modeling content that has no URL or route. Products with variants. Configuration objects. If these feel like hacks in your CMS, the architecture is page-centric and you'll be fighting it on every project that isn't a blog.

And that takes us to the next law.

III. Your content model should be as expressive as your domain

If you're flattening your business domain to fit the CMS, the CMS is the bottleneck.

A CMS that ships with text fields, number fields, image fields, and maybe a "JSON string" field covers the basics. But real domains are messier than that. A product with variants, each with its own pricing tiers and availability rules. An event with sessions, each with multiple speakers who are also authors on your blog. A landing page with a flexible layout where marketing can mix hero blocks, testimonial carousels, and pricing tables in any order. These aren't edge cases. They're "someone's just trying to ship on a Tuesday" jobs-to-be-done.

This goes for rich text too. Rich text stored as HTML couples content to a presentation format. Sure, agents can read HTML. Humans can read assembly language (well… some). That doesn't make it the right abstraction. Can you query which documents contain a specific block type? Can you validate that every "callout" block has both a title and a body? Can a translation service process it field by field without accidentally translating your CSS class names? (Yes, that happens.) Structured rich text (typed JSON blocks, like Portable Text) makes content queryable, "validatable," and transformable at the field level. HTML makes all of these harder than they need to be.

What about Markdown?

Here's the thing though. There's a real tension with how AI agents work today. Agents are great at reading and writing markdown. It's their native I/O format. So the tempting conclusion is: just store everything as markdown. But markdown as an I/O format and markdown as a storage format are different things. Agents can use serialization libraries (like @portabletext/markdown) to convert between structured formats and markdown on the fly. Your storage layer should be optimized for querying, validation, and multi-channel delivery, not for what's convenient for one type of consumer. Let the agent translate at the edges.

When the content model can't express the domain, developers build workarounds: JSON blobs in text fields, naming conventions to fake relationships, HTML strings where structured blocks should be. Every workaround is technical debt that compounds. And flat models limit what AI can do with your content. A schema-aware AI that understands field types, relationships, and validation rules can do meaningful work. An AI looking at a bag of string fields can only guess.

Try modeling a product with variants, each with pricing tiers, or a page with a flexible block layout. Then try querying "all documents where the body contains a code block." If you're reaching for workarounds at any of these steps, the content model is too shallow for the domain it's supposed to serve.

IV. If you can't do it with the API, it's not really a feature

An API is only as good as what you can do with it programmatically. If core operations (create, validate, publish, set references, bulk update) require a browser session, your API is incomplete.

This was tolerable when only humans used the CMS. It's not tolerable when AI agents, MCP servers, CI/CD pipelines, and automation workflows all need programmatic access. Every feature locked behind a UI is a feature that can't be automated, can't be tested in CI, and can't be operated by an agent.

I’m often surprised when I see the limitations that headless CMS vendors put on their APIs outside of the content delivery. Rate-limits that makes it practically hard and painfully slow to do anything meaningful in terms of bulk operations, or simply locking functionality to the UI not making the underlying APIs available for their customers.

You also see this in the "bring your own AI" pattern: a thin wrapper around OpenAI where you bring your own API token, then figure out how to make the AI service work with your content. If the CMS had a complete API, the integration would be straightforward. The wrapper exists because the API doesn't.

Picture an AI agent with no prior knowledge of your CMS trying to create a document, update its content, validate it, and publish it, all programmatically, without a browser. If that workflow hits a wall anywhere, your API has gaps that will show up in every integration you build from here on out.

V. You need a query language, not just endpoints

REST endpoints for basic CRUD aren't enough for content retrieval, and they're barely enough for updates. Especially when you move beyond the page-constrained content model. The moment you need to filter documents by type, project specific fields, resolve references, sort by date, or paginate results, you need a query language. And the moment you need to update a nested field three levels deep without replacing the entire document, you need a patch language too.

Without a query language, every query pattern requires a different endpoint or a different piece of custom code. Sure, an agent can write that code cheaply now. But every bespoke endpoint is a separate thing the next agent (or developer, or integration) has to discover and learn. A query language gives every consumer of your content, whether it's a frontend, an agent, or a third-party integration, the same composable interface. "All articles by this author" and "all articles tagged 'architecture'" are two filters on the same query, not two different code paths.

A query language also lets agents explore your content without knowing the schema upfront. "What types exist? What fields do they have? Show me the five most recent documents of this type." REST endpoints only answer questions you've pre-built answers for. A query language answers questions you haven't thought of yet.

GraphQL, GROQ—heck, even SQL—,or something else entirely. The specific language matters less than having one.

You should be able to sit down (or hand it to an agent) and do a single query that filters by type, resolves references^[2] two levels deep, and projects only the fields needed, without writing backend code or hunting for a custom endpoint. If that's not possible, every new consumer of your content starts from scratch.

VI. Every system output is agentic developer experience

Error messages, CLI output, validation feedback, API responses, log lines. Every piece of text your system produces is a UX interaction. And in the age of agentic development, it's also an instruction to the agent working on behalf of your user.

There's a standard for API errors: RFC 9457 ("Problem Details for HTTP APIs"), around since 2016. A type URI for stable identification, a detail field for this specific occurrence, extension members for context. Most APIs still don't implement it.

But it's not just errors. What does your CLI print when a developer runs --help? What does your dev server log on startup? What does your validation return when a required field is missing? Every one of these surfaces is a place where your system can guide both the developer and the agent. An agent hitting 400 Bad Request with no body will retry, hallucinate a fix, or give up. An agent hitting a structured error with available options and a documentation link will self-correct. Same failure, wildly different outcome. I wrote about this in more detail in my post on agentic developer experience.

Intentionally break something and see what happens. Does the output tell you how to fix it, and does it give enough context for an AI assistant to help debug? Then check your --help text and your startup logs while you're at it, because those are just as much a part of the developer experience as the error messages.

VII. Your content needs a history

Who changed what, when, and why. Rollback. Diff between versions. Audit trails. These aren't premium features. They're the foundation of trust between your CMS and everyone who uses it.

Content versioning matters for everyone because it's the safety net for every other operation. Schema migration went wrong? Roll back the content. Bulk update hit the wrong documents? Restore from history. Agent made a bad edit that made it to prod? See exactly what it changed and undo it. Without versioning, every destructive operation is permanent, and every automation is a risk.

Git ain’t it

"But I have markdown files in git." Sure, and git gives you file-level history. But content versioning is a different problem. Rolling back one field on one document while everything else stays live. Seeing which agent changed which field at 3pm. Branching content for a scheduled release without affecting what's published now. These are content operations, not file operations. And in practice, agents struggle to keep content consistent across scattered markdown files in ways that structured, schema-aware storage simply doesn't allow.

This is where vibe-coded CMSes show their broken seams the fastest. Versioning is boring infrastructure work. It doesn't show up in the demo. But the first time someone accidentally publishes a draft, or an agent overwrites a field it shouldn't have touched, or a migration corrupts 200 documents, you'll wish you'd built it first.

Make an edit and see if you can tell what changed, who changed it, and whether you can roll back to the previous version without losing anything else. Then try doing that programmatically, not just through the UI. If you can't, your versioning is a feature checkbox, not an actual safety net.

VIII. Content operations need to work at scale

Retagging 5,000 articles. Translating 200 documents. Migrating between schema versions. Backfilling a new required field across your entire content library. These are the operations that reveal the truth about your architecture.

If single-document operations work but thousand-document operations hit timeouts, rate limits, or data corruption, the system was designed for manual editing. That was fine when content operations were a human clicking through documents one at a time. It's not fine when an AI agent is processing your entire library.

AI makes bulk operations the default workflow, not the exception. A translation agent processing every document in your CMS. A metadata agent backfilling tags based on content analysis. A migration agent restructuring schemas across thousands of documents. These need to work as reliably as single-document edits, and they need to work while humans keep editing. If your bulk operations lock the system or require downtime, you've built a bottleneck into your infrastructure.

Try updating a single field across 1,000 documents and see what happens. If it works, check whether editors can keep working while the operation runs. If it times out, or if you have to take the system offline to do it, the architecture was designed for one person clicking through documents, not for the workflows that are quickly becoming the norm.

IX. Type safety from content model to component

Your CMS should generate types from the content model. The developer's IDE should know that a "blogPost" has a "title" (string), an "author" (reference to "person"), and a "body" (portable text). Not any. Not Record<string, unknown>. Actual types.

This applies to query results too, not just document shapes. When you write a query that projects three fields and resolves a reference, the return type should reflect exactly that: those three fields, with the reference resolved to its actual type. If your query language and your type system don't talk to each other, you're back to casting everything to any and hoping for the best.

Without codegen, every content access is a runtime gamble. A field gets renamed in the CMS, and the frontend breaks silently. A required field becomes optional, and the component crashes on null. These bugs are invisible until production and tedious to debug. (Ask me how I know.)

Type generation from the content model closes the loop: the schema is the source of truth, the types are derived, and the compiler catches mismatches before they ship. This is table stakes for any typed language ecosystem. Your CMS should participate in it.

Try renaming a field in your content model and see if your IDE lights up with errors in the components that reference it. Then write a query that projects three fields and check whether the result type reflects exactly those three fields, before you deploy. If the answer to either is no, you're flying blind between your content layer and your frontend.

X. Your content should be more portable than your platform

Your content will hopefully outlive your current tech stack. It will outlive your current framework, your current hosting provider, and probably your current CMS. The question is whether it can leave cleanly.

I can’t fathom (well, maybe a little bit) how much money has been billed on just the moving content from one system to another throughout the years. Very often, it was way less hard to just scrape the website, than get it out of the underlying DB.

Yes, this is one of the things that is now more approachable with AI, but storing your content in presentation formats like HTML is still a waste of time and tokens, and it makes the implementation in modern web frameworks weird and limited.

Po(r)table content in proprietary pots

This is about content portability, not platform portability. A hosted CMS can be perfectly fine. The question is whether your content is locked into a format, a schema representation, or a query pattern that only works with that one system. Can you export your content as standard JSON? Can you access it through standard protocols? Can you switch frontends without migrating content? Can you add a mobile app without duplicating your content layer?

The flip side matters too: can you bring content in? If migrating to your CMS requires a six-month data transformation project, the lock-in works both ways. Good content portability means standard formats in and out, APIs that don't require proprietary clients, and content that's structured enough to be useful outside the system that created it.

Export all your content and see if another system can read it without a custom parser. Try switching your frontend framework without touching the content layer. If a new integration protocol emerges next year, you want adding support to be a weekend project, not a six-month rebuild.

Old laws for new times

These laws aren't new. Most of them have been understood by the CMS community for a decade or more. What's new is that vibe coding makes it easy to build something that violates all ten in a weekend and looks great doing it. The hard problems don't show up in the demo. They show up when a second editor joins, when content needs to flow to a channel you didn't plan for, when an AI agent tries to operate the system programmatically, or when you need to migrate and discover your content is welded to your infrastructure.

Build a CMS if you want to. The tools have never been better for it. But if you want other people to use it, these are the problems you'll need to solve. And if you're evaluating one, these are the questions to ask. Feel free to respond with your own list.

1. I can never decide if I like “CMSs” or “CMSes” more.

2. A “reference” here is some kind of indexed and queryable link between two separate pieces of content.

I also sincerely believe that the field is changing and that there’s a lot of us that has to re-evaluate our perspectives if we want to be taken seriously at one of the future’s attractive workplaces. So this is my attempt at a guide for men in tech. Know that I’m writing this knowing that there are things I may have not considered or have enough knowledge about. And consider it a fork of Patricia’s post, and an open source project where pull requests and code reviews are welcome from all who care to. I know that this text smells of a narrow heterogeneous gender dichotomy (men vs. women). Even though these tips are directed at a stereotypical sense of men — whatever your definition is, they are obviously not restricted to them.

1. A team’s success doesn’t rely on being a fraternity, it relies on different people’s ability to work together

It’s time to retire the idea that success in your team requires that all of its members are “in on the jokes,” like the same type of past time activities, or should tolerate shitty behavior because it’s supposed to be a sign of sibling-like love. Don’t take women’s adversity to join in on certain activities to mean that they “aren’t any fun” or that “that they look down on you.” People always have their reasons, there’s no harm in questioning if how you act at work can be unpleasant for others.

2. Give credit to and honor other’s work

For all its flaws, the academy has one system going for it: the practice of citation. It’s generally anathema to steal ideas or research of others without giving it credit (not saying that it doesn’t happen). In tech, we are entirely dependent on each other’s capacity to great work, because despite what some may opine, you can’t write all the code yourself. And I’ll let you in on a secret: It feels way more powerful to be part of making sure that another person’s good idea comes into fruition. Chances are that this person has more good ideas on the way, and you may have the privilege to work with that person.

We know that women are often talked over in meetings. We know that ideas are easily stolen by the most eager and outspoken in these settings. You can be the one that reminds the group who was its originator and place that person back in the narrative. Be conscious about this in your written communication also.

3. Don’t think that it’s other people’s job to ensure that the workplace is safe

If the advice for women is that they can’t trust Human Resources, not even if they’re women and apparently say the right things, the responsibility falls on you to set expectations from leadership. It’s perfectly OK for you as a man to request the strategy for making sure that people are given equal treatment in the workplace. You can require that there are safe ways to report abuse. Often this role falls to women, and they are immediately categorized as “troublemakers” or “pissy.” Relieve those women of that role, I doubt you’ll risk any consequences, and if you do, it lends only legitimacy to what you did.

4. Women in tech are first and foremost technologists

We have different roles and different times in our lives. We are sons, fathers, brothers, employees, coders, front-enders, project managers, strangers, friends, colleagues, but very seldom we are reduced to “the man” in the workplace. Women in tech are often reduced to, well, women in tech. Trust me, most of them don’t want to be. They want to do interesting work and be recognized for it. Sounds familiar? We all play an array of different roles, sometimes gendered or not, but I don’t know any male programmers that want to be celebrated for writing manly code. Don’t go looking after “a woman programmer”, but make sure that you have been in contact with and considered people of all genders.

5. Don’t use alcohol as an excuse for bad behaviour

I’m ambivalent about alcohol at the workplace. It can obviously be a fun social lubricate, and wine, beer, and drinks can be a joy for the senses. But too much of it, or for some, any of it, are often destructive, and drunkenness is used as an excuse for douchebag behavior. You should be aware if you’re able to behave yourself when you drink. If you’re not 100% sure that you can behave when you drink, get feedback from someone, ideally a woman. I doubt it’s feasible to quit alcohol on functions altogether, but make sure that you request that there are good alcoholic-free drinks as well, and make alcohol a complementary thing, not the main activity of the evening.

6. You’re a nice guy, but you’re probably part of the problem

I’m guilty of this. Just because I care about gender equality, it doesn’t mean that I’m not failing to work against it or take advantage of my privileged position at the cost of others. Being circumspect and self-conscious of this doesn’t mean that you have to be self-flagellating or feel like a bad person, it just means that you’ve to put a little work into being a decent person to others. You’re no use if you don’t contribute by calling out abusive behaviour, or don’t make sure that people are given a fair chance to succeed and evolve.

7. Give women space

Both literally and figuratively. Be mindful that people who are constantly reminded of being of and in the minority needs space to be themselves, as coders, nerds, or whatever. Your input or presence isn’t always required. Statistics show that many of the women you will work with have experienced physical harassment in some way. People respond differently to these experiences, but it doesn’t hurt to ask if one would like the door open or closed if you have a one-to-one meeting, or let them choose the location.

8. If you’re given a cake, take that as good feedback

Patricia’s tips are to bake a cake for great people. This cake is not a lie. If you succeed in being a good person for your colleagues, chances are that you’ll get rewarded for it. If you are like me, this can feel a bit unpleasant, because chances are that you behaved like a decent person, which shouldn’t qualify for special treatment. But eat the cake and appreciate the gratitude. And remember, you can bake cakes too.

9. Eat lunch with women in tech (but not as a date!)

If you follow these tips, you may get the chance to talk and learn about other people’s experiences in the field. Much of what I have learned, has been over a lunch, where I have tried to listen. You may feel the urge to argue or get defensive. Save that for later if you must. You’ll be surprised that even female colleagues that you recognize as “strong” and “outspoken” have bad experiences.

10. Help out documenting women’s work

Patricia advice women to make slides and document their work to not lose credit. That sounds like a lot of work. The least of what you can do is to volunteer as meeting secretary and make sure that the work is documented and credited where credit is due. This is significant at a higher level: It’s important that we make sure that women take part in a team’s success story. The book Broad Band: The Untold Story (which is a great book on its own right) by Claire L. Evans shows how many essential and important inventions and practices has been made by women in the history of digital technology, only to be forgotten when men write its history (looking at you Steven Levy).

11. Save your criticism of later

It’s so easy to shoot down ideas. It’s harder to come up with them. Sure, you have insights, experience, and valid points, but more often than not, it’s better to let people explore and make their ideas more concrete. It will also give you a chance to chew it over, and if they make a proof of concept, you’ll both have a more informed and fruitful discussion.

12. Question team-building activities, especially where women have to dress differently

Hell, I don’t feel very comfortable bathing with anyone. I don’t get the appeal of strip clubs. I don’t see how themed parties are very useful in building good teams. Sure, people may find all these things great fun, and that’s ok. But they should be voluntary and complimentary. If the work isn’t team building of itself, you should probably find some more interesting problems to solve.

13. Be wary if women quit your workplace

People quit for boring and legitimate reasons. But sometimes they leave because they can’t bear it anymore. I have many times been caught surprised when I have after the fact learned that some past colleague has gone through some shit at the workplace. Many of these things never hit the surface.You cannot assume that people will automatically recognise you as an ally (you probably look exactly the same as the people who are the reason your colleague is leaving). Again, it’s a good time to ask leadership about how we ensure a safe workplace.

14. Your criticism is least useful in the form of public barrage

I’ve been a part of groups where harsh feedback has been given openly, but I have always found this behaviour in myself and others a bit weird: Some men tend to be obtuse when giving critical feedback. We rationalize it as “being honest” and “not bothering dressing it up nicely,” but honestly, it makes us feel as shitty both as the giver and receiver. So there’s no reason to jump on the dogpile. Good, useful criticism comes with empathy. If you want your feedback to have lasting effects, it has to come from an understanding of the position the work comes from. Also, there are just so many hills you can die on. Give people a chance to learn from own mistakes.

15. Be the one chosen for code review

Patricia have great advice for doing code reviews. It’s mostly about how to do good programming work. Some men have the impression that women generally are not as good at programming, and use code reviews to remind everyone of that. They are wrong. We all make stupid programming mistakes. We’re all learning the craft, and that process never ends. People solve things differently, and that can be a learning opportunity. And seriously, if you find yourself criticising style choices, your team either need to choose a linting standard, or you shouldn’t do the review in the first place.

16. Be generous with your knowledge. Teach those who want to learn from you

If you can be part of making someone a better coder than you, that’s a privilege you want to be a part of. Teaching what you know to others, is also an excellent way to improve your own skills. Remember that teaching isn’t the same as telling or explaining. Good teaching comes from learning what your student needs to increase her expertise or knowledge. It requires a lot of listening.

17. Demand diversity

Make sure that your job ads are read and vetted by different people, including women. Remind recruitment that women often have to be contacted directly. Ask conference hosts what they’ve done to ensure diversity on the stage because then you are taking a place that could have been held by a woman. Be open that a new colleague’s role isn’t to be your new buddy, it’s to set your team up for being able to solve problems. And don’t just demand it, offer to help in any way you can.

18. Don’t tolerate locker room talk

I don’t think there’s much more to say. It’s dumb and unnecessary, and you should call it out.

19. Be a powerful ally

If you gain someone’s trust because you manage to behave like a decent human being, use that trust and your privilege to support that person be heard in meetings and workplace processes. Be prepared and willing to let others shine.

20. You probably don’t need to put a sexy lady on your slides

If your work isn’t sexy enough of itself, it won’t certainly help to augment it with something that makes some people uncomfortable. You may find this prudish, but that’s probably because you haven’t experienced being reduced to a body to any extent. Being an ally also means calling out colleagues and peers who still think this sort of behaviour is fine.

21. Don’t assign non-technical work to women that you don’t also do yourself

If a woman is hired as a programmer, coding is probably what she should be working with. If you find yourself in need of a secretary, project manager or user researcher, you should probably hire one. If you have a small team, which require people to cover more roles, be circumspect of which roles you give whom. Just because you recognize that women may be “good with people,” it doesn’t mean she should be doing all the user research. Perhaps the most talkative person in the meeting should take the role as a notetaker and be forced to listen.

22. Educate yourself

Read books like Brotopia, and Broad Band. Follow women programmers on twitter. Read blogs. Listen to podcasts. Watch conference talks that deal with social issues in tech. Learn something about discourse analysis and literary criticism. Think about how words and language tie in with power. Be open that knowledge can be acquired in different ways, and be skeptical to people who claim that they possess a scientific objective truth about how gender is supposed to work. If they claim scientific superiority they should be able to host a colloquium where you review and discuss published research. Take the time and read Daniel Kahneman’s Thinking Fast and Slow and reflect on all the cognitive biases that are in effect every day, for us all. There’s some good meeting advice in there as well.

23. Think about the fact that Survival Tips for Women in Tech has to be written in 2018, in Norway

Official reports from 2017 have shown that 1 in 12 women have experienced sexual abuse at the workplace in Norway (so that’s not counting what may have happened on school, or at home). Think about it. Norway is one the world’s top countries concerning gender equality. Still, chances are that one of twelve women that walks through the door at your workplace, has experienced some sexual transgression in some way, and almost certainly, have had shitty experiences that comes from her merely being a women and in the minority.

There are situations that may seem completely harmless for you, that may for people that have experienced abuse, feel is unsafe and unpleasant. It’s impossible to account for this at every turn, but be at least open and understanding if someone hints to that may be the case. This affects their ability to do good work. This affects people’s opportunity to be… people.

I know I risk very little writing this, even though I imagine some of my fellow male technologists may call me out as a social justice warrior, or roll their eyes for me being politically correct. Well, I hope they get over themselves. I will still be recognized for the other work I do, and not just “an angry feminist.” I may also be accused of virtue signaling. Be that as it may, I’m not saying I have succeeded in following these tips myself. But I think it’s vital that people like me, also join the conversation. For ultimately, it’s about figuring out how we all can make room for everyone to go explore in this short time we spend in existence, in a way we find fulfilling. And that’s a hill I want to die on.

(Thanks to Patricia for writing the article that inspired this one, and for her feedback on this text. And thanks to Chris Atherton for her helpful comments.)

But this post isn’t about how Apple has lost its edge with its new perfect circular new campus, but about one of my favorite little apps, the GIF screen capture tool LICEcap.

Not a day goes by without me having to record something I do on the screen. It can be to document some bug I found, show my colleagues at Sanity.io something cool, a clever tweet, or useful visual context when I’m helping other people out some project. I know you should think twice before putting animated GIFs on your webpage (because they tend to be huge), but I sometimes make that sin too.

There are loads of cool screen capture to GIF tools out there. An obvious mention is Kap by these wonderful people. It does a lot more than LICEcap, and is even written in the world-eating JavaScript programming language. In fact, I used it to screen capture how LICEcap works.

But the reason I’m always reaching for LICEcap when I need those moving pixels captured is that it records directly to the file. No post-processing. Apparently, that is a killer feature. Being able to quickly do the screen capture and have the GIF ready for sharing in the instant you stop the recording is really convenient. Turns out, convenience trumps feature lists.

LICEcap doesn’t have a bunch of options and settings. But that’s fine for most parts. If I need more, that usually means that I should do the recording with something like ScreenFlow instead.

I actually thought my days with LICEcap were over, but writing this post made me discover that a 64-bit version has been out since February 2018, so shame on me.

Doing some minimal amounts of research for this post, I also discovered that LICEcap’s developer is Justin Frankel of Winamp fame.

Look, when you work with content, it’s not always easy to get going. Perhaps you only manage to come up with the same tired clichés, or you’re too close to the product and find yourself knee-deep on a tangent describing how the design choices were inspired by something your uncle said in a birthday party.

Whatever it is that keeps you from writing that succinct post that presents the what, how, and why to your readers without wasting their time, there is a remedy. We called it “The Hulk Summary”.

The method is simple. First channel your inner Hulk voice (everyone has one hidden in them somewhere), add a touch of rage and use it to describe whatever you need to get writing on. Hammer down that shift key (caps lock is a cop-out) and type max 4 words for each bullet to capture the core sentiment of what you’re arguing. The constraints will set your mind free.

You might not find crude shouting methodology enough to tease out the core of what you try to say. I'm happy to announce that The Hulk Summary™ is fully compatible with renowned communication frameworks proven by probably too expensive consultancy hours, such as the SCQA-model from The Minto Pyramid Principle. Put differently:

• WHAT SITUATION!
• COMPLICATION! DIFFICULTIES!
• I HAVE QUESTION!
• ANSWERS ARE DUE.

This method will most definitively not be developed further. We have loads to things to ship over at sanity.io. But now that it is introduced to a wider audience, we would love to hear your success stories about how it saved your whole content marketing department from writer’s block and pencil fear. Or how you made an interesting friendship from using it as a quirky icebreaker at a gathering. Literally hit us up on Twitter and let us know, hashtag thehulkmethod.

(No Banners were hurt in writing this blog post.)

There was the “[insert technology] for Dummies” series, computer magazines with tutorials, and the occasional workshop at the local Internet café. The path from curiosity to running code was: find an example, read it, change it, see what happens.

Fast forward almost three decades (yikes!) to a few weeks ago.

I’m standing by a whiteboard at Sanity HQ in San Francisco, talking to the team building our SDKs about what happens when agents try to use our stuff. They wanted to know: how do we write better skills files? How do we give devs better prompts?

These are intuitive questions. All of us have spent the last couple of years figuring out what to tell agents to make them useful. Still, I told them they were starting in the wrong place. I’ve been working through this with several of our teams, and what I keep finding is that the answers aren’t where you’d expect.

When someone types “build me an app with [your product]” into Claude Code, unlike a Google search, it just does stuff. It picks packages. It picks patterns. It makes architectural decisions based on statistical opinions trained on everything it’s seen. And it does all of this before your user has read a single line of your documentation.

The new “time to hello world”

If you make developer tools, you probably think about “time to hello world.” How fast can a developer go from zero to running code with your product? You optimize your getting-started page, your quickstart guides, your API key flow. You design for a human reading your docs. You make it easy to copy-paste. You make wizards that scaffold projects from choices.

But now there’s another type of cognition operating between your product and the developer. Language models wrapped in different affordances (an IDE, web or terminal apps, different system prompts, MCPs, skills), what’s often called “agent harnesses.” These harnesses sometimes go fetch your docs, sometimes use your MCP tools, sometimes just predict code from training data. The line between “what the LLM knows” and “what the harness finds” is blurry, and it’s getting blurrier.

What’s consistent is this: someone types a naive prompt. “Build me a content-driven app with Sanity.” “Set up authentication with Clerk.” “Deploy this to Netlify.” There might be no docs consulted. No getting-started page visited. Just a prompt and an expectation.

That naive prompt is your new first impression.

The new kind of developers

The person typing that prompt isn’t always who you’d expect. Agentic coding tools have lowered the barrier enough that people who wouldn’t have called themselves developers two years ago are now building applications. Designers prototyping interfaces. Marketers building bespoke dashboards. Founders shipping MVPs. They’re not going to read your getting-started tutorial. They might not even know they should. (We had these users before too. They just used to hit a wall that forced them to learn or hire someone. The agent removed the wall but not the gap in knowledge behind it.)

We’re seeing this at Sanity too. Builders on Reddit who report that “they are not technical” while touting that they went to production with a website using Next.js and Sanity. That tends to work pretty well, because most models have seen a lot of Next.js plus Sanity code.

But when the task goes beyond what’s well-represented in training data, things get interesting. I work at Sanity, have done for nearly eight years, so I’m obviously invested in how this plays out for us. An agent asked to build a Sanity application, without specific guidance, grabbed the Sanity client, grabbed Next.js, and tried to build a generic app. It had no idea what our App SDK was. It defaulted to whatever had the most representation in its training data. I started calling this “popularity horror”: the agent follows the most-trodden path, not the correct one.

Where you actually have control

This is where the current conversation about “Agent Experience” gets interesting.

Matt Biilmann coined the term AX in early 2025 and did something important: he gave people a name for a design problem nobody was talking about systematically. In his one-year update, he lays out four pillars: Access, Context, Tools, Orchestration. It’s a useful map of the territory. His point about context engineering, managing what’s in the agent’s context window during its tool-use loop, is especially sharp. And the “deploy first, claim later” pattern that Netlify, Clerk, and Prisma have adopted is a genuine innovation in onboarding design.

What I want to add is a question about sequencing. When you have a team with limited engineering time, where do you start?

All four pillars are worth investing in. But I keep finding that the system layer (your API shape, your error messages, your SDK abstractions) does double duty: it improves the experience for agents AND for the humans who were already using your product. The instruction layer (skills, llms.txt, MCP descriptions) is important work, but it’s agent-specific. If I had to pick where to spend the first sprint, I’d pick the system.

Here’s how I think about where your design control actually sits:

Low control: the user’s prompt. You can’t influence what someone types into Claude Code. Zero-control territory.

Medium control: the instruction layer. Skills files, llms.txt, MCP tool descriptions, documentation. You write these, and they matter. But they get interpreted, compressed, sometimes dropped. Whether the agent finds your docs through its harness or predicts from training data, the instruction layer is always mediated. Cloudflare’s developer docs produce an llms-full.txt that’s 3.7 million tokens long. That’s not fitting in any context window.

High control: your system’s surface. API responses, CLI output, error messages, SDK abstractions. These are what the agent actually touches when it interacts with your system, whether it’s predicting code or calling your tools. And this is where I keep finding the real leverage.

Error messages as instructions

There’s already a standard for this, and it’s been around since 2016. RFC 9457 (“Problem Details for HTTP APIs”) defines a JSON format for error responses with structured fields: type (a stable URI identifying the problem), title (human-readable summary), detail (what went wrong this time), and extension members for anything else. The content type is application/problem+json.

The difference between a useless error and a useful one is the difference between the agent spinning its wheels and self-correcting:

// What the agent gets from a lazy error:
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request"
}

// RFC 9457 Problem Details: the agent can work with this
{
  "type": "https://api.sanity.io/problems/document-type-not-found",
  "title": "Document type not found",
  "status": 400,
  "detail": "Document type 'post' not found in dataset 'production'",
  "availableTypes": ["article", "page", "author"],
  "hint": "Did you mean 'article'? See https://sanity.io/docs/schema-types"
}

Same HTTP status code. Wildly different outcome. The type URI gives the agent a stable identifier it can pattern-match on across occurrences. The detail field explains this specific failure. The extension members (availableTypes, hint) give it everything it needs to self-correct. This isn’t a new idea. It’s a standard that most APIs still don’t implement.

I ran into a version of this with our own tooling recently. I was trying to deploy Sanity functions from CI using our Blueprints CLI and hit Missing scope configuration for Blueprint. The scope config (project ID, stack ID) lives in .sanity/, which is gitignored because it also contains build cache. CI clones fresh, so the config is never there.

It turns out there’s a dedicated GitHub Action for Blueprints deployments that handles all of this. But neither I nor my agents found it. The agents went straight to the CLI (the path of least resistance), hit the error, and started trying to work around it. One agent, given enough rope, actually read the CLI source code and discovered that the scope can come from environment variables (SANITY_PROJECT_ID, SANITY_BLUEPRINT_STACK_ID), bypassing the config file entirely. It solved the problem. But it solved it the hard way, by reverse-engineering the internals instead of finding the purpose-built solution.

The interesting part is what happened when I shared this with the Blueprints team. Within minutes we were sketching out improvements: what if the error message mentioned the GitHub Action? What if blueprints init offered a --with-github-action flag? What if --help had a CI/CD section? The building blocks were all there. The surfaces just didn’t connect them. Something like:

Error: No scope configured for this project.

  To set up locally:
    sanity blueprints init

  To deploy from CI (recommended):
    Use the official GitHub Action:
    https://sanity.io/docs/blueprints/blueprint-action

  Or set environment variables:
    SANITY_PROJECT_ID, SANITY_BLUEPRINT_STACK_ID

  Run 'sanity blueprints deploy --help' for all options.

That’s the same information the agent eventually found by reading source code, surfaced at the moment it’s needed. The agent hitting this error goes from spinning to self-correcting. The human hitting it goes from frustrated to deployed.

The experiment

To make the SDK point concrete, I ran a simplified experiment. I opened the Anthropic Workbench, no IDE, no skills files, no system prompt, just Claude Sonnet and a text box, and typed:

Build me a custom content approval dashboard for Sanity. Editors should see a list of documents pending review, be able to open and read each document, and approve (publish) or reject them. Use React.

Some context: the App SDK is a React toolkit for building custom content tools on top of Sanity. It provides hooks for listing documents, reading them with real-time updates, and publishing them atomically. If the agent finds the SDK, this is a straightforward build.

The agent did not find the SDK. (It’s relatively new, so the training data is dominated by older patterns.)

10,335 tokens of code. Built everything from scratch on top of @sanity/client. To publish a document, it predicted three separate API calls with no transaction and race conditions between steps. The production-grade version, publishDocument(handle), is a single atomic operation in the SDK the agent didn’t know existed.

// Patch the draft
await client
  .patch(`drafts.${documentId}`)
  .set({ approvalStatus: 'approved', reviewedAt: new Date().toISOString() })
  .commit()

// Copy draft to published
const draft = await client.getDocument(`drafts.${documentId}`)
const { _id, ...docWithoutId } = draft
await client.createOrReplace({ ...docWithoutId, _id: documentId })

// Delete the draft
await client.delete(`drafts.${documentId}`)

Second run, I added “real-time” to the requirements. Worse, not better. 17,840 tokens (72% more code), 150 lines of hand-rolled state management. Still no SDK.

Third run, I added a system prompt listing the SDK hooks and their signatures. Dramatically different. The result was dramatically different. The agent used every hook I mentioned. useDocuments for listing. useDocument for reading with real-time updates. publishDocument(handle) for the atomic publish. Suspense boundaries for loading states. A standalone App SDK app with <SanityApp> provider instead of a Studio plugin. Cleaner architecture, fewer tokens (11,832), more correct code.

But to write that system prompt, I had to already know the answer. The instruction layer worked, but it required the human to have the expertise the agent lacked.

The hallway, not the signage

There’s an analogy I keep coming back to. If you’re designing a physical space, you can put up signs telling people where to go. Or you can design the hallways so the natural flow takes people where they need to be. Both matter. But if your hallways are confusing, no amount of signage will fix it.

Skills files and llms.txt are signage. Your API design is the hallway.

That’s what good developer experience has always been: making your tooling less vulnerable to oversight. Less vulnerable to the human forgetting a step, skipping a doc page, not knowing what they don’t know. Agents just add another layer where oversight can happen. The SDK absorbs that layer the same way it absorbs the human one. The error message that tells you what went wrong and how to fix it works for both.

Three questions for your next sprint

If you’re on a team building developer tools and you want to start somewhere concrete, here are three questions I’d run every surface through:

1. What does the agent see when it fails?

Pull up your error messages, your CLI output on bad input, your API responses on invalid requests. Read them as if you have no context. Does the failure tell you what went wrong and how to fix it? Or does it just say “invalid request” and leave you guessing?

The Blueprints CLI example is mine. Yours will be different. Maybe it’s an API that returns 400 Bad Request with no body. Maybe it’s a CLI that says “configuration error” without naming the missing field. Maybe it’s a runtime error that shows up in the browser console as an opaque stack trace instead of telling the developer which prop they forgot or which environment variable isn’t set.

That browser console one is worth lingering on. Agents working in coding environments read terminal output and console logs. If a library throws TypeError: Cannot read properties of undefined when someone forgets to wrap their app in a provider component, the agent will flail. If it throws something like Provider not found. Wrap your app in <AppProvider>. See https://example.com/docs/getting-started, the agent fixes it in one pass. Same error, different surface. Every place your system outputs text is a place it can guide the agent.

Fix the worst dead-ends first. (You probably already know which ones they are. Check your support tickets.)

2. Where can you direct agents regardless of user input?

This is the one most teams miss. There are moments in every developer workflow where your system gets to speak, unprompted, into the agent’s context. Not because the user asked for help, but because your tooling is running and producing output.

Think about what happens when someone (or an agent) installs your package. The terminal output from npm install is right there in the agent’s context. A postinstall message that says “Run npx your-tool init to get started” is free guidance. The agent will often just do it.

Or think about what your dev server prints on startup. Most frameworks print a URL. What if yours also printed the key configuration it detected, or flagged a missing environment variable before the first request fails? sanity dev could print “Studio running on http://localhost:3333 | dataset: production, project: abc123.” Now the agent knows the project ID without having to parse config files.

CLI help text is another one. When an agent runs your-tool --help (and many harnesses do this as a first step), what comes back? A wall of flags, or a structured list with examples? The --help output is documentation that lives inside the tool itself. It can’t be summarized away or dropped from context. It’s always there.

These aren’t instruction-layer investments. You’re not writing docs or skills files. You’re making your system’s normal output more informative. It’s the difference between a hallway with good lighting and one where you need a flashlight.

3. What’s the path of least resistance?

If someone gives an agent a naive prompt about your product, what does it build? Try it. Open a workbench, type the kind of thing a new user would type, and look at what comes out. Is the agent reaching for the right packages? The right patterns? Or is it building everything from scratch because your newer, better abstractions aren’t well-represented in training data yet?

You can’t control what the agent predicts. But you can control how many paths through your system lead somewhere good. Fewer paths, better defaults, opinionated SDKs. If your product has three ways to do the same thing (the old way, the new way, and the raw API), the agent will pick whichever one has the most training data. That’s usually the old way. Deprecation warnings that suggest the replacement, clear migration guides, and SDKs that make the new way shorter than the old way all shift what “least resistance” means.

4. Who’s evaluating the output?

This is the one that changes the stakes. An experienced developer will catch a fragile publish pattern and go check the docs. A designer shipping their first app with Cursor won’t. They’ll trust whatever the agent produces.

The instruction layer (skills, docs, llms.txt) assumes someone who can evaluate what the agent produces. The system layer (SDKs, error messages, API shape) protects everyone, including the people who can’t. If your user base is shifting toward less experienced builders (and for most developer tools, it is), the system layer matters more than it used to. The question isn’t just “does this work?” It’s “does this work safely for someone who can’t tell the difference?”

What I'd do if I ran a DX team rn

Take one afternoon. Pull up your product’s error messages, your CLI help text, your API responses on bad input. Run a naive prompt through an agent and watch what happens. Then ask the four questions:

1. What does the agent see when it fails? Find the dead-end errors and rewrite them. This is the highest-leverage change you can make, and it helps your human users too.
2. Where can you direct agents regardless of user input? Your postinstall messages, your dev server output, your --help text. These are free guidance that can’t be dropped from context.
3. What’s the path of least resistance? If the agent follows the most obvious path through your system, does it end up somewhere good? If not, that’s a system design problem, not a documentation problem.
4. Who’s evaluating the output? If your user base includes people who can’t tell good output from bad (and increasingly, it does), the system layer is their only safety net.

The instruction layer matters. I’m not arguing against skills files, llms.txt, or MCP servers. But if you’re deciding where to spend your next sprint, start with the system. It’s the work that helps both your human users and the agents they’re working through. And it’s the work that compounds: every error message you improve, every CLI output you make more informative, every SDK that encodes the production-grade pattern stays improved regardless of which agent harness comes along next month.

Skills files and llms.txt are signage. Your API design is the hallway. The hallways come first.

Wait a minute, what is a JAMstack?

Having just been to a conference that has JAMstack in the title makes it easy to forget that it’s not a known concept to everyone. The JAM is JavaScript, APIs, and Markup. It signifies an approach to making websites where you use JavaScript and APIs to build your site and deliver prerendered markup to your readers. The ethos is really making sure that your website is fast, secure, easier to scale, and developer friendly. If you read this post on my domain, then you’re on a JAMstack website.

Static site generators are a significant part of the JAMstack scene. They have been around for good while. What’s “new”, however, is that there’s more attention given to the dynamic nature of the modern web. By using dedicated services with APIs and client-side JavaScript to take care of those things. In contrast to having a website directly connected to a database that has to re-render the same markup for every visitor each time.

So JAMstack_conf, how was it?

View on Twitter

Of course, I’m at JAMstack_conf not only as a participant in the community but also in my capacity as a developer advocate for Sanity.io. Which means that I represent a vendor in the field. This role is still fairly new to me, and there’s still the self-awarness that you are there with an agenda: You want people to try out the thing you’re working with. The nice thing about JAMstack_conf, however, is that people are curious and open, and in fact, come to you to ask questions and learn. So I just have to make sure to make myself available.

Another nice surprise with this JAMstack_conf was that I also got to meet a bunch of people that have used Sanity for a while, and that I’ve only met in cyberspace. It’s really nice to put a face on people that you have been talking to in the numerous Slacks I’m in.

My good pal Jamie held a blazing lightning talk and gave us a solid shout out. Much appreciate!

The New Dynamic is like the lounge of the JAMstack community and some of us got into a group photo (We have to work on the demographic though).

But the talks Knut, the talks‽

The JAMstack_conf organizers usually end up finding some great speakers. They tend to fall in two categories: Those who are great at doing talks (because they’ve been doing it a bunch), and those who are maybe not as experienced but have some interesting insights. What I appricate with the scope of JAMstack is that you end up with a broad set of themes. We have the nerdy code-snippets-on-screen talks, like how Ives and his team built Codesandbox.io or Una’s inspiring session about CSS Houdini (because pixelated gradient borders are awesome!). There’s also more of the higher level stuff, like Simona’s systematic introduction to serverless and Vitaly’s step-in talk for Chris (of CSS-tricks) (who had a bike accident) about the take-aways from the JAMstackification of Smashing Magazine.

I really appreciated learning more about web performance. I must admit this is a topic where I often feel it’s difficult to discern between what’s “web perf cargo culting”, or what is actually useful advice. I enjoyed Christian’s lightning talk about The State of JAMstack in Africa and how to take lower-powered devices into account. It was also some good quality programming to put Jake & Surma at last with their magnicifent and hilarious “Setting up a static render in 30 minutes”, in which they talked about how they made Proxx work for 2G and 3G devices.

Wasn’t you on stage as well?

We were asked by the good folks at Netlify if Sanity.io wanted to announce something in a lightning talk session at the conference. So we figured this would be a good opportunity to announce that we’re making our query language GROQ open source. That meant that we had to prepare the draft for the specification for public consumption. It was also a good occasion to implement a parser for JavaScript and a CLI that utilises it. So my colleague Magnus “Judofyr Holm did some really amazing work creating a parser-parser that let us set up an alpha version of groq-js rather quickly.

View on Twitter

Now, I really really really like GROQ. It was one of the things that won me over to Sanity before joining. I have done a bunch of talks and lectures before, also for large crowds. So I wasn’t expecting to be as nervous as I was. Seriously, there were quivering hands and tunnel vision. Just to be sure, I had also set myself up for some live command line querying. I did mess it up somewhat by accidentally printing 80k lines of prettified JSON, but I managed to get it back on track and show some of the query magic.

View on Twitter

My takeaway for my next talk, is that I’m not really stressed about things going wrong, but I have this thing where I start to get apologetic about things I really care about. Mainly because I’m afraid that people won’t find it interesting. And that isn’t helping anyone. So next time I'm on stage I'll remember to channel more of my excitement.

A special mention goes out to Netlify’s Phil Hawksworth’s MCing that tempered my nerves somewhat — his down-to-earth and witty approach to MCing makes for a friendly and safe atmosphere.

Next time in San Francisco!

So I guess this is a flaming endorsement. If you’re interested in how you can have a better time as a web developer or a web development adjacent, do consider getting yourself a ticket for JAMstack_conf San Francisco in October. I’m pretty sure that the organizers will tune this one to 11. And hopefully, I'll meet you there!

I mean it! Just scroll!

And then look up. A bit further. Yes, to the area of your tab bar where the <title> content ends up. And then scroll again.

There's a percentage there. And it changes when you are scrolling. Kinda cool isn‘t it? Now you can tab away from this site and still have a sense of how far you have read. That surely makes your existence a tad more pleasant, doesn‘t it?

The idea to put the scroll percentage in the title bar came from this tweet by @round.

View on Twitter

I didn’t make a browser extension, rather, I just put the mechanics into my own blog post template. Since I’m on Gatsby and React, it was not that hard. Here’s how to do it:

First I installed the react-scroll-percentage package. That takes care of most of the heavy lifting. Then, and I’m honestly feel a bit out of depth here, I thought it made sense to put the actual mechanics into useEffect. It may be that it would have been possible to make Gatsby and React rerender the <title> part in another way, but I was just following my gut here (tell me on Twitter if there‘s a better way). So I ended up with something like this (actual code here):

import React, {useEffect} from 'react'
import {useScrollPercentage} from 'react-scroll-percentage'
import Container from '../components/container'
import BlogPost from '../components/blog-post'
import SEO from '../components/seo'
import Layout from '../containers/layout'
import {toPlainText} from '../lib/helpers'

const BlogPost = ({post}) => {
  const {title, _rawExcerpt} = post
  const [ref, percentage] = useScrollPercentage()
  
  useEffect(() => {
    if (post) {
      const percent = Math.round(percentage * 100)
      document.title = `${percent}% ${post.title}`
    }
  }, [percentage])
  
  return (
    <Layout>
      {post && <SEO title={` ${title}` || 'Untitled'} description={toPlainText(_rawExcerpt || [])} />}

      <div ref={ref}>
        {post && <BlogPost {...post} />}
      </div>
    </Layout>
  )
}

export default BlogPost

Since react-scoll-percentage uses Intersection Observer, which is a relatively new browser API, we also need a polyfill for browsers that doesn’t support it yet. First install it as a dependency.

npm i intersection-observer

Then we want Gatsby only to use the polyfill in the browser, and import it dynamically when it‘s needed. We’ll do that by inserting this into gatsby-browser.js:

// gatsby-browser.js

export const onClientEntry = async () => {
  if (typeof IntersectionObserver === `undefined`) {
    await import(`intersection-observer`);
  }
}

And that’s it! Now, marvel at your new updating reading lenght!

(Cover image: Me presenting Sanity.io on the Google stage at Slush, with Bjørge)

In 2015 I was getting worn down. Recruitment practices in the academy are harsh. The prospect of being passed from one temporary university teaching contract to the next wasn't very appealing either. My fellowship was nearing its end, and while I had both published peer-reviewed research, and done lots of teaching and dissemination – it was challenging working on a thesis using digital methods in a field with very, very little experience with such things. Also, I’d developed a severe depression – which, after a too long stretch, I sought help mastering, and am mostly OK from today (do get help people!).

A couple of months before my stipend ran out, I got a job offer as an interaction designer (which soon became “technology strategists”) at the wonderful, UX-oriented design agency Netlife. In addition to my tech-oriented humanities background, I was an experienced web development freelancer. But I was very lucky to get the offer as it not only meant I didn't have to constantly worry about earning a living and how to get the next contract, but I was welcomed to a milieu where people had each other’s back and cheered you on. Not too much of that in the academy. Not that I'm bitter. Or wait.

I worked at Netlife for three years and enjoyed every minute of it – although multiple concurrent clients with high demands, sometimes on tight budgets and with much at stake, also does take its toll.

So when I got the offer from Sanity.io to join as a developer advocate, it felt like a special opportunity. I would get to work on a special technology along with some very talented people. It felt like the right time to move on and an opportunity not to be missed.

I had already had the pleasure of working with Sanity as tech-lead when building Netlife’s new website, using it as a content backend, with Next.js as the frontend, and multiple Node.js-microservices on Heroku. We had also run the same setup for U4 Anti-Corruption Resource Centre. Those experiences inspired me to write the blog post “Headless in Love with Sanity”, which — though I didn’t get at the time — kinda ended up being my job application. Notwithstanding, the motivation was a real appreciation to be working with something where you felt a lot of care and thinking had gone into making my life as a developer easier, and frankly, more fun.

Now that I have been working at Sanity for half a year, I thought it was time to jot down some thought about why it has been such a blast. It’s also a not too subtle pitch for those of you who either are considering applying for a position – or are asked to join. That being said, my motivation to write this it is pretty pure and an opportunity to reflect on what makes my job meaningful and exciting.

The people

I, like many others working with technology in Norway, had an admiration the people behind Sanity for many years. They used to be a technology- and design agency called Bengler, with a track record for doing weird/challenging/state-of-the-art work, such as making a social network tied to local publishing, that launched concurrently with Facebook, controller software for 3d printers, a chorded text input device, or disruption-as-a-service toolkit.

Frankly, coming to work with these people would have been terrifying, if it weren’t that they are all incredibly pleasant, grounded, and open-minded. They challenge you when you haven’t thought properly through the implications of your suggestions, but also cheer you on when you ship. As one of the first “outsiders” in the new company, I have never felt excluded or not a part of the team. Of course, that may come from selection bias, but I would be surprised if the same didn’t account for new, and more diverse hires than myself (a Norwegian white male in his 30s). It's a startup with grown-ups, with families, obligations, hobbies, and things happening outside of work.

The product

At work, pretty much all of our attention is tied up in what we’re making: Sanity. I have done my fair share of CMS related development, be it Wordpress, Craft CMS, Statamic, Contentful, and others. Although it isn't fair to categorize Sanity as “just another CMS,” used as one, it has undoubtedly been the most fun one to work with (and Craft CMS is pretty darn fun). I believe it’s because Sanity.io opens you to so many possibilities. There are plenty of doors that open when you deal with a real-time backend, having a relational document store with a graph-oriented query language, with an open source React content editing app. This makes Sanity.io pretty unique and awesome – it took them years to build.

However, all the little things are as important: some minor functionality in the CLI, some available method on the way you can tweak the document listings or a feature in GROQ. I can’t count how many times I asked if you could do this or that, and while waiting for the answer, discovering that, yeah, you can do it. It's nice to stumble over exactly what you need when you need it. Using Sanity.io has been a series of such experiences.

Sanity is already remarkable in its own right, but looking at the very secret backlog, there are so many cool things that we can build on top of this stack, that I can’t even. 2019 will be an exciting year, for sure.

The community

I have been mistaken so many times since I started in Sanity – which to me, is part of the appeal (that means that I’m learning). One thing I was very wrong about, was my worry about launching the community platform. I was so ready to have to moderate and deal with trolls and hostile people in our community Slack. I was very wrong.

It has been such a joy to get to know our community, get to answer surprisingly challenging questions (because people are using Sanity to solve challenging things), take very constructive feedback, and — this is my favorite thing — see the stuff people are building. The community has grown very fast, but it hasn’t been a single instance of harassment or bad behavior (as far I have been able to gather). As we continue to grow, a key concern is to make everyone feel welcome and included.

The office space

I go to work to the coolest office (though the floors are heated). Almost every day (as a commuter I treat myself to the home office once in a while), I enter a converted horse tram depot at Grünerløkka, a lively neighborhood in central Oslo (the capital of Norway). It’s an open space, yet it doesn’t give the feel of an open office. Behind where I tend to sit, there is a workbench where Polarworks (which also grew out of Bengler) are developing super cool motion control software. It very much feels like a maker space. So although I’m not that into beer and aware that it makes us sound like outtakes from Portlandia, it is indeed nice to have a micro-brewery where good tasting brews are made. Next year we'll be opening an office in San Fransisco, that'll be exciting too!

The challenges

To me personally, the primary motivation that brings me to work every day is many challenges of working on a product like Sanity, which both has many features, but with the ethos of being super easy to use. We sincerely believe Sanity has a place for developers that need a backend for structured content – be it a weekend project, or for enterprise needs. To take a product out in the world is hard work. To prepare your organization for taking on more people is always a challenge. To understand what’s truly useful for people, and how to communicate with them, is not easy. To take time off to recuperate and get enough brain air to stay creative can be difficult when crazy-stuff-we-can’t-talk-about-yet™ is happening every week. To be allowed to be wrong, to experiment, and given the trust to try stuff I haven't really done before are sometimes scary, as there is a great deal of responsibility that goes into it.

However, those are also the things that drive me, and why I, frankly, love working for Sanity.io. I hope I get to share that pleasure with you some day.

I should also mention our office dogs, my own Jara, and Espen’s Kokos.

It's surprisingly easy to get into the habit of publishing some content along with some initial tweet(s) and a post in various communities and move on to the next thing. But chances are, the content you just pushed into the world is long-lived and interesting for way more people than saw your initial push.

At least twice a week I think of the paraphrase that Merlin Mann frequently does on his podcasts, “Every day, somebody's born who's never seen The Flintstones.” I don't remember the full backstory (I believe it was a program manager at a local radio station) and the cultural relevance of The Flintstones is probably not prevalent.

Even so, I find it a useful reminder that there are always people:

1. who don't know the things you may take for granted as “common knowledge.” This is especially true for programming and product topics.
2. who haven't seen your content yet

So what are the practical implications?

There is practically no lack of ideas or things to create content on. Even the things that might seem obvious. Of course, there might still be more or less intriguing ideas, but thinking that “everyone knows this,” should never stop you.

Whenever you plan to release some content or do a launch, also plan for how you want to revisit this content down the road. Schedule tweets for later, add them to the rotation of tips and tricks to be posted in your community. – your future self will thank you.

P.S. And yes, even the points made in this post have been done many times before. Full meta.

A while back, Andy Bell offered some thoughts on silent majorities and whether you should feel technology FOMO from “a very loud minority.” Specifically, to what extent do you, as a (web) developer, need to feel the pressure to learn React, Vue, or TypeScript? Because if you log on to Twitter and follow the trades, it seems everyone is using those nowadays, right?

Andy’s argument seems to be that you can safely ignore the pressure of learning these tools since, according to W3Tech’s statistics, React, and Vue only make up 4% of the web, the majority being WordPress, with a booming at least 43.6% of the top, publicly available, websites of the web^[1].

In other words, if you’re following the discourse on web development on Twitter, you’re not hearing from most who are building the Web, which is a way to say that you don’t need to put that much weight on their opinions.

In Andy’s own words:

Always remember that although a subset of the JavaScript community can be very loud, they represent a paltry portion of the web as a whole. […] Now when you look at it like that, it makes you wonder why we give these people such a large stage while the very quiet majority don’t get a voice at all. The very quiet majority are out there building more than 90% of the web, after all.

I’m not sure we can use these stats like this, and I’m not sure this is the way to fight gatekeeping either.

But first, we need to set the stage

Before you read on, I feel I have to be clear: I am not here to defend React, TypeScript, JavaScript, or any specific technological preference. My agenda here is to bring a bit of nuance to what I feel is a fraught discourse in web development and, hopefully, contribute constructively to this conversation.

I think it’s great and important that we have professionals like Andy, who advocate for the web platform as an accessible (in the broadest sense of the word) place to do work. But I also think it’s great to have educators like Kent C. Dodds (one of the people quoted without attribution in Andy’s blog post) who have done a lot to introduce people to the discipline of professional web development. Andy and Kent have different approaches and preferences regarding tooling and focus, and this diversity ultimately a great thing that enables the conversations that bring us forward.

And a little bit about me

I have been around on the web long enough that I was first introduced to style attributes and presentational HTML (looking at you <center>) as the way to design a web page. I have used clear fixes and tables for the layout as the idiomatic way to do exciting stuff that got you noticed because it pushed the web beyond a boring document viewer for CERN engineers.

And it’s not like “frontend hype” is new. I have built many WordPress sites since I first tried it out shortly after its introduction in the early 2000s. I was one of many who fell for the jQuery hype back in the day. And I shipped sites using LESS, Sass, SCSS, BEM, grunt, gulp, MooTools, CoffeScript, Pug, Bootstrap, Foundation, and other patterns and frameworks that have popped up on the scene for the past 20 years. And in 2015ish, I started using React to build an internal Spotify analytics tool for Warner Music. It was actually then I really started learning JavaScript and more patterns from functional programming.

But more importantly, I have met thousands of developers who use these technologies to solve problems for their clients and customers and to earn a living. The kind of developers, like Andy points out, who aren’t necessarily blogging about bundle sizes or being loud on Twitter. So having established my ethos, let’s get into it.

Statistics are just numbers with a narrative

Nothing makes you doubt statistics as studying statistics does. You’ll find this quote by Benjamin Disraeli (made popular by Mark Twain) in every other statistics introduction book: “There are three kinds of lies: lies, damned lies, and statistics.” Statistics can help us understand landscapes and connections that are usually beyond what we can intuit, but numbers and graphs can be incredible rhetoric persuasive devices. Building your argument on statistics requires you to trust how these numbers were produced. One usually does that in the academic world by being very transparent with the data collection, methodology, caveats, and degree of uncertainty we’re dealing with.

My statistics professor used to say that a “proven” (by falsifying the null hypothesis with a mutually accepted degree of repetitive uncertainty) correlation is only interesting if it comes with a reasonable explanation for why it can occur (yes, I know this can be discussed, he was being didactic). I think the same can be said for sampling and framing of stats. If you want to use statistics to build your stance in an argument, you have to make a reasonable explanation for why the statistics are relevant and prove your point. I don’t feel Andy and similar takes do this. Yes, that goes for lighthouse scores too.

To be honest: I’m unsure what to conclude from W3Tech’s stats when choosing what technologies to recommend and prioritize when creating education and making topics for discussion and critique. If the W3Tech stats proves anything, it’s the adoption inertia of web technologies. That goes for both WordPress and React.

What is the W3Tech stats representative for?

According to W3Tech, they crawl the web by downloading the web pages and running them through static analysis using regular expressions and DOM traversal. They have built-in rules that allow them to assume server-side technologies as well. For example, if you can identify a WordPress site, you can safely assume that it’s using PHP on the server. This seems reasonable, although we don’t get much more insight since W3Tech is a commercial and proprietary operation that sells more fine-grained insights. In fact, it’s a 2-person company called Q-Success operating from Austria.

I think it’s reasonable to assume that their numbers are representative of the technologies that are used for the accumulative publicly available web. This means that these numbers tell a story about technology choices that were made up to several years ago, and only for the stuff that isn’t hidden behind login forms or is running in browsers but not on the open web. It’s still important, but it doesn’t tell the whole story.

Because the argument Andy is making isn’t about what runs on the publicly available web, it’s whether you, as a web developer in 2023, can safely ignore advice and pressure in learning React and TypeScript based on the induction of what most web developers are working with. At least, that’s how I make sense of his post and the broader conversation that Andy is part of. Who are typically very critical (and sometimes rightly so) of React and similar client-side JavaScript frameworks and the impact they have on the web’s user experience.

These stats don’t tell us what’s expected from web developers when it comes to what proficiencies are mentioned in web developer job descriptions, everything that runs behind a login screen in the ever-growing personalized web, the wealth of internal web applications, and the aspirations of web developers looking what technologies they want to learn and put to use.

And if we chose to use these numbers to anticipate the technology choices of a silent majority, then we absolutely should be teaching and talking about React. Since it's become a core technology in WordPress’ block editor, Gutenberg. Or new WordPress adjacent technologies like Faust.js (also React). Of course, it can be discussed if web developers who use WordPress need to use it headless or build/customize the block editor, but you see where the arrows point.

Stories told by other types of statistics

What I find confounding with how the W3Tech’s stats were used is that they tell a different story than most of the annual surveys on web technologies trends. If you look across surveys like State of JS, Stack Overflow, GitHub, etc. Generally, they are all telling the same grand story:

• JavaScript is used a lot for web development
• TypeScript is growing a lot, and people want to learn it
• React-based frameworks are dominating, but other frameworks are relevant too

Now, these surveys come with their own challenges regarding sampling biases, but collectively it’s reasonable to assume that they represent a significant portion of web developers. At least relevant enough not to be outright dismissed and ignored when thinking about what frameworks to discuss and make education for.

We also see similar tendencies in my day job at Sanity.io. The search volume that is people looking for resources on topics like React, Next.js, and TypeScript can’t be ignored. Content creators and educators on YouTube, Twitch, and so on cater to the same type of demand. FreeCodeCamp’s “React Course - Beginner's Tutorial for React JavaScript Library” from March 2022 has, as of today, 2.3mill views. That’s 43% of the views in a year compared to the 4-year-old “Learn CSS and HTML from scratch” video with its 5.3mill views.

Again, I’m drawing on these numbers to make a point. The above stats are nothing to the 4-year-old introduction to Python with its 38mill views. Which tells a different story about what developers and programmers are into and what demand we see in the market. Does that mean that we all should be talking about Flask and Django instead?

I didn’t find any good stats on the type of web development competencies mentioned in job descriptions. But scrolling through web development jobs on indeed.com, you’ll find JavaScript frameworks like React mentioned frequently. I also tend to see it mentioned on developer CVs and applications I’ve read. Still, this is anecdotal, and it’s uncertain how representative this picture is for the population of web developers. But I would suggest that it at least justifies recommending learning these technologies if you’re interested in a career in web development.

Fighting gatekeeping with gatekeeping

I think Andy takes the W3Tech stat interpretations too far in dismissing the value of opinions about learning TypeScript or “best practices don’t work.” But I think he is right regarding the amount of FOMO you should feel and not just taking the opinion of popular personalities on Twitter at face value. As a web developer, you will probably get a lot back from investing time in learning the basics of the web platform and building your understanding of what goes on behind the scenes of React, Tailwind, and so on. Knowing JavaScript well will make you a better React developer, so it’s not a zero-sum game, either.

Even though Andy isn’t mentioning it explicitly in the blog post, it can be read as an entry in a conversation about gatekeeping and heightening the bar to web development. I understand and support the desire to speak out against gatekeeping, but I often find that it’s done in a way that outright dismisses some legitimate and empathetic advice.

For example: Telling someone to “not ship JavaScript to browsers” or “don’t use Tailwind, just learn CSS” is not particularly empathetic or helpful. Rather, telling someone that Tailwind can get the job done quickly, but it’s possible to write it in a way that makes it harder to maintain, is actually useful advice. Or that a JavaScript framework can come in handy if you plan to make an interactive e-commerce experience without having to deal with backend programming languages, but you should keep an eye on different performance characteristics in the kind of browsers and platforms that the customers run the site on.

I also think it’s a stretch to assume that adopting TypeScript, or most other frameworks, makes it harder to enter web development in the first place. If you look at how modern web applications are built, and especially if you’re looking to do anything server-side, then yes, the initial learning curve might be steeper, but I can tell you that it’s significantly easier to be onboarded to a well-done TypeScript project versus a well-done JavaScript/Node.js project. And it’s not like it’s especially easy for a beginner to get started with WordPress locally either (more moving parts, different programming languages).

Beware of The Ideology of The Holy Web Trinity

The inclination that recommending any technology beyond the holy trinity of HTML, CSS, and (vanilla) JavaScript is gatekeepy, confounds an idealized stance about how to do web development with the very real situation a lot of aspiring web developers are facing. These advocates, in their rhetoric, dismiss that something like the React ecosystem empowers developers and teams who are asked and paid to solve problems. Wanting to change the direction of the web is built is a perfectly legitimate stance, but it’s probably not helping the case to dismiss voices that happen to promote tech you don’t like as “loud” and hence, not interesting to listen to.

If you want to make a strong case against popular technologies, it’s probably more effective to communicate an understanding of why these are used, and then provide viable alternatives. And not to undermine your audience: In most of my conversations with developers, I see curiosity towards things that are “hyped” co-exist with a healthy skepticism for what technology to put in production.

Having done developer marketing for five years, I know that the most efficient marketing is to show developers how to solve real problems without hyperbole. You’ll find much of that in the React ecosystem (take the marketing of TanStack). Even Vercel’s Apple-like marketing of Next.js is grounded in narratives of solving actual problems (and their style doesn’t escape critique either).

1. This is quoted, so many times.

But I’m not working a lot not because anyone has told me to do so. Rather on the opposite, I probably have at least 5 people, and among them mostly my managers telling me on a weekly basis that I should work less. The culture at Sanity.io isn't that you should crunch it on weekends and late hours, but rather, take time to plan and think on how to use the time one has on the right things. To get more done in less time with fewer distractions.

I don’t put in a lot of hours because I feel I have to prove myself either. Or because I’m hunting a promotion. I’m in the very privileged position where I’m fairly confident that I’m good at my job, and comfortable with the fact that I have a lot to learn. I put in a lot of hours because I inherently enjoy what I do. I look forward to it. It’s fun. It’s challenging. I learn a lot.

The hegemony of work-life (un)balance

It must be said, that this deep enjoyment is a relatively new thing for me. I have been at places where I have allowed myself to be consumed by work for all the wrong reasons. I have been through burn-out and depression, and used work as an escape from working with my own mental and emotional health and my tending my relationships. The stuff that Jason Lengstorf is writing about on his blog. Or Jason Fried and David Heinemeier Hansson over at Basecamp. (I realize that this paragraph doesn't pass the Bechdel test - let me know if you know of someone that should’ve been included. Edit: I got recommened Ariana Huffington‘s talk about sleep)

There’s a push towards healthy work-life balance in the tech discourse, especially as a response to predatory practices and unreasonable expectations in the start-up world. VCs that suggest that getting a business up and running (with the kind of growth that’s expected in this part of entrepreneurship) may take a bit more effort than a 40 hour week will get hammered by people who thinks this is setting an unhealthy precedence. Both arguments have merrits.

Even if you remove high expecations of growth and insert somber Scandinavian values to work-life, building a company and a product will require more time and energy of the people involved compared to what you typically have in a “normal position” at established companies. That makes it all the more important that you create a culture where people can endure for the laung haul, and not hit the wall. And that is my experience of what one tries for at Sanity.io.

So I am not expected to be available on chat at all times (you set yourself away in focus mode when you need to get deep work done). Meetings are recognized as being expensive in terms of people’s time and attention, thus we try to come to them well-prepared and setting “hard-stops” is normal. If there isn't an agenda or something to actually discuss, we are happy to just call the meeting off.

So the drivers behind me putting in a lot of hours isn't found in the culture or expecations that surrounds me, it’s coming from within.

Vocation versus having a job

I do believe it’s crucial to take time to be someone for your family, partner, kids, friends, or pets. To exercise, sleep, taste things, travel into fiction, take part in culture, listen to music, work with your emotional pain, muse about your existence, and seek spiritual experiences (whatever they are for you). Work can get in the way of that. But sometimes the Venn-diagram between work and life will overlap. And then the dichotomy doesn't fit.

What I’m getting at is the idea of having found a vocation versus having a job. I suspect that many startups begin with founders and early-stage employees that very much has building a product and a business as a vocation, a calling. It might sound a bit precious, but I think you’ll often find the same drive among teachers, athletes, doctors and nurses, and in religious professions (from where the word originates).

The problem arises when you as a founder or early employee that has now entered into a mangager role, assume that it’s reasonable to expect the same calling or priorities from others. It’s probably cool if they do, but I believe you will be much happier if you accept that people can do great things in the hours you get to spend with them, and still turn off e-mail and Slack notifications to go home to be a dad, a partner, or to something completely different.

Now that I've entered into a manager role, I’m also worried that my behavior is modelling expectations that I expressively don’t have: I fully understand that other people that have other priorities for what they want and have to spend time on. In fact, I expect it to be a requirement for bring their best selves to work. I have no problem adjusting and planning for not being able to get in touch with a colleague after office hours.

If you find yourself in having a vocation in a job that you enjoy. That’s great! But remember that’s a privilege that you get to enjoy, and not a reasonable expectation that you can put on others. And to be honest, I find it much more inspiring to work with people who bring other forms of nerdery, interests, and hobbies to the table.

I need to be at work less

I probably have to do something with my own behaviour and prepare to be less present outside of working hours. I should reduce my activity on Slack in weekends, and be more mindful about when I engage my teammates in work-related discussions during evenings. And remember, we're talking about patterns here, not absolutes.

I brought my dilemma up to one of my managers: “I keep being told by all of you to work less, but I don't see that I'm really changing my behaviour. And I don't feel I’m on the path to burn-out, but I'm worried by the precedence it may set. So. How should we approach this differently?”

The advice I got was to approach my days more mindfully by do more planning, to think about what is really important, and to try to measure what I’m actually spending time on, like, in hours. These are activities that I traditionally haven’t eager to do. But as I have gotten more responsibility, I have slowly started to appreciate them more.

I already do fairly more planning. Both long-term, my upcoming week, my next day, and my day. I keep lists. It has helped me being less reactive, and I do less things that may feel urgent, but is probably not important. But spending as much time on more of the right things is only half of the challenge.

So I need to start with the same strategy as when you want to manage your weight, but instead of measuring how much energy I consume, I have to measure how many hours I spend on what things. I need to build some habits that doesn't depend as much as my immediate motivation, and set myself up for success for what I want to achieve. I must admit I kinda dread having to dedicate part of my cognitive brain to keep tally of what I’m doing, but all the better reason to do it probably.

Know thyself; start smol

I know that I probably will continue to thinking about new ideas at any hour, get the urge to get stuff down on paper, roam the web for inspiration, and all these things that you do in knowledge work. My main worry is that I’m modelling behaviour and unreasonable expecations for others, so what I need to fix first is how available and present I am: That begins with being off Slack during weekends.

Since I do a lot on US time (whilst living in Norway), I will also try to log onto work later in the morning, using the first few hours of the day to read, get some exercise, do chores, plan holidays, and so on. And the big one: I will also try to get into time tracking, and probably start small, by tracking just one type of activity, and take it from there.

These things are relatively small behavioural changes that I should be able to make happen. I have tried to make sure that the hardest one, starts with relatively low expectations. Start time tracking just one thing. Is the same as starting to run: It’s much easier to drag yourself out to run for 15 minutes than an hour. And getting out the door is the hardest part.

So this is me acknowledging that there is a door, and a run to be had. And that’s the first step.

Because that’s the only way to make that phrase truly relay excitement.

You're still reading? OK, good. Let's talk about writing great marketing copy!

After I started working with marketing in a startup I’ve become more attuned to how the craft is being done. And for some reason, a lot of announcement posts start with the phrase “we’re excited to” followed by something that doesn’t smell of excitement at all. Anyone who has caught on to this might be tempted to replace “excited” with “thrilled,” “proud,” “elevated,” or even “stoked.”

But the verb isn’t the problem. It’s that you are too focused on the what and not the why. What you’re up against is not people just waiting to hear the latest from your company. They want to be heard, understood and cared for. And your job is to figure where their desires and your news overlap and take it from there.

No one sits on the toilet scrolling to figure out how to optimize efficiency for their teams.

You are probably working on something that’s worth getting excited by! Your team has probably made something that’s useful, and even super interesting and impressive (if that’s not obvious, then you might have deeper problems). But you are also oh so busy, you have shit to do, that needed to get out like yesterday!

So we churn out marketing copy leaning on the words, phrases, and structure that we’re used to to get it done. We write things about “teams,” “collaboration,” “efficiency,” "innovation," and “transformation” that will never spark an ounce of dopamine with anyone.

If your job is to persuade people to pay some attention to whatever you have going for you and take your product into consideration, then you need to consider what makes people stop whatever they are doing, be intrigued enough to pay attention and make the decision to take in what you communicate.

There are a couple of tips that I tend to give to my team:

1. Remember who your audience is and what they care about. Why should they care?
2. Explicitly recognize the problems they have (that you can solve)
3. Use tension, conflict, drama to get people hooked by putting emotion on the problem
4. Give them a call to action early on
5. If you manage to get someone hooked within the first paragraph or two, you can almost do whatever with the rest of your text

Of course, you might have heard some variation of these tips before. It’s rather basic if you think about it. But if it was truly that easy, people would be doing it more. So if you want to give yourself a competitive advantage: Take your draft and do it once more, with feeling. Con brio! (that's Latin for “with spirit”)

As someone with “developer marketing” in my job title, this question is partly existential^[1]. Not since I was digging myself deep into the academic world of the humanities in my mid-20s have I felt this strange mix of urgency, creativity, frustration, and intellectual fatigue.

Especially when Claude Code and Opus 4.5 (aka Clopus) entered the scene. Last time I felt this energy was when stuff like Express.js, Flexbox, and React came about and got everyone excited and frustrated.

My former colleague and developer-education extraordinaire, Simeon, told me he increasingly views his job as teaching agents how to use PlanetScale. When talking to some of the brilliant engineers I know, they report that even with Opus and Claude Code, it’s a mixed bag: some get a lot of mileage out of it for certain things, while for the more specialized or less represented problems in the training, it’s not working as well for them.

And then they also tell me about the experience of skill decay and that it removes the joy of figuring out a problem in code. While others tell me that it removes everything they don’t like about coding.

I can relate to all of it. And it’s making my head spin.

When my head spins, it has always helped to write about it.

This is what you are reading now.

It feels like we’re traveling through an uncanny valley between two opposing mountain sides, looking to our left, there is all of this amazing opportunity to be discovered, and looking to our right, there is pain, disruption, and uncertainty.

The side of hyper-creativity

On the sunny side of this valley, you walk the paths from ideas to proof of concepts with the greatest ease. You find yourself doing stuff with programming languages and technology that you didn’t before. Because the cost of entry was to darn high.

I was able to prompt a schema-aware eslint plugin, Sanity Lint, that wraps a colleague’s Rust code into WASM into life in a day (while doing my day job). This would have taken me at least a week or two in the before days. It even set up the npm publishing pipeline for me. Which I never want to do manually ever again. It feels very empowering.

I made it build a private finance planner tool on top of a csv of transactions.

I started making something akin to Clawd Bot myself over the holidays, but got stuck in the bureaucracy trying to get a phone number to work with Twilio (yes, would have been trivial to set it up with Signal, but I wanted to just iMessage it).

Clopus feels so powerful that I almost feel guilty for not having more ideas to constantly throw against the large language model wall.

I can offload a lot of the boring bits of my day-to-day marketing work, like gathering and organizing research, project reporting, and so on, and focus on the creative parts.

And with MIRIAD (an agent orchestration tool I’ve been using, vibe-coded by Simen Svale), I can deploy a small team of specialized agents and have them figure out a lot of the stuff between them, instead of me running around with markdown files, doing context management for the clankers.

In this mode, I find that what I bring to the table is providing the right cues and input to make the LLM figure it out quicker and better.

I also provide the “taste,” that is, knowing what good looks like.

When this work with LLMs “clicks,” it feels exhilarating and powerful.

It’s democratizing (for those who have the means to pay for tokens) in allowing more people to create with technology that only a couple of years ago felt beyond their reach.

The side of creative nihilism

But there is the other side of the valley where the shadows lurk. It’s the sneaking feeling that everything I spent two and a half decades learning is now… pointless? At least practically. It’s not like AI took away the joy I once felt when I figured out how looping over arrays work, or when I finally grasped the mental model of what a callback is.

But if anyone in principle can make something like Sanity Lint (the eslint plugin I mentioned) if they need it, why should I bother?

It also feels that so much of the engineering we’re doing around the LLMs is so temporary. We’re basically just figuring out how to put markdown files with instructions in the right place at the right time. And finding new ways of infusing the somewhat outdated model on how to write React anno 2026. It was “custom GPTs,” “projects,” MCPs, “sub agents,” and this month, it’s all about “skills.”

So it feels a bit pointless to dive too much into these techniques, because they will certainly be gone within a year, hopefully folded into abstractions where LLMs are orchestrated to understand the semantic field of your ask, and just load into context what they need to know about.

AI feels like toothpaste you can’t get back in the tube, but that was built by breaking the (western) cultural contract of intellectual ownership of your creations. It’s a bargain we didn’t consciously make.

Before the AI hike: some backstory

Back in the early 2010s, I was on a PhD fellowship trying to bring the digital humanities into the study of religion. My research asked if the huge corpus of digitized Norwegian newspapers from the 1700s until today (yes, really) could be used to tease out how the public used and thought about concepts like “religious” and “spiritual.”

Starting out, I had to look to computational linguistics for methods to run through the 70,000 articles that mentioned these concepts. I taught myself Python and became pretty good at regex. I installed undocumented Java applications to run statistical models. There was a lot of banging my head against the wall.

But all the methodologies were pretty much founded in the same principles: identify the word (aka “token”), decide how many words before and after you want to look at, and run your usual suspects of statistical methods (t-tests, chi-square, ANOVA, and so on) in various creative and layered ways.

For someone not trained in computational linguistics, discovering that these methods boiled down to counting word occurrences and calculating averages and variances felt like a dead end.

From means to fields…

And then I found folks working with kernel density estimation to map semantic fields of a corpus. Going from deductive statistics to inductive statistics let you explore a bunch of text in new visual ways. Instead of hunting for confidence levels and p-values, I could now look at my corpus as a two-dimensional map of a landscape.

…and into the multi-dimensional vector space

And then Google published word2vec. Introducing the idea that you could translate a corpus into multi-dimensional vectors, and then use the vector distance between the embeddings of two words to find similar relationships.

The famous example is that this model could predict that if you took the vector distance between man and king, then going from woman would take you close to queen. This worked for other patterns like small→smaller would match big→bigger. Or Norway→Oslo would give you France→Paris.

The kicker was that these patterns emerged from just training on the dataset itself. In other words, you could dig up these inherent relationships in language that emerge from language in a way we couldn’t easily do before.

It gave you a different lens at culture and human communication.

This is when I burned out. Not because of the research, but the brutal and unforgiving nature of academic institutions.

I don’t know how the computational linguists who’d spent entire careers counting words felt when embeddings arrived. But I suspect it rhymes with what I’m feeling now.

Because that was when I left academia and made technology my full-time job.

Climbing the strata of abstractions

And now I’m here again. With my profession being redefined by many metric tonnes of words cast into multi-dimensional vector space to be coaxed into prediction machines that force a conversation.

And like my academic days, it feels like we will have to figure out what the new layer of abstractions are.

Working with AI is a new skill set. And doing so without losing your professional self-worth takes a mindset shift.

We’re getting new jargon and methodologies. Getting stuff done with AI is easier and less frustrating when you understand what it really is and what the constraints are. Right now, it’s useful to know about context windows and how to work around them. Just as it was useful to really understand memory allocation back in the days (still is in some lines of programming, of course).

Yes, giving over to vibe-coding will corrode some of your development skills (because you’re not rehearsing them anymore), but it will also give you time to learn new skills, still to be uncovered.

Yes, using AI to generate content will make some of your writing skills atrophy, but it will also allow you to develop a sharper editorial eye and a deeper understanding of what makes content resonate with humans.

And what will be forever true: human institutions and innovations will remain messy, predictable, unevenly distributed, creative, and formulaic.

I’m still in the valley. The view from here is strange. But I’ve hiked out of valleys before.

1. Yes, existential in a fairly narrow sense and certainly from privileged position.

I installed it this morning. By the afternoon, my household had a working sauna booking system over chat. I didn't write a single line of code.

Here's what actually happened.

The problem (yes, it involves a sauna)

My local sauna spot in Oakland doesn't have an API. No developer docs, no OAuth, no webhooks. Just a Rails app with a booking calendar. I book a sauna almost every week, and the flow is always the same: open browser, log in, navigate to the date, scroll for a slot, click, confirm. Not painful, just repetitive.

I'm a developer. I could have written a scraper months ago. I didn't, because life.

What OpenClaw is

OpenClaw runs on your own hardware at home. You give it a personality, connect it to your messaging and services, and let it figure things out.

I named mine Nisse. In Norwegian folklore, a nisse (or fjøsnisse) is a small, bearded creature that lives in your barn or house. If you treat it well, it looks after the farm, does chores at night, keeps things running. If you forget to leave it a bowl of porridge at Christmas, things start going wrong. Felt right for something that quietly takes care of stuff around the house.

By mid-morning Nisse had connected to our messaging, set up our calendars, and learned our preferences. Then I pointed it at the sauna booking site and said: figure out how this works and build a way to book from here.

What the agent built (with some nudging)

About 20 minutes later I had a working MCP server. MCP (Model Context Protocol) is an open standard that lets AI agents use tools through a structured interface. The agent reverse-engineered the booking platform's session flow, wrote about 400 lines of JavaScript, and gave itself four tools: check availability, book, list upcoming, cancel.

I should be honest about the "20 minutes" part. It wasn't fully autonomous. It tried really hard to figure out if there was an actual API and gave up. But since the availability calendar was a client side JavaScript dingus, I guessed that there was something going on that implied some structured data somewhere.

So I had to nudge it once to look more carefully at the DOM for data structures it was missing. That was it. One hint. The agent figured out the rest: the login flow, the session cookies, the event ID encoding, the booking POST.

The booking platform is FloatHelm, used by a lot of float spas and wellness centers. No public API. The agent had to:

• Extract CSRF tokens from meta tags and maintain Rails session cookies
• Send XHR headers to get usable responses instead of HTML redirects
• Decode the event ID scheme (room, date, time, duration, and service encoded into one string: 1201875-2026-2-21-13-15-45--1213507)
• Parse calendar HTML with Cheerio to extract available slots
• POST reservations with the right "pay in shop" flag for our membership

None of this was documented anywhere. The agent inspected the site, tried things, and built a working integration. I tested it. It worked. We booked Saturday's sauna.

What it's like now

I message "any sauna slots Saturday afternoon?" and get back a list. I pick one, it books it, adds it to our shared calendar. My wife can see it. She can also message the same bot and book or cancel herself. OpenClaw is set up so we can have individual and shared workflows.

The weekly friction of booking went from "open browser, log in, hunt for a slot, click through" to a single message. Small thing. But small repeated frictions are exactly what automation should target.

The trade-offs

I want to be straightforward about what this is and isn't.

There's no API contract. I'm parsing HTML that was designed for browsers, not programs. If FloatHelm redesigned their markup, it breaks. In practice, their interface has been stable for years and the markup is clean, so I'm not losing sleep over it. But it's worth naming. And if/when it breaks, I can probably just ask Nisse to fix it (or it just does it itself).

Credentials stored locally. Fine for a personal tool on a personal machine, not a pattern I'd recommend for anything shared.

The code is duct tape. Tightly coupled to specific selectors and form fields. Good enough for a booking or two a week. Not production software. (Not trying to be production software.)

Here's the thing though

It's not about saunas. Most of the services we use daily don't have APIs. Your dentist, your gym, your local restaurant's reservation system. They have websites designed for clicking, not querying. The data is right there on the page, just not structured for programmatic access. Maybe WebMCP will help fix that?

The gap between "this website has the information I need" and "I can act on it programmatically" used to require a developer sitting down for an afternoon with browser dev tools. Now it requires a 20-minute conversation with your agent.

I suspect we'll see a lot more of this. Not because it's elegant (it's really not), but because it's practical. And the interesting thing about OpenClaw specifically is that the agent doesn't just execute tools, it builds them. I described a problem and it came back with a working integration.

The morning-to-afternoon thing

That's the part I keep coming back to. Not that AI can write code (we know). But the full loop: install a framework, connect it to your messaging, point it at an undocumented website, and end up with a working household tool that two people use through a chat interface.

Setup to genuinely useful, in one day, zero code written by a human. I'm late to OpenClaw, sure. But at least I showed up on the day it made headlines.