#148

[Robin]: This week I’ve been slowly converting an old blog from Jekyll over to Eleventy, a nifty static site generator by Zach Leatherman. It’s pretty exciting going through old posts and learning how to do things the new way but I expected a weekend of cursing my computer and generally being confused by everything. However, when I got going I was thoroughly surprised by how little effort it took to set things up.

Much of that is due to the quality of the documentation for Eleventy which just happens to be perfect for me and was quite honestly a shock as whenever I’m looking through the docs of some API or whatever I often stumble over each and every sentence. The writing is difficult to parse and is written by someone who has immense familiarity with the subject that they’re writing about. To understand even a single sentence in most docs you have to be aware of dozens of technologies and processes, command line tools and principles. You have to be aware of this giant ecosystem of apps and best practices and all of it feels overwhelming.

And so when I see good docs I want to point to them and hop up and down and yell “THIS, LET’S ALL WRITE LIKE THIS.” Because dang the Eleventy docs are wonderful and should be a reminder that we can all do better on this front.

But the reason why I bring this issue up is that documentation often feels exclusionary and it cuts certain types of people out of the conversation. If you don’t know what node is then may the front-end development lords have mercy on your soul if you’d like to understand modern CSS workflows. And as I struggle to understand the first paragraph in docs like this I feel as if I’m not worthy to use this technology, tool, or API. And I’m sure I’m not the only one – but we need to be constantly reminded that documentation is the foundation of our technology and web development communities.

Because without good documentation software is a nightmare.

From the Blog

Chris worked alongside Kylie Timpani and Geri Coady to make this wonderful site all about Serverless which shows how to get started, which services and resources exist out there, and what the heck that word even means:

Let’s get one thing out of the way: it still involves servers, so that word serverless might feel a bit disingenuous. It’s actually a new way to pay for and work with servers that, in many cases, is cheaper and easier than buying and managing your own servers.

Here’s one way to think about it: you can take your front-end skills and do things that typically only a back-end can do. You can write a JavaScript function that you run and receive a response from by hitting a URL. That’s sometimes also called Cloud Functions or Functions as a Service (FaaS), which are perhaps better names, but just a part of the whole serverless thing.

One of my favorite parts of this new site – that I can definitely see expanding over time – is the ideas section which suggests all sorts of things you could build serverless. Also, Chris happened to blog about the process of building and designing the site which is super interesting too.


Speaking of documentation, Ollie Williams writes in all about front-end documentation and the rise of MDX. This is especially useful if you happen to be building a styleguide as this post goes through what .mdx is and how Docusaurus works, as well as diving into how other folks built documentation for their components across different companies and orgs:

The benefits of pattern libraries have been extolled at nauseating length in a million Medium articles. When done well, they aid visual consistency and facilitate the creation of cohesive products. Of course, none of these tools can magic up a design system. That takes careful thought about both design and CSS. But when it comes time to communicate that system to the rest of an organization, Docz, Storybook and Styleguidist are all great options.


What does it mean to be "Full Stack"?

It’s a little tricky, because the meaning of that term has shifted over time. A “stack” used to largely mean a collection of back-end technologies, and these days, it can just as easily mean a collection of front-end technologies. This article explores that from a personal angle.


More great articles from the blog this week:


SPONSOR

WooCommerce

WooCommerce is easily the most popular way to sell anything from a WordPress site, which makes it one of the most popular ways to sell things on the web period. Need to sell T-Shirts? No problem. Track the inventory? Manage shipping? Send customized receipts? WooCommerce has got you.

But did you know WooCommerce can handle all your virtual products as well? Maybe you’re selling event tickets or an eBook, WooCommerce can do all that. Hot off the presses, WooCommerce has just acquired Prospress, meaning that WooCommerce is very serious about making sure it handles subscriptions in an awesome first-class way as well.