Shahed Nasser

How we improved our documentation

Shahed Nasser shares how she and the technical writing team at Medusa went about improving their docs:

The most essential change that helped us implement all improvements is how we manage the documentation. In most software companies, documentation has less of a priority compared to the software, and it is handled as an afterthought.

At Medusa, we early on came to realize that documentation is what can actually drive further adoption of Medusa.

There’s a lot to learn from their process that you can apply to your own, but I think the biggest winner Shahed shares is the mindset change of thinking about documentation itself as a product, not as something that augments or attaches to the product.

Scott Antipa

How to store your app's entire state in the URL

Scott Antipa:

I’m working on a flowchart editor that runs in the browser, and I wanted a way for people to use it without having to sign in, or store any data on our server. I wanted to give them control over their data and to be able to store it locally to open and edit later. And also easily share it with other people. It’s easy to do this by supporting file upload/download, but I wanted something simpler, like the ability to share by sending a url. I also didn’t want to store anything on the backend (at least for the free tier).

What he decided on was to base64 encode the entire application state and store it in the fragment section of the URL. I love all the upsides of this approach and it’s pretty trivial to accomplish. Here’s the pseudocode that Scott provides in his post:

const stateString = JSON.stringify(appState); // appState is a json object
const compressed = compress(stateString);
const encoded = Base64.encode(compressed);
// Push that `encoded` string to the url
// ... Later, on page load or on undo/redo we read the url and
// do the following
const decoded = Base64.decode(encoded); // same encoded as above, but read from url
const uncompressed = uncompress(decoded);
const newState = JSON.parse(uncompressed);
// Now load your application with the newState

Postman Icon Postman – Sponsored

What does it mean to be API-first?

logged by @logbot permalink

APIs have evolved beyond the role of mere interface. In the past decade, APIs have become the building blocks of modern software and businesses. Whether at tech pioneers like Amazon and Netflix or century-old grocery chains and federal agencies, organizations are using APIs to offer new services externally and deliver efficiencies internally.

But, what does it mean for teams and orgs to adopt an API-first development model? This guide from Postman will answer this question and give you the tools and API platform to build on.


Names should be cute, not descriptive

A long-standing debate between me and a peer at work has been how we should name services. His position was always that services should be named something descriptive, so that you can infer from the name what it does. My position is that the name should definitely not be descriptive, but should be something cute and wholly disconnected from the purpose. And I think this applies more broadly to projects and companies, too.

Nicholas’ reason for cute names winning comes down to the inevitably of change in a service/project’s function and the difficulty in renaming things. I hadn’t thought of that argument, but I already agreed with the premise.

We also apply this thinking to podcast episode names, which can be a mixed bag because descriptive titles certainly help when it comes to discovery. As Adam and I discussed on our recent State of the “log” episode, if you see use a descriptive title, it’s most likely because we couldn’t think of a good cute/interesting one.

But that’s just our opinion about episode naming. What do you prefer?

Learn UI Design Icon Learn UI Design – Sponsored

Subscribe to the Design Hacks newsletter

logged by @logbot permalink

We’re big fans of Erik Kennedy and his work on Learn UI Design. By the way, have you subscribed to his Design Hacks newsletter? Our friend Shawn “swyx” Wang says it’s an “instant open, every time.”

Here’s a personal note from Erik about his newsletter. You can subscribe here.

Erik Kennedy here. I’m a big fan of the Changelog; had a legit blast talking about tactical design advice for developers on The Changelog a couple years back. As a developer-turned-designer, I’ve struggled with finding actually practical UI advice that could help me make my crappy-looking designs good. That’s why I made Design Hacks – an email newsletter of short, practical design tips. Hope you like it ✌️

Subscribe to the Design Hacks newsletter


Transform Gist into your personal key/value data store

Sometimes all a project needs is the ability to read/write small amounts of JSON data and have it saved in some persistent storage. Imagine a simple data-model which receives infrequent updates and could be represented as JSON object. It doesn’t demand a full-blown database, but it would be neat to have a way to interact with this data and have it persist across sessions.

This is where gist-database comes in handy, by leveraging the power of the gist api you can easily create a key/value data-store for your project.

This is a perfect solution for low write / high read scenarios when serving static site content with Next.js and using Incremental Static Regeneration to keep your cached content fresh.


