The Changelog: Software Development, Open Source - Tracking layoffs, tech worker demand still high, ntfy, devenv, Markdoc & Mike Bifulco (News)

Episode Date: November 14, 2022

Roger Lee has been tracking all tech layoffs since COVID-19, Amanda Hoover says tech worker demand is still high, ntfy helps you send push notifications for free, devenv lets you share development environments without containers, Markdoc scales from personal blogs to massive documentation sites & we talk with Mike Bifulco at All Things Open 2022.

I'm Jared and this is Changelog News for the week of Monday, November 14th, 2022. We are knee-deep in post-production of all of the excellent conversations we recorded at All Things Open. Expect one or two anthology episodes of our Friday interview show coming soon. We'll also be attaching one conversation to the end of our Monday news show for the next few weeks. Now, we are committed to keeping these news briefs brief, so the interviews will always be at the end, so you can skip them if you're not interested or simply don't have the time. Once we've emptied the queue, it's back to your regularly scheduled programming.

Speaking of the news, let's get into it. The top-clicked link in yesterday's edition of ChangeLog Weekly is a bit of a downer. It was the layoffs tracker at layoffs.fyi. Roger Lee has been tracking all tech layoffs since COVID-19. All the data is compiled from public reports and stored in Airtable, which provides embeddable table listings and charts. So far in 2022, 788 tech companies have laid off 120,699 people. That means 31 companies laid off almost 17,000 people in the past week alone. A huge portion of that, of course, is due to Meta

performing the largest layoff in absolute terms of 11,000 people. Just devastating. Our heart goes out to each and every one of you who lost your job this year, but we have high hopes that you'll get back on your feet quickly, which brings us to our next bit of news. Amanda Hoover writes for Wired, despite big layoffs, tech workers are still in demand. Quote, while many individual workers must now find new jobs, the broader outlook for tech workers remains strong. Their skills are still in demand, and their peers have responded to recent cuts with a wave of grassroots support to help laid-off workers find new jobs. Despite their command of the headlines,

big tech companies are just one niche in the broader tech industry. Many smaller firms and companies in adjacent industries are still hiring tech workers, albeit at slower rates than tech giants recently did and potentially for lower salaries. Some companies are now jumping at the chance to attract people previously monopolized by recruiters from the largest companies. End quote. It turns out big tech has scooped up so many of us over the past few years that many other industries have been left in the dust. From government to retail to ag, many companies are jumping at the opportunity to land talented workers like us that they previously just couldn't get done. It's super cool that we've also been banding together to help one another land safely with new employment. The article

mentions a LinkedIn group for workers let go by meta and a Google sheet with potential opportunities for laid off workers. We'll link to both of thoseet with potential opportunities for laid-off workers. We'll link to both of those in the show notes for you. Here's a cool new thing. Notify, spelled N-T-F-Y, is a simple HTTP-based PubSub notification service that lets you send notifications to your phone or desktop via scripts from any computer entirely without sign-up, cost, or setup. You publish messages via a put or post request to ntfy.sh with your topic as the URL path. Since there's no signup, the topic is essentially a password.

Then you subscribe to topics using your phone, a web UI, or in your own app by using the subscribe API. Apps are available for download for iOS and Android, and the entire system is completely free and open source forever. Here's Notify's creator, Philip C. Heckel, talking about that. Quote, I love free software, and I'm doing this because it's fun. I have no bad intentions, and I will never monetize or sell your information. This service will always stay free and open. You can read more in the FAQs and in the privacy policy. End quote. Never monetize or sell your information. This service will always stay free and open.

You can read more in the FAQs and in the privacy policy. End quote. Learn more at ntfy.sh. DevEnv is a tool that lets you build, share, and run your local development environments with a single command, without containers. How does it do that? With Nix. That's how. You define your development processes declaratively in a devenv.nix file

and start them with devenv up. There are 80,000 plus prebuilt packages for Linux, Mac OS, and x64, ARM64. And yes, Windows users, it works with WSL. We've been thinking about how we might revamp our contribution flows for changelog.com. I've been thinking about how we might revamp our contribution flows for changelog.com. I've always disliked our Docker-based flow because I don't want to run it myself, and DevMvvv might be just a tool we've been waiting for. Lastly, have you checked out

