Docspo

Notes on documentation that inspires me.

docspo
A portmanteau of documentation + inspiration.

What is this?

A few years back I chanced upon studyspo tumblr, a place where the drudgery of note-taking is celebrated as an art form (or at least that’s my interpretation). Here, I hope to collect similar findings in the realm of documentation for programming languages and frameworks.

I’m not yet sure who the target audience is for this (aside from yours truly), or if this document will hold any meaning unto itself. But, for now, I quite literally need a place to keep my notes (by which I mean links and impressions, not content).

JavaScript

My status: I don’t know JavaScript, but we travel in some of the same circles. Like, we have enough mutual friends that I could easily get by with a combination of copy and paste and asking for help, but I’ve never tried to learn it head on. We interact mainly through R packages that wrap JavaScript APIs, which occasionally leads to my looking under the hood to tweak a few things directly.

Speaking JavaScript

Speaking JavaScript (Rauschmayer 2014) wasn’t the first thing I found when looking for some sort of crash-course intro to JS for someone (me) who already knows how to program but is looking to become a bit more JavaScript literate, but I wish it had been. Its author, Axel Rauschmayer, has several free, online JavaScript books, all of which he describes in one or two bullets that, along with their titles, give you a sense of who the targeted reader is.

Overview in commented code

I’m lifting this whole example that comprises An Overview of the Syntax from the first chapter because I think it’s masterful:

// Two slashes start single-line comments

var x;  // declaring a variable

x = 3 + y;  // assigning a value to the variable `x`

foo(x, y);  // calling function `foo` with parameters `x` and `y`
obj.bar(3);  // calling method `bar` of object `obj`

// A conditional statement
if (x === 0) {  // Is `x` equal to zero?
    x = 123;
}

// Defining function `baz` with parameters `a` and `b`
function baz(a, b) {
    return a + b;
}

Why am I so obsessed with it? It’s beyond parsimonious. In that code block alone, you’re introduced to what would elsewhere be several chapters worth of content.1 How to write a comment is always one of the first things I want to know when encountering new syntax, plus it lets you read the commented code that follows.

You also pick up several pieces of vocabulary, the meanings of which can be inferred from the context and that the author can continue to use without needing to explicitly define them: variable, value, function, object, parameter, method, etc. This is super valuable for getting started, especially since defining these terms can be onerous and abstract. I don’t need to know what exactly a method is or how it does what it does, but being able to know that obj.bar(3); means a method is being called on an object opens up quite a bit in terms of reading code. The chapter does go on to define each of these terms, but having that overview means that the definitions can reference other terms without worrying too much about order/sequence.

Setting the vibe

I admittedly didn’t read the whole preface, but there are pieces of it I think are really well done. “What You Need to Know About This Book” gives you the persona/target audience (programmers who know some other language), and what’s not covered. And then there’s this liberating first sentence to “Tips for Reading this Book”:

The most important tip for learning JavaScript is don’t get bogged down by the details.

I honestly think that’s one of the hardest things for programmers to do when writing: ignore the edge cases (AKA get bogged down by the details). It’s like we write in preemptive defense of someone coming in and pointing out the exceptions. Guess what? They’re not who you’re writing this for, Susan!

My take

I haven’t read the whole thing yet (which should be obvious, given my current relationship with JavaScript), and I’ll likely add more comments here as I go. That said, I got more out of reading that one chapter (the first) than I did out of reading more in-depth reference pages on similar topics—I’m glad they all exist, but Speaking JS is fresh (and very for me).

JS4DS

JavaScript for Data Science (JS4DS) (Gans, Hodges, and Wilson 2020) was written by Maya Gans, Toby Hodges, and Greg Wilson who all, presumably, contributed equally. But it’s worth noting Greg Wilson’s background in, and writing on evidence-based practices in teaching programming—see, e.g. Teaching Tech Together (Wilson 2020).

Who you are (personas)

Defining the audience through “prototypical users” (i.e. personas with names, experiences, goals, etc.) is a practice that Wilson uses across his works and is a decidedly effective method for gauging the book’s fit for a reader without feeling like a check-list of credentials.

I, for example, wouldn’t necessarily give a resounding Yes! to the bullets that follow the three learners in the “Who You Are” section of the introduction. But the personas make it clear that it’s a good fit for my level of experience and needs.

Setting up and tooling

In the intro (see Setting Up) and throughout the book as necessary, you’re given a somewhat detailed description of the tools you’ll need to set up, how they differ, and how you’ll be using them on your computer. It’s not so detailed as to bog the reader down, and it’s clearly delineated in such a way that you can easily skim the sections if you don’t need the information. However, this is the type of information that I’ve found lacking in other programming books.

Key points

Each chapter concludes with a section titled “Key Points” (see, e.g. Key Points for Basic Features), which is a bulleted list of the concepts covered. I like this for two reasons: it serves as a summary/reminder for someone who’s read the chapter, and it can serve as a sort of “test” of topics for someone deciding whether or not they actually need to read the chapter.