Your tech stack is not the product

If you are the technical co-founder or early engineering lead at a startup, and you want to talk about your microservices, hand-rolled CI/CD, in-house monitoring stack, or any other unique part of your stack, I will say: Cool. Let’s riff. Take me deep, I’m ready.

But there’s something I’m likely to tell you in return, something I’ll probably insist you’re overlooking and need to internalize as soon as possible: Your technology stack is not the product.

It’s easy to get too focused on our tech and tools. Sometimes we think it’s our competitive advantage, other times it’s merely personal fascination and intellectual stimulation. This post is a good reminder:

A mindset of technology being the means, not the end, is uncomfortable. But it will help you stay focused on what matters most (the product and your customers), avoid wasteful misadventures, and maximize the company’s chance of success.


z-tokens – random tokens generation and related tools

I have (re)written my password generator in Rust with support for many different patterns. From completely random ASCII, to memorable diceware-like passphrases, and anything in between, plus extras such as private IP addresses or MACs.

I’ve also classified these patterns for easy accessing, and based on the pattern entropy I provide guesstimates about the effort for a brute force attack.

Tony Stubblebine Medium (via Scribe)

Medium embraces Mastodon

Medium CEO, Tony Stubblebine:

Today, Medium is launching a Mastodon instance at to help our authors, publications and readers find a home in the fediverse. Mastodon is an emerging force for good in social media and we are excited to join this community.

This strikes me as smart for Medium and a big vote of confidence for Mastodon and the entire concept of federated social networking. With Tumblr support (allegedly) coming as well, what’s next? Reddit?!


Datasette is my data hammer

Jeremia Kimelman:

Datasette is an open source tool that takes an SQLite database and gives you an out-of-the-box, web-based UI built specifically for exploring data. Need an example? Here’s a database of all of Motley Fool’s earning transcripts that I used to look for talk of their California campaign activity. And here’s a bunch of other examples of Datasette from the official site.

And the thing is: I love Datasette. It recently turned 5 years old and I wanted to write down the thing that makes it an absolutely delightful data hammer.

Tim McNamara

Agile isn't about speed, it's about direction

Tim McNamara makes an important distinction that is often lost on us:

Agile doesn’t make your team magically speed up its ability to close tickets. Instead, it speeds up the team’s decision-making process. It’s about orientation, not velocity. An agile workflow is one where you are able to quickly adjust direction based on short feedback cycles.

Mat, Natalie & I touched on this when they dragged me on to Go Time last summer to share some thoughts on velocity. Worth a (re)listen if you’re in to such things.


Ruby and Lambda had a baby and that child's name is Jets

Ruby on Jets allows you to create and deploy serverless services with ease, and to seamlessly glue AWS services together with the most beautiful dynamic language: Ruby. It includes everything you need to build an API and deploy it to AWS Lambda. Jets leverages the power of Ruby to make serverless joyful for everyone.

I’m not (yet) big on serverless things, but if I were, I’d love to run some Ruby code there.

Thomas Depierre

I am not a supplier

Thomas Depierre, writing about the concept of the Software Supply Chain in the context of open source development:

We are not suppliers. All the people writing and maintaining these projects, we are not suppliers. We do not have a business relationship with all these organisations. We are volunteers, writing code and putting it online under these Licences. And yes, we put it online for people to use them. But we do not get anything from it.

He goes on to discuss how, importantly, licenses such as the MIT point this out (in all caps):

If you use this, I owe you nothing. At all. We have no relationship. I put this up online on the condition that if you use it, all the risks are on you… So all your Software Supply Chain ideas? You are not buying from a supplier, you are a raccoon digging through dumpsters for free code. So I would advise you to put these rules in the same dumpster. And remember. I am not a supplier.

That raccoon line reminds me of a now-ancient meme you might still enjoy…


Time to rotate any secrets you have stored in CircleCI

The headline is the nut of this story, but here’s CircleCI CTO Rob Zuber with the announcement:

We wanted to make you aware that we are currently investigating a security incident, and that our investigation is ongoing. We will provide you updates about this incident, and our response, as they become available. At this point, we are confident that there are no unauthorized actors active in our systems; however, out of an abundance of caution, we want to ensure that all customers take certain preventative measures to protect your data as well.

  0:00 / 0:00