MarkDoc? It's Stripe's open-source, Markdown-based authoring framework that scales from personal blogs all the way up to massive documentation sites. I'll keep it brief because today's bonus interview from All Things Open is with Mike Befolko, who gave a talk about MarkDoc in the developer track and then talked to us even more about it in the hallway track. That is the news for now. Stick around and enjoy this bonus interview and stay tuned to the changelog because on Friday we are shipping our first anthology episode with special guests Arun Gupta from Intel, Chad Whitaker from Sentry, and Ricardo Suarez from AWS.

Have a great week. Share The Changelog with your friends and we'll talk to you again real soon. Well, we'd like to talk to you about MarkDoc. Yeah, for sure. Coming out of Stripe. This is something that came out in the summer, maybe, or the spring? Yeah, earlier this year.

I think around April. And made a big splash, of course. Documentation meets MarkDown. Right. These are a few of my favorite things. That's it. As long as somebody else writes the documentation. Yeah. And it's in Markdown But

We haven't been able to talk about it yet On the pod because we just haven't, I don't know Met you until today So did you do the work on the thing? Are you working on it now? Tell us the story of MarkDoc inside of Stripe And then we'll go from there Yeah, so full disclosure

I work at Stripe on the developer advocacy team. I did not create MarkDoc. It was created by a teammate, a colleague at Stripe called Brian Paul. His Twitter handle is segfault, S-E-G-P-H-A-U-L-T. Oh, the PH, yes. So MarkDoc came from, Stripe makes API infrastructure for the internet,

lots of products, tools, APIs for developers who are building things to connect money to a product. And Stripe makes many products that covers many languages, it covers many locales. So you might be looking at Spanish documentation for taking payments in Canada, for example. There's lots of different pivots through which we provide our documentation for many products. And in addition to that, all of Stripe's API libraries are available in seven languages. So I usually am pretty bad at getting them all in one shot, but it's Ruby and Go and Java, JavaScript,.NET, Python, and PHP. And so documentation is dynamic because of that. So you might pull up a docs page and want to see the PHP docs. You might want to see Ruby or Go or whatever

it may be. In addition to that, Stripes documentation has for a long time included dynamic content. So if you pull up Stripes docs, you'll see your test API key embedded in the code snippets in the docs. So you can copy straight from the docs, paste it into a terminal window or into an IDE window and execute it straight from there, and it executes against your account. We also do things like we'll provide in situ in the documentation. For example, if you wanted to get details, see the documentation about listing details

for a product that you have set up in Stripe, our documentation will actually show the keys for your products in your documentation. So, MarkDoc came from a need to want to do that in a way that scaled really well. Prior to MarkDoc, Stripe's docs were done with a Ruby on Rails app using ERB, which is the Rails templating language.

And the challenge there was that for a technical writer to write docs about something, they had to be familiar with ERB. They had to be good at debugging ERB, which was hard. The tooling for debugging those templates wasn't great. And they also had to be a good technical writer. And those things don't happen. That's kind of unicorn-ish. You don't get people like that too often.

So there was this ongoing project to sort of research better ways to do documentation that could solve all these problems all at once. And a bunch of different approaches were taken to do that. What we landed on was this project MarkDoc, created again by my colleague. And what MarkDoc is is essentially a superset extension to the Markdown language, which Markdown is familiar if you've used GitHub to create issues, or I think Reddit supports Markdown-ish authoring, and a variety of other things, Slack, all sorts of places use Markdown by now.

What Markdown does is it takes the Markdown syntax and adds a bunch of stuff to that to let you insert dynamic content without having to go write the code to do the dynamic part. So you can separate your developers, write the code for adding composable tags to your Markdown, and all your technical writers need to know is, hey, this tag is available for me.

I can add a call-out here, I can embed a podcast episode on my podcast site, whatever it may be. And it was designed with documentation in mind, but is applicable to anything. Anything that's content-forward that you write in Markdown. So I maintain my personal site. It's currently actually using MDX, which is an alternative,