ReactJS

Getting Started

The structure is everything!

They may not have list agreement, but the options at the top of React’s “Getting Started” (React Contributors 2021), as seen in Figure 1, are pretty darn good: try React, learn React, staying informed, versioned documentation, something missing.

Screenshot of Getting Started page for React with list of options: try react, learn react, stating informed, and versioned documentation.

Maybe I’d kill off “something missing” (from that header menu, not get rid of it on the whole), but it’s concise and gives the primary things someone would be looking for in getting-started-style documentation.

In Learn React they expressly break things down again:

You also have the sidebar navigation showing you the other sections, some of which might be what someone was actually looking for when they went to the getting-started page (e.g. add React to a website, create a new React app). I also like the wording of “Main Concepts” (and how prominent it is in the menu)—most people aren’t trying to learn all the things, and it lets you know that this subset probably holds the key concepts you need to get going.

Sass

My status: I’ve been learning Sass over the past few months as I familiarize myself with Quarto, and Bootstrap theming2. While I’m by no means an expert, I have a decent sense of how it works at this point.

Sass blog

I think that, on the whole, the official Sass-language documentation (Caitlin et al. 2021) is quite good. The Sass blog has a structure I like in terms of clear categories/types of posts that are consistent, with obvious target audiences, and calls to action.

Posts titled “Request for Comment”, e.g. Request for Comments: New JS API (Weizenbaum 2021a), summarize the key aspects of feature proposals, linking to their full discussions on GitHub. It’s a nice way of both soliciting feedback for those who don’t necessarily want to go through what might be difficult-to-follow threads on GitHub, and creating something to refer back to if/when these proposals are implemented.

Posts announcing live implementations of release candidates, e.g. New JS API Release Candidate is Live (Weizenbaum 2021b), “give users a chance to kick the tires a bit before we set [a feature] in stone.” There are clear instructions about how to use the release candidate (including installation instructions, when necessary), and a concluding section on what to expect if/when deprecation time comes around.

A “Feature Watch” post, e.g. Feature Watch: CSS Imports and CSS Compatibility (Weizenbaum 2018), goes into details about a feature that has gone through the their process of: proposal, tests, and implementation. They’re fairly similar to our package-release posts on the tidyverse blog.

Posts announcing deprecation, e.g. LibSass is Deprecated (Weizenbaum 2020), start off with the key points (which makes sense). After that, the key sections are as follows:

  • Why deprecate?
  • What does “deprecated” mean?
  • How do I migrate?

Other sections are context dependent, but I particularly like that they take the time to reiterate the meaning of the lifecycle stage (i.e. deprecation).

My take

The Sass blog is sufficiently sparse (about four posts a year) that it seems followable for heavy language users. It also creates a succinct, structured trail for the developers to point to as users who haven’t followed as closely encounter these things in the future.

HTML

My status: I know HTML pretty well. These days, most of the HTML I “write” is Markdown-generated. But I’ve been writing things on the interwebs since before Markdown existed. So, y’know, I’m not totally oblivious.

My current HTML boilerplate by Manuel Matuzović

I probably wouldn’t bother to include a section on HTML here were it not for this blog post, My current HTML boilerplate (Matuzović 2021), which I came across today, and just really loved.

The structure is simple. It begins by showing Matuzović’s boilerplate in full.

View code
<!DOCTYPE html>
<html lang="en" class="no-js">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <title>Unique page title - My Site</title>

  <script type="module">
    document.documentElement.classList.remove('no-js');
    document.documentElement.classList.add('js');
  </script>

  <link rel="stylesheet" href="/assets/css/styles.css">
  <link rel="stylesheet" href="/assets/css/print.css" media="print">

  <meta name="description" content="Page description">
  <meta property="og:title" content="Unique page title - My Site">
  <meta property="og:description" content="Page description">
  <meta property="og:image" content="https://www.mywebsite.com/image.jpg">
  <meta property="og:image:alt" content="Image description">
  <meta property="og:locale" content="en_GB">
  <meta property="og:type" content="website">
  <meta name="twitter:card" content="summary_large_image">
  <meta property="og:url" content="https://www.mywebsite.com/page">
  <link rel="canonical" href="https://www.mywebsite.com/page">

  <link rel="icon" href="/favicon.ico">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
  <link rel="manifest" href="/my.webmanifest">
  <meta name="theme-color" content="#FF00FF">
</head>

<body>
  <!-- Content -->
  <script src="/assets/js/xy-polyfill.js" nomodule></script>
  <script src="/assets/js/script.js" type="module"></script>
</body>
</html>

This is followed by a line-by-line explanation of the code. The post doesn’t aim to teach you everything you need to know about HTML, or the components thereof (though there are plenty of resources linked to, if you were looking for that). The explanations are the why for each item—and they’re short!

It’s a great example of a type of “documentation” (though I suppose that’s not technically what this is) the aim of which is code literacy. It explains the type of content that you’re likely generating if you’re publishing anything online. Such content becomes invisible because it’s so common. Do you need to know all of this information? Probably not. But it’s delivered in such a digestible manner that I, for one, was happy to have learned these nuggets of knowledge.

