Designing delightful docs with Orta Therox, engineer on Microsoft's TypeScript compiler team
Orta Therox, Beyang Liu
How do you design software documentation and websites that both intrigue and educate? As a contributor to popular projects like React Native, Jest, Prettier, and TypeScript, Orta Therox has prioritized design for visual engagement, accessibility, and learning. In this episode, Orta talks about the importance of engaging docs, how experimentation fuels learning and engineering in TypeScript, and how developers can write better code examples with Shiki Twoslash, a project he developed and designed. Along the way, Orta also shares his own story of getting into code and the odd way he was hired on Microsoft's TypeScript compiler team.
Click the audio player below to listen, or click here to watch the video.
React Native: https://reactnative.dev/
GraphQL Codegen: https://www.graphql-code-generator.com/
Super Mario Maker: https://en.wikipedia.org/wiki/Super_Mario_Maker
TypeScript Playground: https://www.typescriptlang.org/play
TypeScript Docs: https://www.typescriptlang.org/docs/
Swift Playgrounds: https://www.apple.com/swift/playgrounds/
Shiki Twoslash: https://shikijs.github.io/twoslash/
Orta Therox: Yep. All of it.
Beyang Liu: Yeah. All of it. Orta, thanks so much for being with us here today.
Orta Therox: Thanks. I'm honored. I mean, the Sourcegraph podcast has so many good, interesting episodes that I've been listening to, to catch up on this. I'm really pumped to be here, and thanks for having me.
Beyang Liu: I'd like to kick things off with kind of a personal question. You've obviously done a lot of great work as a developer and designer and open source contributor. I'm dying to know, where did the journey start for you? What's your origin story as a programmer?
Orta Therox: I think in theory I probably have two true origin stories here.
Beyang Liu: Okay.
Orta Therox: I'll tell you them in order. Deciding to be a programmer and first starting to do some interesting programs, which for me was the process of being interested in video games and then being interested in making my own video games, and that sort of gradual using a game-maker toolkit style thing, like a Mario Maker is a good example. And then evolving that to a point where you needed programming to actually do something harder. That evolved quite naturally into building tools for building games, and then it turned that I spent more time building the tools than making the games, which is usually a good indicator that you're into building tools and not necessarily into building games, so I oriented how I was living and what I was doing to focus more on user interface toolkits and how bits come together.
But the second part is more interesting to this, which is like, at what point did I realize that open source was something that I really wanted to focus the last decade of my life on, for example.
Beyang Liu: Yeah.
Orta Therox: I grew up in a small town about an hour away from the closest big city, which is Manchester, with basically no mentorship resources available in programming. As a budding Mac developer back in the day, I really just wanted to know what it looks like to build big apps, and so I used apps like Quicksilver, Colloquy, Adium, all these things we don't really use any more.
Beyang Liu: Yeah, it takes me back. Quicksilver. I remember that. That was awesome.
Orta Therox: They're all open source, and so I would read the code, try to understand how all the pieces came together, take it apart, re-put it back together again. And through that, I learned how to do it. And today there are so much resources to learn to program in different ways, and a million different angles you could do it, but for me the best one was look at code, read it, understand it, move on. And I've always wanted to be able to do that for the next set of people. Not everyone wants to learn by watching a video and not everyone wants to learn by reading a book or a tutorial.
We mentioned the TypeScript Playground, right? The TypeScript Playground is exactly what I would have wanted to learn TypeScript from. It's a place to tinker in a safe environment that's easy to share, and that's how I ended up doing open source at scale. Slowly, slowly, just contributing more and more to these bits.
Beyang Liu: I think that's one of the joys of software development, especially in the present era. There's so many things that you can open up the hood of and peek under and learn how it works yourself. And it's really cool. Today, all the work that you do is in the open, right?
Orta Therox: Yes.
Beyang Liu: Because you so firmly believe in contributing back to the ecosystem that helped you get stood up.
Orta Therox: Yeah. Well, I guess I can still joke that GitHub follows me on Twitter, so it's a bit like being so active on Facebook that Facebook starts following you. Is that a good thing? But now that I work for Microsoft, we're colleagues, GitHub and I, in theory.
Beyang Liu: Yeah. Yeah. That's awesome. Okay, so you came for the video games but stayed for the open source, and it sounds like you got started in open source on Mac. Was CocoaPods kind of the first big community that you jumped into?
Orta Therox: Yeah, CocoaPods was the biggest open source community in the Mac sphere, before iOS anyway. In part, it's like the idea of a temple and a circus. You have the big things that create the ecosystem. That was CocoaPods, because prior to having a dependency manager, everybody would just upload the TILE file somewhere. You'd download it and put it into your project, and then if you wanted an update, you would move the files over and make sure the settings were changed, and CocoaPods changed that. And I wanted my work to have this sort of... maybe not exponential, but I wanted the work I had to be multiplied by the ecosystem I was working on. Any time spent on CocoaPods was a multiplier on everybody's time, so it felt like a very valuable use of my own time, in my spare time, to work on this dependency manager. It was pretty budding when I got to it, and by the time... I'm still pretty actively involved as far as everyone else is.
10 years later, and having moved from native development to React Native development, to working purely on TypeScript, two serious hops away from that sort of thing every day. But sometimes you just need somebody that's been doing it for long enough to still be around to make decisions.
Beyang Liu: Yeah. I think it's interesting. I feel like if you're just getting into development these days, you're kind of spoiled because every major language ecosystem, I think, has a package manager now, and it's seen as table stakes.
Orta Therox: Yeah.
Beyang Liu: But back in the day, so to speak, iOS Objective-C, there's no package management system.
Orta Therox: Yep.
Beyang Liu: Before CocoaPods there's like nothing.
Orta Therox: And before the ecosystem vendor, Apple, just said that's not a problem that needs to be solved. You shouldn't be sharing code, was actually their opinion, and thus CocoaPods was reactionary even to that, the idea that open source could exist was a push in that ecosystem at the time. It's much less now, obviously.
Beyang Liu: How did you go from Mac and iOS native development into the JS and TS and web world?
Orta Therox: Pretty smooth transition. I was forced into it.
Beyang Liu: How so?
Orta Therox: Well, React Native is such a compelling use case in comparison to native code. I had wrote native code for about 10 years when React Native come along, and I knew all of the flaws of native code that can also be seen as positives, but also iteration times.
Beyang Liu: What were the big trade-offs in your mind?
Orta Therox: Native code tends to be more complicated, because systems tend to be more separated. Okay, to give more specific examples. Think about it as if your website required you to code sign one part differently to another part, if your mobile version of your app had to not be sharing a domain, but it had to be a completely separate app bundle that would be included, but may also have different code signing rules, and all of those... each one of those also needs to be compiled in specific ways. Those are reasonable problems that you solve once or twice a month. But the hard one is just iteration times are absolutely terrible, especially if you're targeting for a device that's not the device you're working on. Then suddenly you have to build for that device, send it over, restart whatever simulator or emulator you've got going, then you're up and running, and you lose all state and things like that.
Apple definitely took about a decade to get on board with trying to improve that iteration cycle, but realistically, even their current approach, which is SwiftUI, it doesn't actually run your code and hot-reload it. It actually runs it separately in a sandbox that isn't your application, so it's not actually that accurate. It's just close enough. And so, you still don't get the React style. I press save and it does it all.
Beyang Liu: Yeah. It's magical.
Orta Therox: All those things were such compelling cases to React Native. There was just so much React advantage, and then there was also we got the advantage of using Relay, which is a really powerful way of connecting your API to your client. And we said that the apps I was working on, at Artsy, these were apps that were just pretty JSON parsers, and native development SDKs, these are really built for building long-running applications like web browsers or your music player, messaging apps, not these quick, like, "Get me some JSON data, put it on a screen and then don't do anything until you click something next."
Beyang Liu: Yeah.
Orta Therox: React Native provides these much better abstraction layers to be building these sorts of almost webpages-style applications. So it was very easy, once we'd made the transition, to think in terms of React instead of thinking in terms of individual native toolkits.
Beyang Liu: Got it. That was a decision... you were working at Artsy at the time-
Orta Therox: Yes.
Beyang Liu: ... and so the team made that decision to transition over from native iOS development to React Native?
Orta Therox: Yep. Just for iOS, and then I think three years later, just a little bit after I left, launched an Android app.
Beyang Liu: One of the things I really appreciate about your work is it's not just about the code for you, it's also about the design and the accessibility of the documentation. You mentioned that you used Relay, and I know that you played a major hand in the design or redesign of the Relay docs. Can you talk about that experience? How did you come to get involved in that?
Orta Therox: To give anybody who doesn't know the background on Relay... if you've heard of GraphQL, Relay was the thing that people were meant to like, and GraphQL was meant to be the side thing that powered Relay, and instead it turned out to be the opposite way around. But Relay is almost like a compiler-level checking of all of your GraphQL queries in an application. It really binds them tight together, the user interface and the API schema, in ways that today people will do using Codegen and things like that.
But a lot of Facebook open source projects, open source in name and maybe less in spirit in the fact that what they are doing is they are shipping open source code and they are generally contributing back to the ecosystem, but these projects are Facebook led, for Facebook, and you guys can use them if you would like to. Flow has very explicitly stated that very recently, and Relay is that way. And if you talk to anybody that uses it, they'll know that because they-
Beyang Liu: This is in contrast to other open source projects that have more of an independent community-led development?
Orta Therox: Yeah, I think the contrast there is that, TypeScript is a good example of the furthest edge of... TypeScript's a little bit dictatorial like, "We're the only people that make the hardest decisions," the TypeScript team. Whereas something like Rust will have pure RFCs for everything, and it's very democratic. But in all these cases, that is open source where the community gets equal input to bugs, features and pull requests, and the core contributors take the time to make sure that we keep the community PRs smoothly moving in, and we don't let them pile up too much.
On a project like Relay, that's much harder because the engineers don't have time to work full time on the community management aspects of it, which is very time consuming at the sort of scales which we're talking about here. You should feel some of that. Sourcegraph has quite a lot of developers doing a lot of interesting work.
Beyang Liu: Yeah.
Orta Therox: For Relay, there was just doing documentation, trying to explain Relay and trying to get people involved and understand what the relationship will be between them and Facebook. Pitching it wasn't really a priority to them. They were just happy that they had it open source. They don't necessarily want it to become as big as some of the GraphQL libraries that are out there, because that just means more work for them in their spare time.
We adopted it early at Artsy, and we actually spent a lot of time explaining regularly to new employees and to other community members why we use Relay. Instead of explaining it enough times, I took a bunch of rough blog posts that I'd had on the concept, sort of pitched to the Relay team that I should redesign their homepage to answer a lot of the questions that people are asking, those at Artsy about Relay, and move that out into their official introduction to that process. And it was fun. It's always an interesting problem trying to do, like how do you pitch an open source project? We struggled with it on TypeScript. I'm on the fifth redesign of the TypeScript homepage right now.
Beyang Liu: Wow.
Orta Therox: And this one might be good enough to go public with, but we're still not sure.
Beyang Liu: What do you think about when you go into a redesign like that? And maybe with Relay specifically, how did Facebook message or market it originally? What were the major changes that you made in explaining what it exactly did?
Beyang Liu: Yeah. Esbuild is so fast, it kind of completely resets expectations for what's possible...
Orta Therox: It totally does.
Beyang Liu: ... in the JS toolchain world.
Orta Therox: Yep. And that's basically all they'd tell you. They tell you that the thing underneath is very fast and that the thing is very secure, in terms of the data that you get wrong. But you can't just describe Relay and those things, because somebody is going to put that next to the Apollo homepage, of which Apollo has a lot of great designers and developers trying to figure out what is the right way to sell a GraphQL client.
Beyang Liu: Apollo is another end-to-end GraphQL framework, also has a great company behind it.
Orta Therox: Yeah. Part of the current generation of open source cool kids, like Gatsby, Vercel and...
Beyang Liu: Yeah, yeah, yeah.
What I did instead was tell the story of Relay. Why would someone want to use a system that is quite blatantly more complicated than the vision that you've probably already heard of? Right? If you care about GraphQL clients, then you probably already know about Apollo because they do a great job and a lot of people use it. Somebody is coming to Relay already with a thing of like, "This is probably what I'm going to use, but I'm just checking out the competitors. To know that I am making a reasonable decision, because I've at least checked the other avenues." You need to be able to talk someone through. Like, "Okay, here's why you should care about this particular feature, which is fragments of the main way in which you interact with GraphQL queries." Which, if you don't know what fragments of GraphQL queries are, it doesn't matter. But it is just the way in which you think about it requires a different abstraction to the way in which you normally think about it, and to get you there, you really have to explain it three or four steps before that.
You can't just have a single line that says, "Use fragments to tie your queries to whatever." You really have to be like, "This data is needed here but not here, and if you use a fragment, then it will appear only there." That description requires so many levels of iteration to get to a point where it reads pretty reasonably and you feel like you actually understand how you got to a decision to use this.
And why Facebook use it still, right? They rewrote the entire Facebook.com using Relay everywhere and supposedly they love it in Facebook. I don't know how they got around the lack of docs, but I think they've been doing a lot of work on that lately to try and fix that, in part because they redid facebook.com.
Beyang Liu: Yeah. It's so funny to see the contrast between level of documentation for open source projects versus internal libraries. You would think that this is something that's important enough to be private and part of your company's core codebase, that documentation would be a first-order concern, but there's a huge documentation gap.
Orta Therox: I bet the opposite's completely different. It's like, "Oh, this is just our code. Nobody needs to see it. We don't need to document it. You can just go and tap on someone's shoulder and find out the answer instead of writing it." Yeah, it's very difficult. And then if it's open source, then it does need to be better documented, because it's a representation of what your internals looks like to the rest of the world.
Beyang Liu: I think one of your goals has been to up-level the design and documentation of a number of open source projects. In addition to Relay, you're involved in Jest-
Orta Therox: Yeah, Jest.
Beyang Liu: Prettier. Any interesting things with those projects that are worth sharing, in terms of the documentation and the design, and what changed when you got involved?
Orta Therox: I think a lot of them always is the thing that really gets me to start working on it is that I come up with a hook that really resonates with me personally. For Jest, if you've not been to the Jest website, Jest has a deck of cards that actually animate into place in front of you, and then it shows this little spinning thing on the back of them. They flip. It tells whether it's passed or failed. When I came up with that metaphor in my head, I just knew that I had to design the entire page with that as a core principle of here is the thing, how Jest can be visualized in an interesting way, and then I think from there you can then start saying, okay, these card metaphors can be used to these other things and you can describe the entire structure of Jest and its advantages through a lens of that.
Prettier, I had the same thing, which is like Prettier's logo starts off completely messed up and then prettifies its own logo and so it symbolizes its own, the actions of its own system. And React Native, for example, I had the idea of... you know you have this view DOM at... You don't think about it that way when you're a native developer, so I wanted to try to show this interactive pattern that you don't normally think about when you're a native developer, in a way that feels natural to a web developer.
But the thing has always been like, this is such low-hanging fruit. These are massive projects with millions of weekly downloads. The way in which they describe themselves can be different, depending if you're external and internal. In part, when I came to TypeScript I was a completely external person. I knew nothing of the internal baseball of Microsoft, and I didn't have any of the prior history to TypeScript, so it's not like I had been in the team for... I think TypeScript's about eight or nine years old now... and had all that baggage. Back from when TypeScript was a very small project and it had to be very cautious about how it described itself, especially when the view of Microsoft has changed a lot over the last eight years, too.
Beyang Liu: Yeah.
Orta Therox: TypeScript used to have a very tiny, "This is a Microsoft project."
Beyang Liu: I remember when it first released. This is still during the pre-refresh of the Microsoft brand. I remember thinking, this is a trap of some sort.
Beyang Liu: Yeah. You mentioned there's this gap between how the internal team, the people actually building something, view it, because they have all the in-depth knowledge. They've been thinking about it forever. They're kind of expert users of their own system. And then how newbies perceive it, external people, are coming to the project for the first time. And it seems like that informs a lot of your design goals. It's like making these frameworks and technologies accessible to newcomers.
Orta Therox: Yeah.
Beyang Liu: And when we were talking earlier, you mentioned something interesting about TypeScript itself, the way that... When you joined the team, what was the gap, in your view, between how they perceived what TypeScript's purpose and value was and the value that you saw in it, as someone looking in from the outside in.
Orta Therox: I think it's that I had a more concentrated perspective of certain sets of things, because even internal to TypeScript, there's very little consistent agreement on what TypeScript is and where its edges are. TypeScript has a design document that says, "These are the 10 golden rules of what TypeScript will be and won't be, so we'll try to never break those." But public perception and external perception is very different. For a lot of people it's very rare to think of TypeScript as being buggy, but from internal perspective we are getting hundreds of comments a day saying, "This thing is broken in this way and this." We've got 5,000 open issues. A lot of them are very reasonable.
From TypeScript's perspective, they've just evolved, and so TypeScript has an infinite backwards compatibility guarantee, to a reasonable extent. If you had a configuration set up today... well, from five years ago... it would still probably work, but you would get a lot of compiler errors now. Think about it as like the project settings will still be the same, but the actual thing will be different, which can also sometimes be a bit of a noose around TypeScript's neck. A good example is decorators, which TypeScript adopted very early in order to get Angular support, and decorators, maybe next year, will be spec-ed out properly and that will be different from the one in TypeScript, so we'll have to retain-
Beyang Liu: Interesting.
Orta Therox: ... old decorators and new decorators in the same codebase forever. Can't break Angular.
Beyang Liu: No, that's a big project. A lot of people depend on that.
Orta Therox: From TypeScript's perspective, most of the engineers on this team have been here for 5+ years, so when I came in I was like, "No, TypeScript is massive. Everybody uses it. Almost every major codebase I have used is in the process of moving to it or has moved to it." When you tell me that we have these stories of people migrating away from TypeScript, in the last two years, I've read maybe three or four blog posts ever about that. And internally they knew that people migrated away from TypeScript because people used to migrate away from TypeScript. I'm not saying that there's never going to be a time when people don't migrate away, but that the value of the types and the tooling are enough to keep people, even if they're not happy with the way in which errors can be presented, because that's a very complicated thing, too.
There was a lot of naïve external persons saying like, "Hey, look. I've never seen anyone migrate away from TypeScript," and all these big Flow projects are moving to TypeScript now. The perception of what you think TypeScript is and how it is seen from the outside are very different.
Beyang Liu: Can you tell the story of how you joined the TypeScript team?
Orta Therox: Yes.
Beyang Liu: Did they recruit you or...
Orta Therox: No. They had a GitHub issue. They said, "We are hiring," and I pitched specifically that I would not be a good compiler engineer.
Beyang Liu: The hiring req was for someone with a compiler background, right?
Orta Therox: Yeah. And so, I tell juniors, apply for a senior job, and conceptually I have done the same thing here. I applied and said, "Well, I'm not actually what you're asking for."
Beyang Liu: That's awesome.
Orta Therox: And I said that TypeScript is like a little village and there's a castle, and that's the TypeScript compiler, and it powers all this tooling and all these other things. But the scope of TypeScript has this massive ecosystem of people building tools using TypeScript, using the language, doing the parsing. And all those folks are not really being catered to by the TypeScript team, in part because the TypeScript team is a bunch of compiler nerds and they want to be doing compiler-y stuff and the documentation and the web infrastructure and stuff like that. Whilst it gets done, it's not a core focus for any of the individuals on the TypeScript team, at least prior to me, and so the problem was that a lot of the good stuff was all closed source, too. When I wanted to contribute to the Playground or to the TypeScript website, I couldn't because none of that was available for me.
Beyang Liu: Huh. A lot of the tooling in the ecosystem was still closed source in those days?
Orta Therox: Yeah, the web and documentation infrastructure.
Beyang Liu: Interesting.
Orta Therox: It wasn't something that I could just... I couldn't just go like I did to Relay and just say I will redesign all your stuff. Here's your website, so I will do that. It was much harder to be able to do that to TypeScript. Plus it was also a commercial entity in ways that others aren't. That would have made it hard to just go out in the blue and say it. Yeah. I pitched that ecosystem outreach and trying to figure out what it looks like to be from an external person interacting with TypeScript was what I pitched, and I must have won against compiler engineers to get that space.
Beyang Liu: You sold them.
Orta Therox: Yeah, exactly. Honestly, I think I've done a good job of this. I think I've got a lot of the good documentation out. We've got new handbooks, we've got new... the Playground is some of the best work I've ever done, to be honest. It's this incredible environment for doing all sorts of great things in. And I think for anybody using TypeScript, it is much easier now to learn TypeScript and to jump from... intermediate to experienced is still a bit of a gap, but almost every other part of the TypeScript learning process is now significantly better.
Beyang Liu: Can you talk more about the Playground? Because I think that's one of the most delightful pieces of the TypeScript documentation, the learning TypeScript experience. A very limited version existed before you. How did you come in and change that and completely revamp that?
Beyang Liu: It was controversial.
Orta Therox: It was controversial-
Beyang Liu: Yeah.
Orta Therox: ... and you wanted proof, and you wanted to be able to see that the code that you were putting in made some sense. And that was the goal of the TypeScript Playground, which is obviously quite a different goal from what the Playground is today. And so, what I said coming in was I wanted the Playground to be an environment for learning in. I want the Playground to be an environment for experimenting in, and I want the Playground to be an environment for compiler engineers to use to pitch and prove their ideas and improvements. The third one is maybe the quickest, so I'll start at the end and work backwards.
Beyang Liu: Yeah, yeah.
Orta Therox: All of the features that I pitched, I wanted to make sure were also good for the TypeScript compiler team. An easy way to set any possible configuration variable, an easy way to be able to choose a different version of TypeScript at any point in time, and nightly builds would be available inside the Playground, so those are sort of decoupling of the version of TypeScript from the user interface at the website that needed to happen, but nowadays it's very common for almost any complicated feature being built in TypeScript, to just ask for a Playground build that you can just do on the TypeScript pull request.
Beyang Liu: That's amazing.
Orta Therox: And we make a Playground for it. And that gives people the environment to be able to play around with this, as though it was a real editor and as though this is a real version of TypeScript. And it is a real version of TypeScript, and it is obviously a real-ish editor. That's really great for the TypeScript team.
Then for the other two, it's like there's an infrastructure called the Playground Plug-in System, which allows anybody to make their own individual plug-ins to the TypeScript Playground. Think of it like VS Code extensions, but for the playground. And there's not that many other people using it, but I am using it a lot. That means it's a great abstraction in my mind, because there's tons of ways in which, as compiler engineers, we have different needs from other people, and I can build these one-off plug-ins for compiler engineers that nobody else needs. Rather than jamming the Playground full of really clever, complicated tools for understanding the TypeScript under the hood, instead I can just say, "Hey, just install that plug-in and now you can see the results of a scanner, of a different point in time and see how a Flow graph is generated for things."
Beyang Liu: That's really cool. Is it very much like an editor plug-in, where you get these in-line annotations into the code? Or like certain highlights or things like that?
Orta Therox: Yep. It's all of those. Yeah, exactly. All those APIs are available for you, so it just depends on what you need. That sort of thing, again, is a really great thing for the TypeScript compiler team, and really great for individuals, because people can play, even make their own plug-ins. Somebody added Vim support to the Playground via a plug-in, as well as people that are also exploring, "How do I share the code?" I built a real-time collaboration tool so you can have two people on the same Playground at the same time. There's all sorts of things that that is available for, which kind of brings us neatly into learning.
I mentioned earlier that there are so many different ways that people do learn, and a great set of documentation does many things, but you usually have a guided tour, like the main tutorial. In TypeScript we call that the Handbook. And then we have lots of reference pages. If you want to go deep dive on something like what happens when I click on a name, a path, and it finds it way to somewhere else? What is the module resolution? That sort of stuff you can get in the reference, and that's complicated code, so it's very complicated reference documentation.
Beyang Liu: Yeah, yeah.
Orta Therox: But there needs to be somewhere between, "I can read from A to Z" and "I would like to build a system where I can play around once the ideas have been presented to me." Almost every code block in the new TypeScript Handbook has a click to go to the Playground with this code inside it, where you can then instantly try and figure out, "What happens if I change this or if I break it in this way? How does that look?" And so, the Playground is considered one of the tenets of learning TypeScript. Maybe even further, in the fifth redesign, maybe considered almost the second level of importance with the Handbook. And in that case, we present you with this list of topics like, "Here you go. You want to learn about sets." You click on this and you're in a Playground with sets, comments everywhere, and you can just type in whatever you want and see how it works.
Beyang Liu: That's awesome. It's like learn by doing. Get people into the code and tinkering and playing around with it as quickly as possible.
Orta Therox: Yeah, exactly. And that's the goal. And the Playground does a really good job of giving people an environment to work in. I always compare it to the Swift Playgrounds. Apple have really good, really solid little iPad app that you can use to just play around with the language and try to understand how it all comes together. I take a lot of inspiration from how they are doing it, because they're a fully staffed team working on one thing, and Playground is one of my side projects, so just trying to get it all together.
Beyang Liu: Yeah. When I think about the programming language ecosystems that have really been successful, a lot of the times I think the major reason for their success is not just the language itself. Obviously the language is important, the syntax and the type system and whatnot. But the whole ecosystem of tooling around it and the overall developer experience plays such a big role, because that in turn leads to... Almost like a coefficient of how easy this thing is to adopt or-
Orta Therox: Adopt?
Beyang Liu: ... dive into, and that feeds into, if you try to model it out, that's your growth coefficient. Every percentage or every point that you can reduce or-
Orta Therox: Increase the friction?
Beyang Liu: Increase that coefficient... Yeah. Yeah. Your slope goes up and that increases the likelihood you'll reach critical mass and take off velocity and all that.
Beyang Liu: When I think about Flow versus TypeScript... and I'm not an expert in either, so this is just pure speculation on my part... but when I think about why TypeScript has seen wild success, to the point where it's so deeply integrated into the JS ecosystem that a lot of the NPM package... even if you're writing pure JS, chances are a lot of packages you've installed were written in TypeScript and then transpiled into JS. Whereas Flow is still... to me it seems like very Facebook-centric, and I almost feel like the starting point... Like you said, originally if you'd asked me back in 2014, 2015, which one of these would become more dominant, I'd be like, "Flow."
Orta Therox: Flow.
Orta Therox: Yeah. I can't stress enough how the higher-ups in Microsoft are making good decisions here. All the way from eight years ago when TypeScript was pitched, all the way to still now, in the highest levels of Microsoft, TypeScript is just considered... not even this golden goose that's continually laying these eggs. It's just like, "This is a really successful Microsoft project. We don't want to interfere with it. We want to make sure that we're steering it in a way that fits with VS Code and Visual Studio, but not to the detriment of the language, especially not to the detriments of VS Code and Visual Studio. But that it feels good and it still feels somewhat Microsoft-y."
The organization I'm in is called Development Division, and it's all just development tools. And it's very different because normally these tools like TypeScript live in a completely different one, like the languages and ecosystem tooling space. We don't answer to the F# people or the C# people, but almost every other Microsoft language does. And this was an experiment in trying to give it its own space to...
Beyang Liu: Interesting.
Orta Therox: ... to work out. And it's obviously worked out well, and a lot of that is owed to the higher-ups that normally you would never even think about as being involved in something like this. Just saying, "Yeah, we'll give it a shot and we'll see where it goes." And it worked out. Someone had to have said the same for VS Code, right?
Beyang Liu: Yeah.
Orta Therox: That's like taking the thing that gets you almost as much money as maybe Windows, Visual Studio, and just saying, "Yeah, we'll make a free competitor to it. Sure. Give it a shot."
Beyang Liu: Yeah.
Orta Therox: They did it, though. Obviously it worked. But that takes a level of vision that is hard to think that I would have made those same decisions, is maybe the right way to say it.
Beyang Liu: Yeah.
Orta Therox: You want to protect your babies, and making the first open source language that is well used outside of Microsoft was probably not something someone wanted to necessarily give that control away.
Beyang Liu: The way I think about it is like long-term self-interest versus short-term self-interest. And a lot of times it's so easy to make those short-term self-interested decisions, where you locally optimize, but then lose sight of this bigger opportunity, both for you and the surrounding community that you're trying to contribute to and thrive in. And it's a big bet, right? It's harder to justify. Someone has to step up and take a risk and say, "We're going to do it this way, even though it's not directly tied to the bottom line in any of these divisions. We think this is overall going to be better for Microsoft and better for the community at large.
Orta Therox: The ecosystem.
Beyang Liu: Yeah.
Orta Therox: Yeah. I think TypeScript has done a good job, and Microsoft, and especially the app division, has done a good job of knowing when to make the pie bigger versus when to try and make your slice of the pie bigger.
Beyang Liu: Yeah.
Beyang Liu: Well, I want to talk about Shiki Twoslash, because that's the new thing right now that you recently released, and it's really cool. Can you tell us, what is it and why is it useful?
Orta Therox: Sure. I love Shiki Twoslash. One interesting thing is, I've probably only had a few good ideas in my entire life... I know... but what I'm really good at is taking somebody else's good idea, that they have a rough idea of and maybe could turn out well, and just be like, "I'm going to take this and I'm going to polish it until it's incredible." And that's what I did with CocoaPods and that's what I did with Shiki Twoslash. There was a rough draft of what the TypeScript new documentation could look like before I arrived, and one of its things was that we verify every single TypeScript documentation, sort of code chunk, ahead of time, so that we can know that docs are not out of sync with the compiler.
Pretty common thing, like a linter system, kind of novel tooling, and someone said to me, "Well, what about if we try and take some of the editor features and put that in there?" And I was just blown away with like, what does it look like to sort of statically take all of the interesting IDE features and put those inside the code blocks? It was not really a space that anybody else had explored. We had to think about what does it look like to create special code blocks with TypeScript-specific markup in there. And it turned out that TypeScript already have two different flavors of markup inside the codebase for the compiler. I know.
The TypeScript compiler's testing system is mostly integration tests, so basically we make it so very trivial to create a single file that represents a complicated TypeScript project, and there's two different ways to do that, depending on the way in which you want to test. That's either a fourslash test or a twoslash test, both of which have different markup semantics. I took the idea of twoslash out of the compiler and re-implemented it myself in a way that it would run on the web.
Beyang Liu: I guess really quick, twoslash is like... it's called twoslash because there's two slashes and then you have some sort of metadata in that... The compiler will interpret it as a comment, but then in the comments you have these annotations that are semantically meaningful for the test that's being run, right?
Orta Therox: Yes. Yeah, exactly. We just call it twoslash because it's just a normal comment. And then you usually put an @ after it to indicate that some work is about to happen, and that will get erased from the end result of your code sample.
Beyang Liu: Yeah.
You write, like how Markdown turns to HTML, you would write twoslash-style TypeScript and it comes out as a normal TypeScript file with a lot of additional metadata on top of it, and then that then is this really rich, really powerful tool for describing complicated code. And the thing about something like Shiki Twoslash is that it actually requires a little bit of understanding to get to that point, too. It's a bit like Relay, in the same way. If I told you you could get cool syntax highlighting on a code sample, that's uninteresting because that's available, because that's a baseline.
Beyang Liu: Right, right, right.
Orta Therox: If I tell you that you can run the TypeScript checker on your code samples, that's at least a little bit interesting because you can keep that running over a long time period, and you know that your code sample's not going to go out of sync. But if you tell someone that you can get the code samples were checked and then that provides all these extra user tools, all this great user experience for people reading the code samples, that's when people get excited. But you have to reach that point through explanation first.
Beyang Liu: And for those listening, you should just go to the Shiki Twoslash docs page. They have the embedded code snippets that the project itself emits, and you can see for yourself. There's hovers and autocomplete and a lot of the standard editor niceties, but in an embedded code snippet in the documentation, which is-
Orta Therox: Yeah. That's done entirely in markup, and it's all static HTML.
Beyang Liu: That's awesome.
Orta Therox: Yeah, exactly. And I think it's-
Orta Therox: Yeah. Because it has to run inside of ePUB, in a PDF, so it literally has to run in all these different environments, so I cannot make assumptions like that, which because we wanted to be able to ship a handbook to people to read offline, and that needs to be autogenerated, and so all of this stuff needs to... These were constraints in the TypeScript website that turned out to be useful for almost any documentation.
Beyang Liu: That's awesome. I was just going to say, the code snippets I feel like are always the most useful part of the documentation for me. A lot of times I just go from code snippet to code snippet and copy and paste a bunch of stuff to try it out and see how it works.
Orta Therox: That's why they have a Try button on them in the TypeScript website, so that you can do that really trivially. The advantage here in Shiki Twoslash is that we can just show you a bunch of these code samples in a row, and we can highlight the parts that are interesting to you as you go through. And you don't have to think about it too much. The current redesign of TypeScript website actually does this at a meta-level layer, so I'm not sure if it will go into Shiki Twoslash as an abstraction, but it might, which is I want the ability to annotate a code sample from outside the code sample. Think about it as I want to be able to write a marker note and point at a particular line or symbol, because I want you to... This is the thing I want you to be thinking about, and I want to give you these sets of ideas ahead of time so that you can skim through these code samples and be like, "Yeah, that thing. Yeah, that's what I was thinking it was." And then seeing these annotations.
That is the future of Shiki Twoslash probably, but also the future of how we're describing TypeScript, because showing the code samples and then showing what is the rough TLDR here? I think is better than trying to have some text ahead and after trying to describe it, because people won't read those, but they would read it if it was attached to the code sample.
Beyang Liu: Yeah.
Orta Therox: User testing. People don't read. People skim.
Beyang Liu: Especially in this day and age. Attention span, they're like...
Orta Therox: Yeah, exactly. Yeah. It's incredible watching people use the test, the website. For all the ones that I talked about as a cool pitch, then people play with that concept for a bit and then just scroll down, but I can't do that so much for TypeScript, because it's a bit more serious, so I need to have these ways of making people skim and be able to understand enough to be able to decide whether to make a decision.
Beyang Liu: Yeah. Let's talk about the visual design of the Shiki Twoslash documentation itself, because it's very old and unique. And I'm going to kick this off just by reading the intro section of the documentation, just to give people a flavor of what the style is like, because I think the written style reflects the visual style, too.
It begins, "The documentation concerning the NPM modules of Shiki Twoslash, in which Markdown code samples are powered by the syntax engine of Visual Studio Code, mixed with the TypeScript compiler's information by Orta Therox, purveyor of renowned open source code and TypeScript compiler team member."
Orta Therox: Yeah. It's just perfect. The entire thing...
Beyang Liu: It's like old-school.
Orta Therox: ... has this great old-world... yeah.
Beyang Liu: Shakespearean almost.
Orta Therox: Yeah. My first draft for this actually had more of the documentation in this old-world voice, but after reading a few paragraphs of it, it actually gets quite... you start to really zone out. I'm like, okay, it can work above the fold, but it probably can't work below the fold.
Beyang Liu: Yeah.
Orta Therox: There are unbelievably great tools today for creating documentation websites, especially the two key ones are Docusaurus, and Tailwind also does a great job of having really great foundations for anybody to recreate a good website without design skills. And basically, to some extent, all these documentation websites, they're all starting to look the exact same. And I have enough skills to really play around in the space until I really feel like try and make it stand out on its own feet as well as being a pretty complicated tool like Shiki Twoslash. I really wanted to go deep on a really creative take on this sort of design work, and I'm really happy with how it turned out. I actually-
Beyang Liu: It's beautiful and gorgeous. Yeah.
Orta Therox: Thanks, yeah.
Beyang Liu: And unique.
Orta Therox: Exactly. One of the things about the Shiki Twoslash is they've actually, if you scroll down to the bottom, there's a link that takes you to my design document, and you can actually... I left every draft of the Shiki Twoslash website in the design document so you can actually see it evolve as a concept. Yeah. I originally had this idea of 1950s ice-creamy Americana thing going on, and then I felt a bit off on that, when then one day just found this incredible book. I saw this book and was like, "Wow. I really love the style of this book. I want to copy the book exactly and try and get the feel of it." Once I got far into that iteration, I realized that it just doesn't feel right. It felt muggy, muddy, like trying to emulate the book too far made it not feel like a...
Beyang Liu: Which book was this?
Orta Therox: It's a maths book that was one of the first ever book to include graphs. They didn't have any of the rules that we have about you put a graph in particular position, the order of things is this way. It's just text intermingled with pictures everywhere. They had a very limited color palette, and once I got far enough into copying the book, I realized that I just couldn't copy the book, and I needed to take the ideas from the book and re-apply it into a modern context. And that's what you're seeing today. You're seeing 1600s ideas re-applied using today's tools.
It's built to still feel like a book, but it's not telling you that too much. The structure of how there is a side margin that's meant to emulate the edge of a page, the way in which it describes itself as chapters is meant to make you think that this is old-school, but not get in the way in a way that an old-school system of design would have.
Beyang Liu: Yeah.
Orta Therox: It's like good skeuomorphism is how I like to think about that sort of idea.
Beyang Liu: That's so cool. And you mentioned that a lot of the other documentation sites are starting to look the same, in part because there's these standard, popular, automatic docgen tools now, and you get a great design, but it's the standard design. But I almost feel like it almost becomes self-fulfilling at some point, where now it's not just because people are using the same tools and they end up with the same design. Actual human designers are starting to move companies' design to this plain, featureless, vanilla Helvetica-esque aesthetic, to the point where logos now, which used to be all sorts of different fonts and colors, it seems like we're all just converging on the same platonic ideal. What is your take on this interesting trend in the design world?
Orta Therox: I mean, it's fashion. It will go away in time. It's not my bag. My design style is very big, bold colors, very flat but still using depth in interesting ways. And, as I mentioned earlier, and I'm air quoting, "good skeuomorphism." Reusing existing concepts that people know about in order to not have to learn all of these different things. Again, the tools are so good and so easy that almost every website will slowly move to use Tailwind and we'll be in similar stage as where we were with Bootstrap.
Beyang Liu: Yeah, I was going to say, it's the new Bootstrap.
Orta Therox: That is both good and bad, right? Bootstrap is more restrictive than Tailwind is, so conceptually you can see more experimentation in using Tailwind, but at the end of the day, yeah. If you want a website that looks like a 2020s tech website, you use Tailwind. That's it, and it will look that. And it will tell you something. I have a side project called Capture with some of my friends, which is automatic Zoom recording, and it sends it off into Google Drive or something. And we just reused all those design ideas to make it look like a tech website, and that was the goal. The goal was, look like a generic tech website so that people will look at it and be like, "Oh, yeah. Okay. If it looks like all the other ones, then it must be as high quality, blah-blah-blah, as all the rest of them." And so that can be a shortcut.
Beyang Liu: But Orta, I thought the whole point of design was to project a unique personality into things. Is that not a big part of it? Are we forgetting why?
Orta Therox: It's a reasonable statement, right. Almost every website nowadays will use something like Tailwind, will have the flat humans on it in multicolored ways. And that will look same-y, simply because everybody's using the same design assets and more or less the same color palette and the same CSS frameworks. And that is just how it is going to be for a while. And that is okay. If it's empowering people to do things, not every artist has to try and go for impressionism. Lots of people are just trying to pitch an interesting idea in other ways.
I've yet to build a website that looks like a Docusaurus one or even looks like a Tailwind one, but I have used Bootstrap to build the CocoaPods web page. That doesn't look like a Bootstrap website. These tools are things that you can build on top of, and there will be people experimenting in these spaces and do really interesting work.
I think GitHub are doing really great design at the moment. I don't know if you saw, for example, the new GitHub issues page that came out recently.
Beyang Liu: Oh, yeah. It looks snazzy.
Orta Therox: It looked really snazzy. Yeah, exactly. I wouldn't be surprised if that was built on something like Tailwind. The designers there are taking the ideas of Tailwind and reusing the existing concepts, and actually just mixing them together in a way that completely feels unique, and still feels like GitHub. I think trying to figure out consistent brand identity is something that would be...
I think you need a designer to be thinking of that level of abstraction. It's quite rare for an individual programmer, and especially in open source, where people don't necessarily need to think much about the brand outside of persuading people that it's a good tool. When I joined Jest, I was like, "You should have the logo be the word Jest written out in a way that can fit in the console, too, so they would match." The TypeScript logo is now in the Help for TypeScript, because it's just a square of blue with TS.
Beyang Liu: Yeah.
Orta Therox: And connecting all those dots together and making it all feel like a cohesive strategy, it's not really something a lot of people particularly find fun, probably.
Beyang Liu: There's a whole design system, in other words, that you have to implement, and that's a lot of work.
Orta Therox: That's time. Yeah. Design systems are really fun at the same time, but they're also restrictive in the same way, right? The goal of a design system is to put constraints on what you do so that it's consistent everywhere. That constraint can breed creativity, but it's also the constraint means that that is your brand. You don't see Nike going around having different types of ticks, because there's only one tick. That's the design system, and trying to find ways to allow people to have creativity within that space, I think Nike is a good example. They allow for it to be hollow, so you can use it show some text on the inside, colors, things like that. But you still have the constraint.
Beyang Liu: I get what you're saying. There's a lot of work that goes into a design system, and it's very easy to just use the out-of-the-box thing, but why are they all the same? It feels like there's almost this conservatism creeping in. Are the designers on board with this? Or was it kind of like this corporate, "Oh, we just want to do the standard thing," and that's the kind of low-risk... it's not going to be outstanding, it's not going to be distinctive. People aren't going to talk about it, but at least it won't be terrible. So CYA. Let's just go with this.
Orta Therox: Yeah.
Beyang Liu: Is that a dynamic, or are all the designers like, "No, actually, this is fantastic. After all these years, we've finally convinced everyone in the world to converge on the perfect design."
Orta Therox: That's the one we are converging on. Absolute pinnacle of perfection.
I like to think about this in the same way that I thought about design for Mac development, back in the day. There used to be a human... well, there still is... human interface guidelines and a set of primitives that everybody uses. But you would still have people that would just reach for the stars, do unique designs that had all those really cool things built on top of these existing things, existing primitives. And they had two problems. On top of having a great design, they first of all had to implement them, and second, they had to maintain them as trends changed. And if you were bleeding edge, just like in fashion, a year later that is not going to look like it looks in your mind because something has changed.
In the Mac days, that was Apple has decided to use transparency here instead of using a shadow, and adopting... who knows? I was already tired of people adopting flat humans before Dropbox did, and after Dropbox, then everybody did.
Beyang Liu: Is that the predominant avatar artistic style now that you're referencing?
Orta Therox: I am. You'll know them. They're like representational people that usually don't-
Beyang Liu: A friend was like Alegria... is that name... I forget what the name was.
Orta Therox: That might be one of the artists, but I always just refer to them as flat people. I don't know if there's a better one.
Beyang Liu: Okay, flat people. Yeah, yeah, yeah.
Orta Therox: Yeah. It is kind of impressionistic, the art style, which is trying to reduce as much as possible the form of a human, which is an interesting problem.
Beyang Liu: And it was interesting when one person did it for the first time, but now it's everywhere. I guess that's-
Orta Therox: That's the problem, right? Do a good idea.
Beyang Liu: That's the paradox of success, I guess.
Orta Therox: It's like the game Freeze. It introduced this idea that somebody stole and created 1024. And 1024 is this massive game that everybody knows, that has a million clones of 1024, but that's just a clone of an original idea. And everybody looks at the original one as like, "Why did you copy this? You made it really restrictive, you took out all the-
Beyang Liu: Oh, man.
Orta Therox: ... all these extra accessibility things that were in the other one." Yeah, the success of somebody else with your idea can sometimes be a bit painful, but it's tricky. Yeah. And this is just fashion. That's why developers sometimes stay clear of this sort of stuff.
If you choose to use Tailwind, then yeah, you're adopting Tailwind and it's going to look very similar, like I did with Capture, but the trade-off there is that it does look similar and it feels like a tech-ish website and there's a minimum bar of quality, just by adopting it. It's going to work well on mobile, it's going to work well on an old browser. All I have to think about is what CSS classes go in a certain place. And if it's so well-adopted, then it's going to have so many tutorials and people describing the problem in different ways. That should make it very easy to learn, regardless of your style of learning.
Beyang Liu: Yeah.
Orta Therox: Yeah, it's a trend, and there will always be trends. This current one... eh, but almost every trend goes too far almost every single time. Skeuomorphism on the iPhone went too far, and then Apple took it too far with flat design. And now people are taking Tailwind too far in the web ecosystem, and maybe there will be an anti-Tailwind pushback from that, or maybe there will just be a new generation of something else. Whatever it is, it helps a lot of people get good-looking things done.
Beyang Liu: Yeah.
Orta Therox: That's the thing. You get a better experience because someone's using it, even if it does feel same same-y. It's tricky.
Beyang Liu: All right. We're coming up on end time here, but I wish there was more time, because there was a lot more to talk about, but as a parting thought, if there's one thing that you want a person watching this or listening to this to go and do now, what would that be?
Beyang Liu: All right. Well, Orta, thanks so much for joining us today. This was great, and I feel like we should have you back because there's more that we didn't get to that it would be good to talk about. But thanks for your time today and thanks for being a guest on this show.
Orta Therox: Same. Thanks for having me. It was such a pleasure.
This transcript has been lightly edited for clarity and readability.