another extension of Markdown, an alternative that came out of the React world. I want to say maybe Gatsby was where MDX was born. MarkDoc is sort of parallel to that with a very different approach. So the API for MarkDoc has sort of a three-phase rendering process that developers have access to every part of that rendering. So you can do things like add validation to your mark doc, where let's say, Adam, you were writing a docs page and you added a banner to your page and you set the type of the banner to be something that wasn't allowed. Like the type of your banner for whatever reason is Buick,

right? And we don't allow Buick on our banners. For some reason, we only have Ford cars or whatever the case may be. Just as an example, you can add validation to say we only allow certain brands here, certain words here, which is really nice because then suddenly you have some sort of inbuilt parsed testing on your documentation, which is hard to do otherwise. And with Markdown, it's just not possible too. Does that kind of make sense? That's sort of where the project came from. So outside of Stripe, who would be MarkDoc's ideal user? Yeah. So really, it's a framework approach that is sort of unopinionated in what the best uses for it are. Documentation is definitely an easy knockdown. Anyone who's building docs for a product that needs to have some sort of dynamic injected stuff in it is really great. I've gone to 1Password, and I've seen my code in the docs. It's my stuff. So whenever I'm

configuring the SSH client, it's like it's not, here's the example. Now go find out this other, go find your own code. It's more like, it's right there because I'm logged in and it's documentation for me. Right. Yeah. So personalized documentation is a great use case for it. There are people who use it for blogging sites, things like that.

If you have generally the sort of heuristic I use for like when it's time to think about more than just Markdown is when you're starting to think about adding something to the page that is either repetitive or needs to be dynamic in some way that Markdown can't do. So a good example is, let's say you're writing, you have a personal blog, you have lots of articles that are sort of long form. And in the middle of your articles, you want to add a call to action that's, go subscribe to my newsletter, or make sure you check out this other article.

And it's dynamic in some way. Right. You could create a mark doc tag that you could just embed somewhere in your article to say, this is a good place for that sort of call to action. And it can go and do the magic of that call to action without you having to go find the article to link to, or whatever the case may be in that place. What kind of tooling does it fit into? Yeah.

Really good question. Generating does it fit into? Yeah, really good question. Generating static HTML or something? Yeah, so if you pull up the Docs site, the walkthroughs are pretty straightforward. There's a couple of walkthroughs, one for going from MarkDoc to HTML, one that goes from MarkDoc to React, and then one that's sort of an integration plan for Next.js. All of those are essentially React flavored. I mentioned before there's sort of this three step rendering phase for MarkDoc. The last step is where you pick what it renders to.

And right now React is sort of the defacto renderer for MarkDoc. So anywhere where you're building something that can use React, it does the standard React DOM render thing where it grabs a div on the page, it uses React's render functions to take the syntax, your MarkDoc syntax,

and turn it into content on the page. But because it's open source, you could write a renderer that works with something else, right? You could render to React Native or someone in the talk I just gave asked about, what about Haskell? Like, sure, if you really want to.

What about Haskell? There's always that one person that's going to say, you know, hey, what about Haskell? What about Elixir? Yeah, that's right. That's me. Yeah, yeah. If you wantedkell? There's always that one person that's going to say, you know, hey, what about Haskell? What about Elixir? Yeah, that's right. That's me. Yeah, yeah.

If you wanted to, there's, I mean, it's open source for a reason. It's meant to be extensible. Okay, so that's cool. Will it write your documentation for you? Unfortunately not, yeah. Dang. Uninterested. I'm not interested.

Although I did just walk out of a talk about GitHub Copilot, which sounds like they might try at least. Yeah, they're writing more and more of our stuff for us, aren't they? Hard to say how good that would be, but it'll try. Oh, you haven't seen my documentation. It's a low bar. It's a low bar. Docs are hard.

Docs are tricky. In all ways. I mean, it's hard to write, hard to get right. Hard to keep up to date. Things change. The docs don't always reflect. And this, of course, isn't a silver bullet, but it's a helpful separation of concerns