CSS

My status: I know enough CSS to know what to look up, and use it sparingly enough that I’m fine with that. I don’t really keep up with the latest, though, so when I do want to do something beyond the very basics, I need a concise resource that assumes the appropraite amount of underlying knowledge.

MDN Web Docs

The MDN Web Docs (MDN Contributors 2022) could fall under any number of language and/or framework headers. Their most meta table of contents, Web technology for developers, is broken into “Documentation for Web developers,” and “Web technology references,” which covers a lot. I happen to be learning about CSS Grid, so I’ve been spending the most time in their CSS resources. However, the content isn’t as important as the structure.

Property reference pages

I’m using their reference page for grid-column-start (MDN Contributors 2021) as an example in Figure 2, but there’s nothing specific to this page that distinguishes it from the others. The page opens with an informal definition (the formal definition comes later), and interactive demo that showcases a variety of property values/legal syntax options where applicable.

Screenshot of https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start which has the header, grid-column-start, in the body with a definition and demo below it. In the sidebar there is a Table of Contents, and a subsequent list of Related Topics.

The table of contents and subsequent sections are consistent across reference pages in a manner similar to that for “man pages” in most languages. What I like about the MDN page structure is the integration of “Related Topics” (in the sidebar), and “See also” (which comes at the very end of the page).

The related-topics section of the sidebar is broken into “Learn” (broader, getting-started material), “Reference” (other reference pages like the one you’re on), and “Guides” (which are broader than reference pages, but more specific and detailed than the learn pages). All of these give the reader cues about content they may not have searched for, but could be helpful (especially since a reference page is, by nature, niche).

I imagine the extent of the see-also section varies across pages, with some having more content than others. The first bullet is consistent, though, showing related properties (i.e. related reference pages). In the case of grid-column-start, there’s also a link to an MDN guide, and, lastly, to an external video tutorial.

My take

All in all, the MDN Web Docs are great. I use them frequently I’m sure at least in part due to the fact that they’re sufficiently popular as to do very well in search results. There are a variety of types of resources targeting different personas and levels of experience, and they make it easy to traverse from one type of resource to another.

CSS vocabulary

There are several handy resources that amount to CSS glossaries (though they all go by different names). I found most of them by way of Chris Coyier’s post on CSS Tricks, CSS Ruleset Terminology (Coyier 2017), which includes a limited set of definitions, but has a visual guide I quite like (see Figure 3).

Visual depiction of CSS ruleset terminology from Chris Coyier's post by the same name on CSS Tricks.

Assorted

  • The documentation system (AKA The Grand Unified Theory of Documentation) by Divio, which breaks documentation into a system of four elements: tutorials, how-to guides, technical reference, and explanation.

References

Caitlin, Hampton, Natalie Weizenbaum, Chris Eppstein, and Jina Anne. 2021. Sass Documentation.” Sass-Lang.com. https://sass-lang.com/documentation.
Coyier, Chris. 2017. CSS Ruleset Terminology. CSS-Tricks.” May 3, 2017. https://css-tricks.com/css-ruleset-terminology.
Gans, Maya, Toby Hodges, and Greg Wilson. 2020. JavaScript for Data Science. Boca Raton, FL: CRC Press. https://js4ds.org.
Matuzović, Manuel. 2021. “My Current HTML Boilerplate.” Web Development Blog. https://www.matuzo.at/blog/html-boilerplate/.
MDN Contributors. 2021. “Grid-Column-Start - CSS: Cascading Style Sheets. MDN Web Docs.” August 12, 2021. https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start.
———. 2022. MDN Web Docs.” January 18, 2022. https://developer.mozilla.org.
Rauschmayer, Axel. 2014. Speaking JavaScript. Sebastopol, CA: O’Reilly Media. http://speakingjs.com.
React Contributors. 2021. React - a JavaScript Library for Building User Interfaces.” Reactjs.org. https://reactjs.org.
Weizenbaum, Natalie. 2018. “Feature Watch: CSS Imports and CSS Compatibility.” Sass Blog. https://sass-lang.com/blog/feature-watchcss-imports-and-css-compatibility.
———. 2020. LibSass Is Deprecated.” Sass Blog. https://sass-lang.com/blog/libsass-is-deprecated.
———. 2021a. “Request for Comments: New JS API.” Sass Blog. https://sass-lang.com/blog/request-for-comments-new-js-api.
———. 2021b. “New JS API Release Candidate Is Live.” Sass Blog. https://sass-lang.com/blog/new-js-api-release-candidate.
Wilson, Greg. 2020. Teaching Tech Together: How to Create and Deliver Lessons That Work and Build a Teaching Community Around Them. Boca Raton, FL: CRC Press. https://teachtogether.tech.

Footnotes

  1. That’s not a bad thing in those contexts, but this is something special.↩︎

  2. See Down the front-end rabbit hole for more on that journey.↩︎