where your technical writers can just do the writing things and your people doing the dev work can make it flashier, make it more dynamic, make it fit in with your analytics or whatever tracking you need to do. What about the look and feel? Does it have that Stripe look and feel? Out of the box, no.

There's no theming incorporated in it. It just generates a valid HTML from Markdown. It's fully themable, so you can take it and apply Tailwind to it, or if you use something like Chakra or some of the other UI libraries, you can do all of that. You can also write your own custom CSS or add components to it as needed. Let's talk about inside

Stripe then. So this is created, it's open source for others to use, but you're using it. So how has the documentation changed for you all? How did this shift the way you both create, maintain, consume as a user, speak for your users, and also the organization? Right. So I'm not a technical writer,

but I work with some of our technical writers on various products. And in sort of the before scenario for this, building documentation for any given product at Stripe was using ERB, like I mentioned before. And so pick a product, pick a language, pick anything, and you're writing documentation for any given product at Stripe was using ERB like I mentioned before. And so, pick a product, pick a language, pick anything, and you're writing documentation for something, you would go and find one Ruby template, one particular page

that had a Ruby view in it, that had ERB interspersed into it, and it was like a lot of interpolated stuff. So it was some text, some calculations, some this and that, and each page was sort of different depending on who implemented it originally. And this goes back to Stripe's early days back in 2011, 2012.

And so there was a lot of history built into that that was really hard and very fragile. If you forgot a closing tag on something, the page might crash and return a 500 error when someone went to view it, which is not good, right? You really don't want that. In this way, we've separated the

I need to be a Ruby developer from the I need to be a technical writer thing. And now, so in the new world, technical writers really just need to have an understanding of Markdown, have an understanding of what tags are available, and be able to work with engineers to build out new tags for new dynamic stuff. And so they're generally just kind of writing content at this point, which feels a lot better as a technical writer.

They don't also have to have a brain for being able to debug a Ruby template, which is like something that I would have to spin up a ton of work to figure out how to do, too. This might be Stripe-specific, but how then did this documentation move? Did there become a new repository for it, or how do you now take it from this page, not embedded, to just markdown or markdoc that folks can edit and maintain?

How does it shift architecture? Right. That predates my history at Stripe, so I don't honestly have the answer to that. I suspect that it was a gradual change where it was one page at a time, one product at a time, but I honestly don't have the answer there. I should say, too, that MarkDoc, so the MarkDoc site is MarkDoc.dev.

That is open source and built with MarkDoc, so you can go see how a documentation site was built using MarkDoc in sort of a self-referential way. Did you already say how old this project is then? Did I miss that? It went open source in April of this year. So April 2022. But it's been at Stripe for a while though, right?

It seems like. It was in use at Stripe for a while. The decision to open source had happened earlier this year. So rollout's probably been many years then, right? Gradual, project by project. Yeah. So this is where I should say that I started at Stripe in March of this year. Okay. Yeah, probably. That sounds right Gradual, project by project. Yeah. So this is where I should say that I started at Stripe

in March of this year. Okay. Yeah, probably. That sounds right. Yeah, probably. Okay. It's plausible. Yeah.

The impact is net positive basically though. Yeah. Okay. Certainly. Not negative. That's bad. Right.

Let's not go there. And truly the benefit of this being an open source thing is that we welcome contribution. We want people to tell us what they're struggling with or ask us the hard questions about why doesn't it do this. And try and apply it to their problems too.

Very cool. MarkDoc.dev. Yes, MarkDoc.dev. GitHub.com slash MarkDoc. Awesome. And then Stripe.dev if you're doing any Stripe-flavored developer stuff. And you can chase me down on Twitter too at Irreverent Mike. Nice. Irreverent Mike? That's me.

Mike, thank you so much. Of course. Yeah, thanks for having me. I too at irreverent Mike. Nice. Irreverent Mike? That's me, yeah. Mike, thank you so much. Of course, yeah, thanks for having me. I appreciate it. MarkDoc.dev. Yeah. Get it while you can. Open source, yeah, yeah. All right.

Thanks, guys.