A newly revived philosophy for publishing personal knowledge on the web

A Brief History & Ethos of the Digital Garden

A case study showing how I make illustrations for abstract programming concepts

How to Draw Invisible Programming Concepts: Part I


<IntroParagraph>

With the recent rise of <a href="https://roamresearch.com/">Roam Research</a>, the idea of bi-directional linking is having a bit of a moment.

</IntroParagraph>

We're all very used to the _mono-directional_ link the World Wide Web is built around. They act as one-way pointers we follow in a linear sequence.

While we can link to any site, the destination page hasn't a clue we've done so.

We set up all these single direction paths, trying to signal relevance and context, only to have the other side completely ignore our efforts.

Our monolinks are trying to establish relationships in vain.

<BasicImage
  width="950px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1589455927/maggieappleton.com/notes/Hyperlinks.png"
/>

We're starting to look around our mono-linked environment, and wonder why it's so hard to surface relevant, contextual relationships.

Manually interlinking content takes an awful lot of human curation and effort. Effort we should probably slog off onto our systems.

> ✶ Enter the bi-directional link ✶

A _bi-directional_ link has **social awareness** - it knows about other pages or 'nodes' that point to it, and can make them visible to people. This means we get a two-way conversation flowing between our web locations.

<BasicImage
  width="950px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1589455927/maggieappleton.com/notes/Hyperlinks_2.png"
/>

---

## Bi-directional links are not new

The idea of the bi-directional link goes all the way back to 1945, when [Vannevar Bush](https://en.wikipedia.org/wiki/Vannevar_Bush) dreamed up the <a href="https://en.wikipedia.org/wiki/Memex">Memex</a> machine.

Vannevar outlined this hypothetical gadget in an essay in _The Atlantic_ called <a href="https://www.theatlantic.com/magazine/archive/1945/07/as-we-may-think/303881/">As We May Think</a>. He wanted a system capable of "associative indexing... whereby any item may be caused at will to select immediately and automatically another... [so that] numerous items have been thus joined together to form a trail."

This essay turned out to be a foundational document for the ideologies that directly led to both the internet and the Web. <Footnote idName={1}>Yes, those are two entirely seperate pieces of technology.</Footnote> Vannevar was one of the key movers and shakers rallying folks to help build the original internet infrastructure. He coralled folks at MIT, the US Department of Defence, the National Science Foundation and various research labs like the Standford Lincoln Lab, Bell Labs, the RAND corporation, and Xerox PARC to get involved. <Footnote idName={2}>Walter Isaacson, <a href="https://www.librarything.com/work/15179823">The Innovators</a>: How a Group of Hackers, Geniuses, and Geeks Created the Digital Revolution (London: Simon & Schuster, 2015).</Footnote>

Suffice to say, the guy was driven by a belief that enabling people to connect information and share knowledge would expand the scope of human understanding. The Memex was one idea of how that might manifest in material form.

<br />

<BasicImage
  showalt
  alt="Vannevar even created a small informative diagram of this desk-bound vision. Marketing chops 101."
  width="800px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1589545798/maggieappleton.com/notes/memex.jpg"
/>

Vannevar's evocative description of the Memex is especially impressive given that digital computers had only come into existence 5 years earlier. Most were still the domain of large military operations like Bletchley Park, and seen as inconveniently large calculators.

Implementing a wildly interactive computational personal knowledge base wasn't much of an option.

So the idea went into hiberation, and didn't resurface until the idea of personal computing began blooming in the sixties and seventies. <a href="https://en.wikipedia.org/wiki/Ted_Nelson">Ted Nelson</a>, an unlikely film director and sociologist, stumbled into a series of computing lectures and began to imagine how graphical interfaces might reinvent the way we write and connect ideas. He took inspiration directly from Vannevar's essay, and in 1965 when he coined the term _hypertext_ to describe his vision for a sprawling network of interlinking information.

Nelson planned to implement these hypertextual dreams in his perpetually-imminent Project Xanadu. <Footnote idName={3}>If you have some time, this is quite the internet history <a href="https://en.wikipedia.org/wiki/Project_Xanadu">rabbit hole</a> to run down. <br /> Ted Nelson is on <a href="https://www.youtube.com/watch?v=F0NgV3yNd2o">another level</a>.</Footnote>

The Xanadu project was a hypertext system that imagined that every sentence, block, and page would be part of a vast bi-directionally linked network.

<br />

<ImageFrame
  showalt
  alt="A design mockup of how Project Xanadu might visually connect pieces of text across multiple documents"
  width="1050px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1000/v1589545780/maggieappleton.com/notes/xanadu.png"
/>

<Center>

<img
  width="100px"
  alt="fleshed emoji face"
  src="https://emojipedia-us.s3.dualstack.us-west-1.amazonaws.com/thumbs/120/apple/237/flushed-face_1f633.png"
/>

</Center>

You'd be able to trace information back to its origin the way current web links do. But you'd also be able to see who had referenced, remixed, and expanded off that original. The full [[Pattern Language of Project Xanadu]] expands far beyond just bi-directional links to include features like [[Transclusions]], but we won't dive into it all here.

Suffice to say, Xanadu didn't pan out.

Instead we got the less fancy, but far more real and useable World Wide Web that currently does not support bi-directionals on an infrastructre level.

While Sir Tim Berner's Lee <a href="https://www.w3.org/DesignIssues/Topology.html">wrote himself a note</a> debating their pros and cons back in 1999, there is an obvious design issue with letting two-way connections flow freely around the web.

If _every_ site that linked to yours was visible on your page, and you had no control over who could and couldn't link to you, it is not hard to imagine the Trollish implications...

Figuring out how we might filter, moderate, and set permissions around link visibility turned into <a href="https://dl.acm.org/doi/epdf/10.1145/74224.74236">quite the challenge</a>. The <a href="https://dl.acm.org/doi/epdf/10.1145/74224.74229">design details</a> <a href="https://dl.acm.org/doi/epdf/10.1145/74224.74245">grew complex</a>.

It became clear implementing the Web with simpler mono-directional links was the right thing to do, given that its creators wanted universal adoption. Lots of people are still mad about it. Let's not venture too far down that historical wormhole.

> **The TLDR is technology is hard**.

Until <a href="https://www.wired.com/1995/06/xanadu/">Xanadu ships</a> and we're all immersed in the universe of multi-linked, version-controlled nodes of remixable micro-content (that somehow solves the problems of permissions and moderation), there are still plenty of ways we can resurrect the possibility of bi-directional links on the web.

---

## Bi-direction Linking in Personal Digital Gardens

Most of the design issues with adding bi-directional links to the global web were related to moderation and permissions. However, adding them within the bounds of a single website with one author sidesteps that problem.

There's been a flurry of interest around bi-directionals among people involved in the [[Digital Gardening]] movement.

Much of this was originally sparked by <a href="https://notes.andymatuschak.org/">Andy Matuschak's notes</a>. Go have a good browse through them.

<ImageFrame
  showalt
  alt="Andy's linked notes stack on top of one another, allowing you to browse to new notes while previous notes are still visible"
  width="1050px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1589545795/maggieappleton.com/notes/andy-note-links.png"
/>

<Spacer size="small" />

<p>
  There's plenty to admire here.
  <Footnote idName={4}>
    It should be noted Andy is an experienced developer and interaction
    designer, and these notes should not be taken as the standard expectation
    for the rest of us normal plebby internet citizens.
  </Footnote> But the key part of this system that creates interlinked context is
  the <b>"Links to this Note"</b> section at the bottom of each post.{" "}
</p>

Anytime Andy links to another one of their notes on the site, it'll pop up as a related note at the bottom of the page. This is the bi-directional dream.

<BasicImage
  width="1050px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1589483829/maggieappleton.com/notes/Hyperlinks_3.png"
/>

It gives us a way to navigate through these ideas in exploratory mode, rather than navigating a hierarchy of categories on a main index page.

Since it's all contained within a single-author site, our Spammish-Troll-risk factor is at a comfortable zero. <Footnote idName={5}>This is mildly tangential, but I love how the topic of bi-directional links
makes fully visible our "websites are locations" and "websites are
containers" conceptual metaphors with <b>"inside"</b> and <b>"outside"</b>
links.</Footnote>

---

### Building Your Own Bi-Directionals

That's all very cool, but how are you supposed to build bi-directionals into your own site? Thankfully, setting up your own public gardening bi-directional Memex doesn't involve Xanadu.

One fantastic option for non-developers is based around a personal wiki system called <a href="https://tiddlywiki.com/">TiddlyWiki</a>. Anne-Laure Le Cunff wrote up an easy-to-follow guide to getting <a href="https://nesslabs.com/tiddlywiki-beginner-tutorial"> your own up and running</a>.

For those of us here for the hyper-customised, over-engineered JavaScript solution (that would be me 🙌), the <a href="https://www.gatsbyjs.org/">Gatsby.js</a> community has a number of active gardening enthusiasts building themes and plugins.

I built mine using Aengus McMillin's <a href="https://github.com/aengusmcmillin/gatsby-theme-brain">gatsby-theme-brain</a>. Aengus has documented the theme well and it's not too challenging to implement (as long as you're comfortable in JavaScript and React).

I also curate a list of tools for [[Digital Gardening]] on this [Github repo](https://github.com/MaggieAppleton/digital-gardeners/)

---

### Bi-Directional Linking with WebMentions

While I argued that Web-wide bi-directional links are unlikely to happen at a global scale, there's a way you can add bi-directionals to your personal website that picks up on references anywhere on the web.

[WebMentions](https://webmention.io/) are an piece of web infrastructre the [IndieWeb](https://indieweb.org/) community has done a lot of work to advocate for. The W3C gave the [specification](https://www.w3.org/TR/webmention/) _recommendation_ status in 2017.

The system notifies a URL whenever that site is mentioned elsewhere on the web. You're then able to show that mention and its contents on your site. It's essentially an opt-in bi-directional linking system.

Plenty of folks have written useful guides on how to add these to your site. Here's one for any [static site](https://keithjgrant.com/posts/2019/02/adding-webmention-support-to-a-static-site/), one for [Gatsby](https://www.christopherbiscardi.com/post/building-gatsby-plugin-webmentions), one for [Next.js](https://css-tricks.com/jumping-into-webmentions-with-nextjs-or-not/). In fact there's a whole list of implementation examples on the [IndieWeb Wiki](https://indieweb.org/Webmention#IndieWeb_Examples) you can look through.


Seventy years ago we dreamed up links that would allow us to create two-way, contextual conversations. Why don't we use them on the web?

A Short History of Bi-Directional Links


<IntroParagraph>

In 1965 [Ted Nelson](https://en.wikipedia.org/wiki/Ted_Nelson) imagined a system of interactive, extendable text where words would be freed from the constraints of paper documents. This _hypertext_ would make documents linkable.

</IntroParagraph>

Twenty years later, Tim Berners Lee took inspiration from Nelson's vision, as well as other narratives like Vannevar Bush's [Memex](https://en.wikipedia.org/wiki/Memex), to create the World Wide Web. Hypertext came to life.

But hypertext was only one small concept amidst a sea of ideas Nelson spent his life developing. Most were entwined in his grand vision of [[Project Xanadu]], a piece of software that at first glance looks similar to The Web we're currently on – a way to access and connect shared human knowledge. But Xanadu was more complex and nuanced. It centered around the principle of <b>"Parallel Documents, Visibly Linked"</b> – the proposed interface presented documents side-by-side, and included features like version control and [[Bi-Directional Links]].

<BasicImage
  width="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1000/v1640076312/maggieappleton.com/notes/xanadu/transclusion_6_shrink_sl0vcb_mtepgz.jpg"
  alt="Three pages of documents presented side-by-side, with colorful visible links between them"
/>

<img src="g" alt="" />

In the historical record, Xanadu is often framed as an alternative to The Web – "the web that could have been" – if it had ever shipped. Unfortunately its [complexity led to troubles](https://www.wired.com/1995/06/xanadu/), and Berners-Lee's version of hypertext won out.

Despite the fact we're not currently browsing the Xanadu web, Nelson is still full of provocative, insightful ideas that never quite came to life – some that speak to many of the issues currently plaguing the modern web and are worth revisiting.

Two of the most intruiging are **Transclusion** and **Transcopyright**, a pair of concepts that reimagine the way authorship, attribution, copyright, and content monetization might work online.

## Transclusion

Transclusion is including one part of a document into another, and maintaing a link between the two. **This is different to copying.** A copy isn't inherently linked to it's original, and can be changed in the duplicate version.

A transclusion is directly linked to the original, and contains the exact same contents. Someone viewing the transclusion can easily open and view the original document. By doing this, transclusions create a single source of truth for that element, and a [[Bi-Directional Link]] so you can navigate between the original source and its instances across the web.

Now, what happens if the original source changes?

The transclusion doesn't automatically change along with it. If transclusions were direct embeds of the original content, we'd end up with [link rot](https://en.wikipedia.org/wiki/Link_rot) on a whole new scale. Every document would be a sad compilation of 404's.

You've probably' seen this happen with images – `<img>` tags where the `src` element points to an original source URL are essentially embeds. If the original publisher deletes the photo, your image dissappears along with it.

Instead, a transclusion is more like a saved version of the original – a _cached_ snapshot of it at a moment in time. You can update that snapshot to a newer version if you want to, but it's not automatic. Even if the original author deletes it, your transcluded version stays visible.

It works the same way [Git](https://en.wikipedia.org/wiki/Git) does – it's a version control system that stores the state of a file at a particular point in time.

<img
  width="620px"
  alt="Two documents connected by a transclusion. Transclusions are the same content displayed in more than one location, visibly linked."
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_620/v1640076309/maggieappleton.com/notes/xanadu/transclusion_5_shrink_bcif1h_it9ar8.jpg"
/>

This idea is powerful in both the possibilities and horrors it could open up. It would allow us to always know where content came from, and see it in its original context. This is a capitvating promise in the age of post-truth informational relativism. We are constantly presented with isolated soundbites, quotes, and tweets that are divorced from the context they were created within.

It would create a more layered and nuanced form of hypertext – something we're exploring in the [[Digital Gardening]] movement. We could build accumulative, conversational exchanges with people on the level of the word, sentence, and paragraph, not the entire document. Authors could fix typos, write revisions, and push version updates that propogate across the web the same way we do with software.

On the flip side, we can also imagine transclusions that once held bible quotes linking back to pages that are now filled with fiery smut. This sort of bad behaviour is inevitable to some degree, but could be minimised through thoughtful design patterns that I'll touch on later. Cultivating strong social norms, making social reputation visible, and enabling community moderation are all potential tools for it.

## Transcopyright

Transcopyright is an extension of transclusion that begins to make this very interesting for attribution, copyright, and monetisation – we begin to see how this might evolve into a sustainable economic system.

If text is able to be endlessly embedded across the web in a way that leads back to a single source and a single publisher, you can theoretically pay that person for every instance of their content showing up on the web.

In this alternate web utopia, readers would pay small amounts for reading content on the web. These _micropayments_ need to be truly micro for this to work. We're talking fractions of a cent for an article, not the chunky level of $5-10 a month most Patreons and subscription services run at. The majority of that payment would then flow back to the original author.

<BasicImage
  width="1100px"
  alt="Two documents connected by a transclusion. Transclusions are the same content displayed in more than one location, visibly linked."
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1100/v1640076317/maggieappleton.com/notes/xanadu/transclusion_4_shrink_a1ybfm_j5cb5c.jpg"
/>

In this idealised utopia we obviously want to place value on sharing and curation as well as original creation, which means giving a small fraction of the payment to the re-publisher as well.

We should note monetisation of all this content is optional. Some websites would allow their content to be transcluded for free, while others might charge hefty fees for a few sentences. If all goes well, we'd expect the majority of content on the web to be either free or priced at reasonable micro-amounts.

There are a thousand open questions here about the logistics of how this would work. But I find it sad to conclude it's completely outside the realm of human imagination.

We now have the [Web Monetization API](https://webmonetization.org/) up and running, and inevitably the words "blockchain" and "cryptocurrency" might have to be involved here. I'm not brave enough to speculate beyond that.

---

## Designing Speculative Interfaces

What I am comfortable speculating about is how this might look and feel as a user experience. My immediate reaction to this conceptual pair was to try and grasp onto a more grounded version of it.

**What would this look like in a real interface?** What kind of visual representations and interactions would make this possible? How would I create a transclusion, or pay someone through transcopyright?

Let's play a design game and think this through.

Here's a snippet of text I lifted from a recent Wired article, [To Mend a Broken Internet, Create Online Parks](https://www.wired.com/story/to-mend-a-broken-internet-create-online-parks/) by Eli Parser:

<SimpleCard>

"There’s a problem of public imagination. Fixing our ability to connect and build healthy communities at scale is arguably an Apollo mission for this generation—a decisive challenge that will determine whether our society progresses or falls back into conspiracy-driven tribalism. We need to summon the creative will worthy of a problem of this urgency and consequence."

</SimpleCard>

I've copied and pasted the text from the article. You can click the link above to view it in context, but you're going to have to scan the entire page to find the section I copied this from – your browser isn't going to scroll you to the correct point or highlight the relevant text because it's not a very smart link 😕.

The original source also has no clue I've copied and pasted from it. Nothing on Wired's article shows how many people have linked to or quoted their article - it currently looks like this:

<ImageFrame
  src="https://p-ZmFjNlQ.b3.n0.cdn.getcloudapp.com/items/geuoQpb4/d63e913c-dc63-4643-933f-e98d9b0368f7.jpg?v=15fe4f207f02029a4dbbb83471f6add0"
  width="800px"
/>

Which means we have absolutely no visiblity into who else on the web is responding to and building off this piece of writing. If other people have also copied and pasted this snippet of text, adding on their thoughts and ideas, we'll never know. <Footnote idName={1}>I'm not saying any of those responses are necessarily good or worth reading. They might all be crap troll comments. But I at least want some visual indication they exist. </Footnote> Unless we really go digging through pages of Google search result for it. Which we're certainly not going to without good reason.

**Transclusion** would make this whole scenario quite different. Let's imagine this again...

---

As I'm reading this article on Wired, perhaps small indicators show up next to each paragraph showing the number of times each it's been cited somewhere else on the web.

Below is a simple Figma mockup to demonstrate the idea. Try hovering over the number 8 here and clicking:

<FullWidthBackground>

<iframe
  width="880"
  height="760"
  src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FoRs8JnNMxNI3AZQhZslzlL%2FTranscopyright%3Fnode-id%3D1%253A6%26viewport%3D805%252C1447%252C1.084823489189148%26scaling%3Dmin-zoom"
  allowfullscreen
></iframe>

</FullWidthBackground>

An overlay appears with links to those other transclusion instances. If we click on one of those links, we clearly want to see how this snippet of text fits into other contexts. Ideally, they would be {x links} that highlight the relevant text on the destination page and scroll you to the right position.

If we want to offer a more modular browsing experience, we could also have this link modal expand into the page itself.  
Try clicking on the first link in the transclusion list here:

<FullWidthBackground>

<iframe
  width="880"
  height="760"
  src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FoRs8JnNMxNI3AZQhZslzlL%2FTranscopyright%3Fnode-id%3D358%253A3%26viewport%3D319%252C700%252C0.5028579831123352%26scaling%3Dmin-zoom"
  allowfullscreen
></iframe>

</FullWidthBackground>

Showing the linked article inline allows us to stay within the current article, but also quickly check what discussions and narratives are happening around it – a feature that might help pop a few of our filter bubbles.

---

## Content Moderation and the Tradgedy of the Comments Section

Many people will react to this prototype with a justified sense of horror.

"If _anyone_ can link to _anything_ on the web and have it show up on the original, everything will devolve into anarchy!"

We can easily imagine transclusions going the way of the public comments section. The 14-year-olds of 4chan might mass-tranclude the introductory paragraph of a New York Times lead story, surrounded by the incendiary lyrics of South Park's '_Uncle Fucka_'. In fact that would definitely happen.

This system opens up all the gnarly philosophical questions around control, censorship, community moderation, and "_free speech_" that the web constantly makes tangible and visceral.

What we're after is a low-friction way for website owners to let other people link to their ideas and creations, offering a rich contextual reading experience for audiences, without letting bad actors monopolise the system.

**It goes without saying transclusions need to come with a permissions system.** Website owners might be able to include a single flag in their metadata that turns transclusions off. Something to the effect of:  
`<meta name="transclusions" content="disable" />`

A subtler approach would be to simply choose not to display transclusion links on their webpage. The equivalent of `transclusions { display: none; }` in a css file. In this scenario the transclusions would still exist, but wouldn't be as easy to access and read.

Simply reducing it to an on/off switch is a bit of a ham-fisted solution though. It leaves no room for nuance or spectrums of permissioning. Luckily, Ted Nelson baked this consideration into his original ideas.

Transcopyright is of course a **copyright** system, which means there's a variety of restrictions and rules about who can use a piece of content across different contexts. <Footnote idName={2}>As always, IANAL and actual lawyers should feel free to expand on this point and add informed nuance to the argument. I wish you could use transclusions to do so, but <a href="https://twitter.com/mappletons">Twitter</a> is sadly our best option at the moment.</Footnote>

<ComingSoon />


The lost permissioning and copyright system of the Web

Transclusion and Transcopyright Dreams


<IntroParagraph>
    
An eponymous law is a principle or rule named after a particular person. The programming community abundantly creates and embraces eponymous laws. Compared to other fields, the number of "unofficial" laws, principals, and rules of thumb considered cultural gospel is overwhelming.

</IntroParagraph>

Each law isn't simply a piece of unique knowledge or insight. They often have a backstory – the context of when and where it was created is signficant. Many of these laws were spawned at critical turning points in the history of computer programming. Some come from inside influential companies, or innovative collectives, or touchstone books. Each feels a small story woven into the mythology and cosmology of computational history.

They come with a social connection to their creators. Their legacy and social credibility adds weight and legitimacy to the principle itself.

<br />

<SimpleCard alignLeft>

**Atwood's law** - Any software that can be written in JavaScript will eventually be written in JavaScript.  
_Jeff Atwood_

</SimpleCard>

<SimpleCard alignLeft>

**Atwood's duck** - When compiling a presentation for corporate managers, programmers should include at least one throwaway "duck" detail that's begging to be to removed or changed. This allows the corporate office to feel like they're participating, despite the change being inconsequential.  
_Jeff Atwood_

##### More on [New Programming Jargon from Jeff's blog](https://blog.codinghorror.com/new-programming-jargon/)

</SimpleCard>

<SimpleCard alignLeft>

**Brandolini's law** - The amount of energy needed to refute bullshit is an order of magnitude bigger than to produce it.  
_Alberto Brandolini_

</SimpleCard>

<SimpleCard alignLeft>

**Conway's law** - The systems we design always reflect the organisational structure of the community that designed them. Our software and automated systems end up 'shaped like' the teams and companies that created them.
_Melvin Conway_

##### More on [Wikipedia](https://en.wikipedia.org/wiki/Conway%27s_law)

</SimpleCard>

<SimpleCard alignLeft>

**Engelbart's law** - Like Moore's law, but applied to human performance. Organisations and human potential increases at an exponential rate.  
_Douglas Englebart_

##### More on [The Doug Englebart Institute](https://www.dougengelbart.org/content/view/316/322/)

</SimpleCard>

<SimpleCard alignLeft>

**Gall's law** - A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.  
_John Gall_

##### More on [Wikipedia](https://en.wikipedia.org/wiki/John_Gall_%28author%29#Gall's_law)

</SimpleCard>

<SimpleCard alignLeft>

**Godwin's law** - As an online discussion grows longer, the probability of a comparison involving Nazis or Hitler approaches one.  
_Mike Godwin_

</SimpleCard>

<SimpleCard alignLeft>

**Wadler's law** - The emotional intensity and time spent debating a language feature
increases along this sequential scale:

1. Semantics (least intense)
2. Syntax
3. Lexical syntax
4. Comments (most intense)

_Philip Wadler_

##### More on [HaskellWiki](https://wiki.haskell.org/Wadler's_Law)

</SimpleCard>

Know about an eponymous law from programming that I'm missing here? [Tweet me](https://twitter.com/mappletons) about it.


A collection of laws named for specific people in the field of programming

The Eponymous Laws of Programming


A growing collection of all my favourite Neologisms.

These are freshly coined words or phrases inching their way into common usage, but not fully mainstream yet. Neologisms emerge when we are unable to express or conveniently refer to an emerging collective idea or experience.

They're **acts of creativity** as we fill the gap between our symbolic understanding of the world and our documented language.

<SimpleCard alignLeft>

#### Brahmin Left

"The “left” has become the party of the intellectual elite (Brahmin left), while the “right” can be viewed as the party of the business elite (Merchant right). In India’s traditional caste system, upper castes were divided into Brahmins (priests, intellectuals) and Kshatryas/Vaishyas (warriors, merchants, tradesmen). To some extent the modern political conflict seems to follow this division."

##### From <a href="http://piketty.pse.ens.fr/files/Piketty2018.pdf">Thomas Piketty </a>

</SimpleCard>

<SimpleCard alignLeft>

#### Cargo Cult Programming

Ritualistic inclusion of code into a programme without fully understanding why it needs to be included.

The term is a riff off the anthropological concept of **Cargo Cults** - a phenomenon in early 20th century Melanesian communities where people began to perform religious-like rituals hoping to summon modern technological goods.

They were often island communities who had previously been brought cargo-loads of foreign supplies by European colonisers.

In times of short-supply, communities would build symbolic totems like airplane runways, steamship docks, warehouses, and radio masts out of timer and straw. In the hopes of attracting the airplanes and ships that had once showed up with excesses of material wealth onboard.

</SimpleCard>

<SimpleCard alignLeft>

#### Digital Prepper

Riffing off **doomsday preppers**, people who have seen so many centralised services shut down, they default to Open Source Software to prevent losing their data and system setups.

<TweetEmbed tweetId="1221804267083718656" />

</SimpleCard>

<SimpleCard alignLeft>

#### Epistemic Peer

People who have demonstrated clear cognitive overlap with you. You trust their thinking enough that if they feel strongly about a topic you haven't researched, you're willing to defer to their judgement. If they disagree with you, you take it seriously. Even if you don't change your mind, you consider their viewpoint valid.

You earn epistemic peerhood by doing your research on topics you choose to write about, presenting compelling evidence, and making creative arguments that help reframe existing debates in more interesting ways.

</SimpleCard>

<SimpleCard alignLeft>

#### Failson

The proudly self-applied moniker of <a href="https://en.wikipedia.org/wiki/Chapo_Trap_House">Chapo Trap House</a> hosts and listeners - "downwardly mobile, disappointing male offspring of complacent baby boomers"

##### From n+1's <a href="https://nplusonemag.com/online-only/online-only/professional-managerial-chasm/">Professional-Managerial Chasm</a>

</SimpleCard>

<SimpleCard alignLeft>

#### Greenpilling

When someone reaches the tipping point of researching too much about the reality of our climate breakdown situation, and can now no longer function as a normal person in society.

The climate crisis version of Redpilling, Blackpilling, etc.

</SimpleCard>

<SimpleCard alignLeft>

#### Hospice Mode

The stage your when your phone / fitness tracker / laptop is in its final months and you're just prolonging its death through a series of coping techniques. Carrying around extra battery packs. Patiently giving it 10 minutes to restart. Resetting the system at regular intervals. Just give up.

</SimpleCard>

<SimpleCard alignLeft>

#### Glamour Toil

Displaying the social status marker of toiling so hard it's glamorous. You rise, grind, and hustle every day of the week. And only take breaks to watch <a href="https://www.youtube.com/watch?v=PIJElPStJpg">Gary Vaynerchuck</a>'s motivational clips while chugging <a href="https://www.bulletproof.com/recipes/bulletproof-diet-recipes/bulletproof-coffee-recipe/">bulletproof coffee</a>. A variety of Hustle Porn.

##### See also, <a href="https://www.sloww.co/total-work/">Total Work</a>

</SimpleCard>

<SimpleCard alignLeft>

#### Ironesty

“The braiding together of irony and sincerity (honesty) in a unified aesthetic expression.” - Greg Dember

##### From Anne-Laure Le Cunff's <a href="https://nesslabs.com/metamodernism">An introduction to metamodernism</a>

</SimpleCard>

<SimpleCard alignLeft>

#### Manel

Panel made up entirely of men. Usually honouring work done entirely by other men.

</SimpleCard>

<SimpleCard alignLeft>

#### Metarationality

Having epistemological awareness of _how_ you know what you know, _how much_ you know about it, and how much you should _defer to experts_ instead of your own judgement.

We should all aim for at least mediocre metarationality.

</SimpleCard>

<SimpleCard alignLeft>

#### Milquetoast

Vanilla, bland, flavourless Normie behaviour.

Someone might be Milquetoast if the primary features of their personality centre around liking avocados, watching Game of Thrones, and "travel"

</SimpleCard>

<SimpleCard alignLeft>

#### Neofeudalism

The new Feudalist system we all rely upon for online security. No single person or company can defend themselves against hackers, attackers and trolls without aligning themselves with one of the monolithic fortresses (Apple, Facebook, Google, or Microsoft). We hide behind their enormous cybersecurity teams. We're required to live within their walls and tolerate whatever surveillance suits their business model. It's feudalism, with likes.

##### From Cory Doctorow's <a href="https://locusmag.com/2021/01/cory-doctorow-neofeudalism-and-the-digital-manor/">Neofeudalism and the Digital Manor</a>

</SimpleCard>

<SimpleCard alignLeft>

#### Pinkering

Named for Steven Pinker - a common phenomenon among do-gooder elites who cite the long arc of human history in order to downplay and minimise any immediate suffering.

Another variety is _Economic Pinkering_ which justifies any economic concerns by simply citing how many Chinese people have been lifted into the middle class.

##### From Anand Giridharadas' <a href='https://en.wikipedia.org/wiki/Winners_Take_All:_The_Elite_Charade_of_Changing_the_World'>Winners Take All: The Elite Charade of Changing the World</a>

</SimpleCard>

<SimpleCard alignLeft>

#### Privacy Veganism

Unnecessarily shaming people who aren't willing to delete their Facebook account when it’s a functional necessity in their social context

</SimpleCard>

<SimpleCard alignLeft>

#### Subtweeting

It's about them. And we all know it's about them.
But you're not going to tag them or address them directly. The ultimate expression of digital passive aggression.

</SimpleCard>

<SimpleCard alignLeft>

#### Theoretical Graffitiability

The degree to which an academic theory can be captured in graffiti in public space. I coined this one after someone posted a photo of the <a href="https://sjef.nu/theory-of-change-and-the-futures-cone/">futures cone</a> in spray paint.

<TweetEmbed tweetId="1268881238934380546" />

</SimpleCard>

<SimpleCard alignLeft>

#### Vegan Tourist

Temporary visitors in the land of Veganism. The person who just watched Cowspiracy on Netflix last week and now is **all in**. Often gone within a month or two.

</SimpleCard>

<SimpleCard alignLeft>

#### Yak Shaving

Embarking on a sequence of nested tasks to accomplish a goal, where each step seems logical and necessary in the moment, but becomes less and less linked to the original goal.

You set out to fix a broken image in your code, which leads to refactoring the image rendering function, which requires updating your npm packages, but first you need to plan this all out in Jira, and then install the latest version of Adobe Flash, and on and on in seemingly logical sequence until you find yourself in a zoo... shaving a yak.

##### Originally coined by <a href="https://projects.csail.mit.edu/gsb/old-archive/gsb-archive/gsb2000-02-11">Carlin J. Vieri</a>

</SimpleCard>

<SimpleCard alignLeft>

#### Zemblanity

Unsurprisingly unlucky conditions

##### From <a href="https://www.ribbonfarm.com/2020/03/09/plot-economics/">Plot Economics</a> by Venkat Rao

</SimpleCard>

<SimpleCard alignLeft>

#### Zumping

Dumping someone over Zoom. An unfortunate necessity in the life and times of COVID-19.
Possibly due to a lack of Zex.

</SimpleCard>


A collection of interesting words that have recently been coined

Neologisms


<SimpleCard alignLeft>

### Can I hire you to design my project?

Sorry, no. I'm unavailable for any contract, side-project, or full-time roles for the forseeable future. I'll post on Twitter and update this status if the situation ever changes.

</SimpleCard>

<SimpleCard alignLeft>

### Do you consider yourself a designer or developer?

Both. I find the distinction between the two fields necessary on the macro scale of our whole industry, but fairly irrelevant on the micro scale of an individual making things in the world.

I starting learning HTML at 12 because I wanted to figure out how to layout a bunch of Neopets images in a table format. Development skills have always been a necessary tool in my design process. You can't divorce the creation from the medium.

</SimpleCard>

<SimpleCard alignLeft>

### What tools do you use to illustrate?

Primarily my brain and upper body limbs. With a little help from [Procreate](https://procreate.art/) on an iPad Pro. I do a little color and brightness editing in Photoshop as well, but it's a pretty minor step.

I'm betting want more information than that, so I wrote a whole post called [[What App is That?]] for you.

</SimpleCard>

<SimpleCard alignLeft>

### Do you have any resources or advice for someone who wants to get started with making illustrations?

Plenty.
Have a look at the [Resources](/resources) page for a collection of courses, learning platforms, and books I personally recommend.

You might also want to read my essay series on [[Drawing Invisible Programming Concepts]]

That said, I no longer work as an illustrator. I spent four years working professionally in illustration (2015-2019) before moving into an art direction and product design role. I'm not a great source of advice on 'making it' as an illustrator, since that's not something I want to do.

</SimpleCard>

<SimpleCard alignLeft>

### I want prints of your illustrations. Can I buy prints from you or print them myself?

You can indeed print any images you find here for your own personal use!

The image quality on the garden notes and twitter is low for printing (72dpi). But if you join my email list I send out high-quality, downloadable versions on there (300dpi – big enough to print on the side of a wall if you so desire).

I'm not fan of the carbon emissions involved in printing, storing, and shipping these from a central location. So if you want professional prints I suggest finding a local printer near you and sending them the high-res files.

</SimpleCard>

<SimpleCard alignLeft>

### How would you describe your work?

I think about this too much, but I would shelve everything I do under the banner of **visual explanations**. This conveniently vague term includes everything from **illustrated notes and essays** to **interface design**.

What I don't make:

- **Comics** - Comics tell a narrative story over time. I mostly explain non-narrative topics and explore ideas atemporarily out of time. They share a lot of comic-like qualities though, and I've spent countless hours studying & stealing techniques from comic artists like [Will Eisner](https://en.wikipedia.org/wiki/Will_Eisner), [Nick Sousanis](http://spinweaveandcut.com/), and [Scott McCloud](http://scottmccloud.com/).
- **Infographics** - Infographics have [a particular aesthetic](https://www.pinterest.com/visualistan/latest-infographics/) that makes my eyes bleed. While technically these do communicate information through graphics, the word _infographic_ comes with visual baggage. And I would like to run very, very far away from it.
- **Sketchnotes** - If we define 'sketchnotes' as true _sketches_ – unrefined, unplanned visual scribbles – my work doesn't fit.
  They're far more crafted and planned than stream-of-consciousness sketches drawn in one fell swoop.

</SimpleCard>

### Have a question I haven't answered?

[Feel free to ask me on twitter](https://twitter.com/mappletons)


Frequently Asked Questions


<IntroParagraph>

Now, and for the rest of my brief life, I'll be trying to write narrative non-fiction that isn't entirely crap. I'm not a _Writer_, but I write in order to explore others things – anthropology, weird cultural quirks in the web development community, interaction design, and the rising field of "tools for thought".

</IntroParagraph>

Perhaps you're the same kind of non-_Writer_ writer. The playful amateur kind, using it explore and communicate ideas, rather than making the medium part of your identity. But even amateurs want to be good. _I_ certainly want to get good.

Knowing what you like is half the battle in liking what you create. In that spirit, I collect narrative non-fiction essays that I think are exceptional. They're worth looking at closely – their opening moves, sentence structure, turns of phrase, and narrative arcs.

<p>
  The only sensible way to improve your own writing is by [[echoing]] the work
  of other writers. Good artists copy, great artists steal quotes from Picasso.
</p>

You may want to start your own collection of lovely essays like this. There will certainly be some Real Writers who find my list trite and full of basic, mainstream twaddle. It probably is. I've done plenty of self-acceptance work and I'm okay with it.

Twaddle aside, the essays below are worth your attention.

## The Essays

### [What is Code?](https://www.bloomberg.com/graphics/2015-paul-ford-what-is-code/)

<p class="small-caps">by Paul Ford</p>

Paul Ford explains code in 38,000 words and somehow make it all accessible, technically accurate, narratively compelling, and most of all, culturally insighful and humanistic.

I have unreasonable feelings for this essay. It is, to me, perfect. There are few essays that take the interactive medium of the web seriously, and this one takes the cake. <Footnote idName={1}>Most of the rest live on [The Pudding](https://pudding.cool), though they are focused on data visualisation rather than exploring longform, narrative writing in particular.</Footnote> There is a small blue cube character, logic diagrams, live code snippets to run, GIFs, tangential footnotes, and a certificate of completion at the end.

<ImageFrame
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1100/v1640188990/maggieappleton.com/notes/essays/ford-2_w4zoqb.jpg"
  alt="Screenshot of the essay what is code"
  style={{ marginBottom: 0 }}
/>

<ImageFrame
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1100/v1640188990/maggieappleton.com/notes/essays/ford-1_bxqtj8.jpg"
  alt="Screenshot of the essay what is code"
  style={{ marginTop: 0 }}
/>

### [A Supposedly Fun Thing I'll Never Do Again](https://harpers.org/wp-content/uploads/2008/09/HarpersMagazine-1996-01-0007859.pdf)

<p class="small-caps">
  by David Foster Wallace
  <br />
  Published under the title 'Shipping Out'
</p>

Forgive me for being a David Foster Wallace admirer. The guy clearly had issues, but this account of his 7-day trip on a luxury cruiseliner expresses an inner monologue that is clarifying, rare and often side-splittingly hilarious.

He taught me it is 100% okay to write an entire side-novel in your footnotes if you need to.

### [What’s the Point If We Can’t Have Fun?](https://thebaffler.com/salvos/whats-the-point-if-we-cant-have-fun)

<p class="small-caps">by David Graeber</p>

Graeber explores play and work from an anthropological perspective. He's a master of moving between the specific and the general. Between academic theory and personal storytelling. He's always ready with armfuls of evidence and citations, but doesn't drown you in them.

### [The Ketchup Conundrum](https://www.newyorker.com/magazine/2004/09/06/the-ketchup-conundrum)

<p class="small-caps">by Malcolm Gladwell</p>

This piece uses typical Gladwellian style. He takes a fairly dull question – **Why had ketchup stayed the same, while mustard comes in dozens of varieties?** – and presents the case in a way that makes it reasonably intruiging. He's great at starting with specific characters, times and places to draw you in. There are always rich scenes, details, personal profiles, and a grand narrative tying it all together.

Some people find the classic _New Yorker_ essay format overdone, but it relies on storytelling techniques that consistently work.

### [Quitting the Paint Factory](http://www.molvray.com/ebooks/Quitting_the_Paint_Factory_Mark_Slouka.html)

<p class="small-caps">by Mark Slouka</p>

### [Goodbye To All That](https://essaysspring13.qwriting.qc.cuny.edu/files/2013/04/Joan-Didion-Goodbye-to-All-That.pdf)

<p class="small-caps">by Joan Didion</p>


Narrative essays that I consider ideal models of the medium

The Finest Narrative Non-Fiction Essays

The written version of my talk about bringing visual explanations and embodied knowledge to programming tools

A Picture Worth a Thousand Programmes


<IntroParagraph>

I have been seeing an increasing amount of baby pink on developer Twitter.

In lieu of the hooded figures in dark rooms, boxy hardware, and streams of neon green characters that we traditionally associate with code nerds and computer geeks, there's been a sudden influx of pastel shades and baby animals.

</IntroParagraph>

It's an aesthetic that feels like walking into a Sailor Moon episode. Bright, sparkling rainbows and unicorns waft by a soft pink backdrop. Everything looks like a puffy, dusted marshmallow.

<br />

<TwoColumn maxWidth="1000px" alignItems="top">

<BasicImage
  showalt
  alt="Git It Gurl designs created by Amy Wibowo"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1615658712/maggieappleton.com/notes/femme-dev/git_it_gurl_1024x1024_2x_zy6vyi.jpg"
/>

<BasicImage
  showalt
  alt="Programming zines created by Amy Wibowo"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1615658722/maggieappleton.com/notes/femme-dev/c2_1024x1024_2x_mpb5l5.jpg"
/>

</TwoColumn>

For lack of a better term, I'm calling this style "_femme dev_."
To be clear, by _femme_ I don't mean "for women." I mean it in the sense of celebrating a traditionally feminine aesthetic.

Sex (man / woman) is [not the same](https://en.wikipedia.org/wiki/Sex_and_gender_distinction) thing as gender (male / female). If you're not familiar with gender theory, [Judith Butler](https://en.wikipedia.org/wiki/Gender_Trouble) is a good introduction.

_Feminine_ and _masculine_ are socially constructed roles, behaviours, activities, and attributes. The way we walk, talk, sit, dress, and decorate our laptops all have the potential to be '_read_' as either masculine or feminine by those around us. Or somewhere in between. It's all a big fuzzy spectrum.

Our ideas about what reads as feminine or masculine is fluid and culturally relative. These roles are constantly shifting and changing under our feet. We have only associated the color pink with femininity for the last 100 years <Footnote idName={1}>Good read by The Atlantic on this - [Pink Wasn't Always Girly](https://www.theatlantic.com/sexes/archive/2013/08/pink-wasnt-always-girly/278535/)<br/>"In the 18th century, it was perfectly masculine for a man to wear a pink silk suit with floral embroidery"</Footnote>, and it's reasonable to expect that in 100 years time we'll once again attach arbitrary color associations to arbitrary gender roles.

But given our current historical moment, it's fair to say the aesthetic on display here draw on an established history of traditionally feminine visual styles. By no stretch of the imagination does that mean it is designed just for women, or off limits to men.

It simply means it's made for anyone who enjoys the aesthetics of soft, puffy Kirby plushies and sparkle text.

---

[Amy Wibowo](https://twitter.com/sailorhg) (@sailorhg on Twitter) is one of the folks at the centre of this fuzzy, adorable shift. Their online store [bubblesort.io](https://shop.bubblesort.io/) sells zines, keyboard designs, and sweatshirts bring an intentionally femimine vibe to an industry overwhelmingly staffed by self-identifying males. <Footnote idName={2}>An unsurprising 91.1% male according to 2020's State of JS [survey](https://2020.stateofjs.com/en-US/demographics/gender) </Footnote>

Since keyboards are one of the only pieces of 'kit' developers use in their jobs (other than 32" tall vertical displays), custom keycaps designs have become a central feature of this movement.

The [Astrolokeys](https://astrolokeys.com/) set designed by Wibowo and [Cassidy Williams](https://twitter.com/cassidoo) is a particularly beautiful example. It's pink, purple, and yellow keys feature astrological symbols for each of the 12 zodiac signs.

<BasicImage
  alt="A split, astrology-themed keyboard made up on yellow, pink, and purple custom keys"
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1615658717/maggieappleton.com/notes/femme-dev/EfqE7d1UYAAd1Nk_qbahzg.jpg"
/>

<TwoColumn maxWidth="1000px" alignItems="top">

<TweetEmbed tweetId="1295494004943933441" />
<TweetEmbed tweetId="1368997186055249922" />

</TwoColumn>

---

The aesthetic has also started showing up in the branding choices of dev-focused tools and companies.

[Charm](https://charm.sh/) is a set of command line tools designed to make the terminal feel "glamorous" – featuring bubble tea, lipgloss, and rainbows.

<ImageFrame
  alt="The charm website featuring pink glow and bubble text"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638703762/maggieappleton.com/notes/femme-dev/charm1_fmuwnw.jpg"
/>
<ImageFrame
  alt="A set of cute 3D characters representing Charm's plug-in ecosystem"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638703762/maggieappleton.com/notes/femme-dev/charm2_ihnlyd.jpg"
/>

<TwoColumn maxWidth="1000px" alignItems="top">

<TweetEmbed tweetId="1371211189703835650" />
<TweetEmbed tweetId="905270297128865792" />

</TwoColumn>

[Compute Cuter](https://computecuter.com/) is Amy's full minisite dedicated to making your computing environment a bt softer. They have fonts, themes, and keycap sets that fit the vibe.

<ImageFrame
  width="1100px"
  alt="A screenshot of the compute cuter website"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1615658708/maggieappleton.com/notes/femme-dev/compute_cuter_-_a_guide_to_cute-ifying_your_computer_xu8th0.png"
/>

Considering the plethora of males in development, the rise of femme aesthetics is perhaps both curious and not.

<ComingSoon />


A collection of observations on the rise of soft, sparkly, baby pink aesthetics among developers

Pink, Soft, Glittering Developers


<IntroParagraph>

People who want to improve their drawing and illustration skills [[frequently ask]] what books, courses, and resources I recommend. Trying to Google it leads to an overwhelming pile of cruft and most of the great resources aren't anywhere on the first 10 pages of search results.

</IntroParagraph>

I've compiled all my favourite learning platforms, courses, and books below to help guide you towards the good stuff. Everything below will help teach you how to work in the [[meat and medium]] of visual language, rather than focusing on the materials (the "which iPad should I buy?" distraction). <Footnote idName={1}>If you desperately want to focus on tooling, you can read about the hardware and software I use over on [What App is That?](/apps)</Footnote>

I've read every book and taken most of the course on this page, so can at least vouch for them first-hand. But be aware it's not exhaustive. The volume of illustration education avaliable online is constantly growing and I don't keep close tabs on it anymore.

<Center>

## Learning Platforms and Courses

</Center>

<TwoColumn maxWidth="1200px" alignItems="top">

<LinkCard url="http://bit.ly/35UyJ8l" title="Schoolism" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779716/maggieappleton.com/notes/illustration-resources/schoolism_upphcl.png">

Primarily aimed at concept artists and digital painters, Schoolism is strong
on advanced fundamentals.

Probably too intense for beginners. Dives deep on
rendering, composition, and character design.

<br />

**Recommended Courses**

[Drawing Fundamentals](https://schoolism.com/courses/drawing/drawing-fundamentals-thomas-fluharty) by Thomas Fluharty

[Pictorial Composition](https://schoolism.com/courses/illustration/pictorial-composition-nathan-fowkes) by Nathan Fowkes

[Essentials of Realism](https://schoolism.com/courses/illustration/essentials-of-realism-jonathan-hardesty) by Jonathan Hardesty

[Fundamentals of Lighting](https://schoolism.com/courses/art/fundamentals-of-lighting-sam-nielson) by Sam Nielson

</LinkCard>

<LinkCard url="http://bit.ly/3a1S6Q5" title="New Masters Academy" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/nma_gh0mzu.png">

While a bit old school and slow-paced, the instructors on here are true veterans. Many are classical painters and sculpters, or come from the visual development and film world.

They're strong on anatomy, traditional painting yechniques, and compositional layout theory.

<br />

**Recommended Courses**

[Composition for Visual Artists](https://www.nma.art/courses/composition-for-visual-artists/) by Bill Perkins

[Constructive Head Drawing](https://www.nma.art/courses/constructive-head-drawing/) by Steve Huston

[Elements of Traditional Composition](https://www.nma.art/courses/elements-of-traditional-composition-with-glenn-vilppu-2013/) by Glenn Vilppu

</LinkCard>

<LinkCard url="http://bit.ly/2uN8KTr" title="School of Visual Storytelling" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779504/maggieappleton.com/notes/illustration-resources/svs_x6axnq.png">

Strong on beginner fundamentals – great for anyone just getting started.

Jake Parker and Will Terry teach drawing and digital painting from the ground up through sets of well-designed, hands-on exercises.

<br />

**Recommended Courses**

[How to Draw Everything](https://courses.svslearn.com/courses/how-to-draw-everything) by Jake Parker

[Basic Perspective Drawing](https://courses.svslearn.com/courses/basic-perspective-drawing) by David Hohn

[Painting Color and Light](https://courses.svslearn.com/courses/painting-color-and-light) by Will Terry

[Creative Composition](https://courses.svslearn.com/courses/creative-composition) by Will Terry

</LinkCard>

<LinkCard url="http://bit.ly/3aaLajJ" title="Art of Aaron Blaise"  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/aaronblaise_iro6yk.png">

Animation, animals, and character design are the focus here. Ex-Disney artist Aaron Blaise leads most of the courses – his teaching style is friendly and laid-back.

These courses assume basic drawing skills and cover more advanced topics.

<br />

**Recommended Courses**

[Taking Control of Colour](https://creatureartteacher.com/product/color-theory-class-ronnie-wiliford/) by Ronnie Williford

[Character Design](https://creatureartteacher.com/product/character-design-course-aaron-blaise/) by Aaron Blaise

[The Art of Storyboards](https://creatureartteacher.com/product/storyboard-course-with-lyndon-ruddy/) by Lyndon Ruddy

</LinkCard>

<LinkCard url="http://bit.ly/34O5F1K" title="Peter Han"  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638827480/maggieappleton.com/notes/illustration-resources/peterhan_ardexg.png">

Infamous for his pen and ink techniques, Peter is a master of the Dynamic Sketching style that has spread throughout the art education world. He's a seasoned instructor who knows how to break down concepts into simple, understandable principals.

He runs online courses and individual mentorships a few times a year, as well as in-person workshops in LA and Europe

</LinkCard>

<LinkCard url="http://bit.ly/2NnE6pR" title="Draw a Box" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638827480/maggieappleton.com/notes/illustration-resources/drawabox_yjrfl0.png">

A community favourite, this site walks you through the core concepts of Dynamic Sketching in a well-organised set of lessons.

Covers the essentials of drawing smooth lines, creating textures, and (obviously) drawing good boxes! You can even get feedback on the homework assignments through their group discord or subreddit.

</LinkCard>

<LinkCard url="http://bit.ly/36PRv1P" title="Modern Day James" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638827480/maggieappleton.com/notes/illustration-resources/moddayjames_fpp9tn.png">

James is an independent creator running a patreon and selling individual gumroad courses. The style is more directed at game design and concept art for films, but builds on top of classic drawing techniques that are valuable no matter what kind of medium you're interested in.

</LinkCard>

<LinkCard url="http://bit.ly/2NhnKiH" title="Ty Carter" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638827480/maggieappleton.com/notes/illustration-resources/tycarter_brecyy.png">

Another independent teacher, Ty is a background designer from the animation world creating tutorials on Patreon and Gumroad.

Strong on lighting & colour theory, stylised illustration techniques, and visual design principals

</LinkCard>

<LinkCard url="http://bit.ly/2uKMYj2" title="Concept Design Academy" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638827480/maggieappleton.com/notes/illustration-resources/cda_pwjvsb.png">

An in-person training school in Pasadena, California that offers a full curriculum of foundational illustration and design skills.

The instructors are all working professionals in the concept art industry, and teaching courses on evenings and weekends.

</LinkCard>

<LinkCard url="http://bit.ly/3a06Ui5" title="Ctrl+Paint" image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638827480/maggieappleton.com/notes/illustration-resources/ctrlpaint_wrnj50.png">

An impressivly high-quality and sizeable collection of video tutorials by Matt Kohr. The videos focus on fundamental painting techniques, specifically around building skills for concept art and digital work.

A great spot for beginners – Matt covers all the basics in a well organised sequence.

</LinkCard>

</TwoColumn>

<Center>

## Books

</Center>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/41583721-how-to-think-when-you-draw-volume-1"
  title="How to Think When You Draw"
  author="Lorenzo Etherington"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779504/maggieappleton.com/notes/illustration-resources/lorenzo_rw2yuo.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/15808089-how-to-draw"
  title="How to Draw"
  author="Scott Robertson"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779504/maggieappleton.com/notes/illustration-resources/robertsondraw_lubamf.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/2766647-creative-illustration"
  title="Creative Illustration"
  author="Andrew Loomis"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/loomiscreative_njwqd8.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/23389095-framed-ink-marcos-mateu-mestre"
  title="Framed Ink: Drawing and Composition for Visual Storytellers"
  author="Marco Mateu-Mestre"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/framedink_h9pder.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/2767856-sketching"
  title="Sketching: Drawing Techniques for Product Designers"
  author="Koos Eissen"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/koossketching_i6ovzm.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/146300.Rapid_Viz_"
  title="Rapid Viz"
  author="Kurt Hanks & Larry Belliston"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779504/maggieappleton.com/notes/illustration-resources/rapidviz_mfopn4.jpg"
/>

<ResourceBook
  small
  url="https://www.gallerynucleus.com/detail/21089/"
  title="Dynamic Bible"
  author="Peter Han"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/dynamicbible_scuqpu.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/6250465-drawn-to-life"
  title="Drawn to Life: Volumes I and II"
  author="Walt Stanchfield"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/drawnlife_p2eanr.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/1027978.Fun_with_a_Pencil"
  title="Fun with a Pencil"
  author="Andrew Loomis"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/funpencil_cohrn3.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/136091.The_Animator_s_Survival_Kit"
  title="The Animators Survival Kit"
  author="Richard Williams"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/animator_vvevbn.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/899923.Force"
  title="Force: Dynamic Life Drawing for Animators"
  author="Michael D. Mattesi"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/force_jeslfd.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/102920.Understanding_Comics"
  title="Understanding Comics"
  author="Scott McCloud"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/comics_vmklzx.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/2393396.Graphic_Storytelling_and_Visual_Narrative"
  title="Graphic Storytelling and Visual Narrative"
  author="Will Eisner"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/graphicstory_srgm0q.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/517518.Thinkertoys"
  title="Thinkertoys"
  author="Michael Michalko"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779504/maggieappleton.com/notes/illustration-resources/thinkertoys_bvvn4w.jpg"
/>

<ResourceBook
  small
  url="https://www.goodreads.com/book/show/10675.Lateral_Thinking"
  title="Lateral Thinking"
  author="Edward de Bono"
  image="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1638779503/maggieappleton.com/notes/illustration-resources/latthinking_iw53ec.jpg"
/>


My favourite resources for learning to draw and developing your visual thinking skills

The Best Illustration Books and Courses


<AssumedAudience>

People familiar with the _tools for thought_, personal knowledge management, and notetaking space / twitterverse

</AssumedAudience>

<IntroParagraph>

The term **tools for thought** has become a new rallying point over the last few years. People who might otherwise gather around keywords like _personal knowledge management_, _networked thought_, _productivity_, or _knowledge work_ are reframing their work.

</IntroParagraph>

The phrase appears on the landing page of every hot new note-taking app:

<ImageFrame
  showalt
  width="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1000/v1637794932/maggieappleton.com/notes/tools-for-thought/Muse_your_tool_for_thought_cqkrxu.png"
  alt="Muse for iPad"
/>

<ImageFrame
  showalt
  width="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1000/v1637794932/maggieappleton.com/notes/tools-for-thought/Roam_Research_A_note_taking_tool_for_networked_thought._nbtjab.png"
  alt="Roam Research"
/>

<ImageFrame
  showalt
  width="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1000/v1637794932/maggieappleton.com/notes/tools-for-thought/Kosmik_phl9wo.png"
  alt="Kosmik App"
/>

The phrase was first used by Kenneth Iverson in their 1979 paper [Notation as a Tool for Thought](https://www.eecg.utoronto.ca/~jzhu/csc326/readings/iverson.pdf). Howard Rheingold picked it as the title of their 1985 book [Tools for Thought](https://mitpress.mit.edu/books/tools-thought) – a speculative history of how computing might unfold throughout the 1990's.

<ResourceBook
  url="https://www.librarything.com/work/2127253"
  title="Tools for Thought"
  author="Howard Rheingold"
  image="/images/books/toolsthought.jpg"
/>

---

[Andy Matuschak](https://andymatuschak.org/) and [Michael Neilson](https://michaelnielsen.org/)'s 2019 essay on [transformative tools for thought](https://numinous.productions/ttft/) helped kick off the new popularity wave, as well as Andy's [continued research](https://www.patreon.com/quantumcountry) and writing advocating for TFT as a field.

<ImageFrame
  width="1200"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1637795112/maggieappleton.com/notes/tools-for-thought/How_can_we_develop_transformative_tools_for_thought_i64mlz.png"
  alt=""
/>

There's something odd in the way people are currently using the term though.

If we take the phrase at face value, as anything that helps humans think different kinds of thoughts, the list of historical examples should certainly include:

- Written language
- Hindu-arabic numeral system
- The Socratic Method
- The Scientific Method
- Data visualisations
- Spreadsheets
- Cartesian coordinates

All of these things pre-date digital computers by at least a few hundred years (if not thousands).

<ComingSoon />


The written version of my talk on seeing tools for thought in historical perspective

Tools for Thought as Cultural Systems, not Computational Objects


<IntroParagraph>
    
A <b>Pattern Language</b> is a set of flexible, reusable solutions to common design problems. 
These patterns evolve naturally within systems, and are found rather than crafted. Identifying and recognising these patterns gives us a framework to craft solutions with.

</IntroParagraph>

There is no one way to implement a design pattern – they are purposefully abstract enough that you can apply them to the situation at hand. They're guiding principles instead of formulaic instructions.

Languages like [[The Knowledge Hydrant]] for collaborative learning and [Material Design](https://material.io/design) for digital screens are examples of pattern languages working out in the wild.

### The history of pattern languages

Christopher Alexander developed the idea of Pattern Languages in their 1977 book by the same name.

<ResourceBook
  url="https://en.wikipedia.org/wiki/A_Pattern_Language"
  image="/images/books/patterns.jpeg"
  title="A Pattern Language"
  author="Christopher Alexander"
>
  The book outlined a number of solutions for architecture and urban planning
  design, but the theory has since (appropriately) taken on a life of its own.
</ResourceBook>

Alexander was an architect and urban planner working on building cities and homes condusive to harmonious living.

### Pattern languages in programming

The programming community picked up on on Christopher Alexander's ideas in the late 1980's.

Despite the original book being primarily about public transportation tempos and cafe sidewalk strategies, the notion of design patterns heavily influenced the development of <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">Object-Oriented Programming</a> languages like Smalltalk and C++.

In a charming presentation at the 1996 OOPSLA conference (Object-Oriented Programs, Systems, Languages and Applications, obviously), Alexander openly admits **"I'm about to address a room full of people and I don't know hardly anything about what all of you do"**.

<Video src="https://www.youtube.com/embed/98LdFA-_zfA" />

> Some computer scientist called me and said they had a group of people in Silicon Valley willing to pay $3,000 to have dinner with me... and I thought "What the hell is this?"

[Richard Gabriel](http://dreamsongs.com/SiteMap.html), an engineer at
IBM, was one of the ring leaders actively building these bridges between
software and built landscapes.

### Pattern languages in interface design and design systems

<ComingSoon />


Notes on pattern languages and Christopher Alexander's legacy on software programming

Pattern Languages in Programming and Interface Design


<IntroParagraph>

At [React Rally 2020](http://reactrally.com) I gave a talk on magic, kinship, and ritual within the React development community. Anthropology isn't something we hear a lot of about in the world of programming, and this is my lighthearted attempt to explore some of the odd cultural behaviours and norms we've come to see as 'normal' in the web development world.

</IntroParagraph>

You can watch the whole talk below, or scroll down to see slides and read the transcript.

<Video
  src="https://www.youtube.com/embed/8snrXgzM1bM?start=484"
  title="The cultural anthropology of react"
/>

<BasicImage
  width="880px"
  alt="The cultural anthropology of react title slide"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_880/v1597334915/maggieappleton.com/notes/anthropology-react-slides/ReactRally2020-Draft1.001.png"
/>

## Links and References

- "Anthropology is Philosophy with the people in it" - [Tim Ingold](https://en.wikipedia.org/wiki/Tim_Ingold) from [Anthropology: Why it Matters](/anthropology-matters) (An excellent brief introduction to Anthropology).
- "Deep Hanging Out" coined by [Clifford Geertz](https://en.wikipedia.org/wiki/Clifford_Geertz) in a [1998 New York Review of Books essay](http://hypergeertz.jku.at/GeertzTexts/Deep_Hanging.htm)
- [Imagined Communities](/imagined-communities) theory from [Benedict Anderson](https://en.wikipedia.org/wiki/Benedict_Anderson)
- Social interaction is a performance by [Erving Goffman](https://en.wikipedia.org/wiki/Erving_Goffman). Proposed in the book [The Presentation of Self in Everyday Life](https://www.librarything.com/work/5484)
- [Cultural Capital](https://en.wikipedia.org/wiki/Cultural_capital) - The theory cultural knowledge and information you hold within a community works in much the same way as financial and material capital. From [Pierre Bourdieu's](https://en.wikipedia.org/wiki/Pierre_Bourdieu) essay one [Cultural Reproduction and Social Reproduction](http://piggottsclass.weebly.com/uploads/2/3/1/7/23179512/bourdieup_cultural_and_social_reproduction.pdf)
- [Alfred Gell](https://en.wikipedia.org/wiki/Alfred_Gell) on the connections between technology, enchantment, and magic in [his essay on](https://www.brown.edu/Departments/Joukowsky_Institute/courses/materialworlds/files/1108595.pdf) **The Technology of Enchantment and the Enchantment of Technology**
- "Technology is society made durable" from [Bruno Latour](https://en.wikipedia.org/wiki/Bruno_Latour) in his [1990 essay](http://www.bruno-latour.fr/sites/default/files/46-TECHNOLOGY-DURABLE-GBpdf.pdf) by the same title.

<Center>

<SimpleCard>

### Take a look at all the [slides on Github](https://github.com/MaggieAppleton/react-anthropology-slides)

</SimpleCard>

</Center>

---

## The Abridged Essay Version

I've been immersed in the world of React developers since 2016. As a cultural anthropologist, the beliefs, norms, and social dynamics of Reactland have always been more intriguing to me than the useEffect hook or concurrent mode.

### What is cultural anthropology?

If you have never head of "**cultural anthropology**," don't worry. That's expected. It doesn’t often overlap with the world of web development and as a discipline it's not great at self-promotion.

It's essentially the study of human cultures and trying to understand how they work.

Or as one of my favourite anthropologists [Tim Ingold](https://en.wikipedia.org/wiki/Tim_Ingold) puts it:

<BasicImage
  width="880px"
  alt="Cultural anthropology is philosophy with the people in it"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1597334937/maggieappleton.com/notes/anthropology-react-slides/ReactRally2020-Draft1.012.png"
/>

<Subtext>

From [Anthropology: Why it Matters](/anthropology-matters)

</Subtext>

Anthropology tries to answer many of the same questions philosophers concern themselves with;

_Why do we have language?
How should we organise our societies and institutions?
How do we deal with birth, death, morality, and conflict?_

Philosophers turn inwards to find these answers. They go into a small quiet room alone, think a lot, and read books by mostly old dead white men to find answers.

In contrast, Anthropology turns outwards - **it looks for the answers in people.** By living among them, learning from them, and taking part in their lives. A process known as [Participant Observation](https://en.wikipedia.org/wiki/Participant_observation).

It isn't searching for one universal truth of all humanity, but rather **particular truths for particular people**, at particular points in time.

---

### Why care about the anthropology of React?

Looking at React through a cultural lens helps us understand it as more than simply **"a JavaScript library for building user interfaces"**.

Technical definitions can be reductive - they draw a technological box around our concepts that hide the historical and cultural context.

<BasicImage
  width="880px"
  alt="The react logo inside a strict technical box"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1597334929/maggieappleton.com/notes/anthropology-react-slides/ReactRally2020-Draft1.008.png"
/>

What happens if we expand our understanding to include all the people who surround this React, and how they might **affect** and **be affected by** what's inside it?

<BasicImage
  width="880px"
  alt="An expanded circle of all the people of react"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1597334932/maggieappleton.com/notes/anthropology-react-slides/ReactRally2020-Draft1.010.png"
/>

What if we entertain the idea that humans and the culture of React are an essential part of what defines React? What if we consider it a cultural ecosystem we're _active participants_ in, rather than simply a package we `npm install`

Cultural anthropology is perfectly placed to help us find answers to these questions.

---

### Understanding the "The React Community"

We should establish who we’re talking about when we say “the react community” - where do we think the boundaries of the React community are, and who do we think is part of it?

<BasicImage
  width="880px"
  alt="How do we define the React community?"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1597334943/maggieappleton.com/notes/anthropology-react-slides/ReactRally2020-Draft1.014.png"
/>

I drew a very incomplete and fuzzy map of the React world here. It’s definitely not comprehensive or to scale.

<img
  alt="A hand drawn map of the react community"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1597334948/maggieappleton.com/notes/anthropology-react-slides/ReactRally2020-Draft1.015.png"
/>

I drew this to point out two key things.
First, being a React person isn’t a mutually exclusive identity - you can be other things too.

We have many overlapping and neighbouring communities we all belong to. You might also be part of the Data Viz world, or hang out within a sub niche like React Native.

Second, our community has very fluid boundaries. People flow in and out quite easily – anyone who finds it can join. To become a member you didn’t need to fill out a form and send it to a committee, or go through an initiation ceremony.

You also have the freedom to leave whenever you like.

These fuzzy boundaries sometimes make us a little bit anxious - it's hard to know who's part of the group, and weakens our sense of being a cohesive whole.

Another way to try and understand the React community is to look at some rough numbers.

<BasicImage
  width="880px"
  alt="Stats on how many React developers participate in Github, Reddit, and Dsicord groups"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1597334954/maggieappleton.com/notes/anthropology-react-slides/ReactRally2020-Draft1.016.png"
/>

These are interesting indicators, but they're not necessarily helpful if we're primarily interested in how React works as a cultural system.

---

### React is an Imagined Community

Rather than talking about stats and numbers, it’s much more meaningful for us to talk about React an an [imagined community](/imagined-communities)

This was a concept developed by a political scientist called [Benedict Anderson](https://en.wikipedia.org/wiki/Benedict_Anderson) in the 1980’s.

Anderson was writing about how nations imagine themselves as collective wholes, but his theory maps very well to how online communities like React work.

An imagined community has nothing to do with it being imaginary in the sense of being fake, but simply that it’s something we have to mentally construct across thousands of individual minds. It gets built through shared images and rituals.

Anderson specifically uses the idea of a national daily newspaper.

The act of sitting down and reading the daily news, and imagining a whole nation of other people, similar like you, sitting and reading those exact same words at roughly the same time, creates a sense of collective belonging.

It’s a daily ritual that reaffirms your membership, and sense of unity with a greater whole.

<ComingSoon />


A cultural analysis of the native behaviour of React developers

The Cultural Anthropology of React


[Jared Pereira](https://awarm.space/) has been running a wonderful series of personal [website tours](https://www.youtube.com/playlist?list=PLEXbN99LY3OCarUeXcxWeZzOelXQvVdAA). The guest list features many of my favourite [[Digital Gardeners]] and [indie web](https://indieweb.org/) creators such as [Tom Critchlow](https://tomcritchlow.com/), [Chris Aldrich](https://boffosocko.com/), and [Azlen Elza](https://azlen.me/).

At the end of 2020 I stopped in to show what this website looks like behind the Wizard of Oz curtain:

<Alert>

The video walkthrough on this page walks through how I built my [previous
website](https://github.com/MaggieAppleton/maggieappleton.com) in Gatsby.js. To learn about the tech stack behind the current
version visit the
[Github](https://github.com/MaggieAppleton/maggieappleton.com-V2)

</Alert>

<Video src="https://www.youtube.com/embed/bUGoPcQleto" />

<Spacer size="small" />

### Tech Stack and Features

- Built with [Gatsby](https://www.gatsbyjs.org/), which uses [React](https://reactjs.org/) for rendering and [GraphQL](https://graphql.org/) for data fetching
- All posts (notes, essays, books) written with [MDX](https://mdxjs.com/) - allows me to write React components inside markdown files for extra JavaScript power ✨
- I use the CSS-in-JS library [emotion](https://emotion.sh/docs/introduction) for styling components
- Responsive footnotes implemented with [Tufte CSS](https://edwardtufte.github.io/tufte-css/) (no JavaScript required!)
- [[Bi-Directional Links]] with <a href="https://github.com/aengusmcmillin/gatsby-theme-brain">gatsby-theme-brain</a>, and page previews adapted from <a href="https://github.com/aravindballa/gatsby-theme-andy">gatsby-theme-andy</a>
- [Tippy.js](https://atomiks.github.io/tippyjs/) for tooltip popovers
- Images hosted on [Cloudinary](https://cloudinary.com/) to avoid the long build times when using [gatsby-image](https://www.gatsbyjs.org/packages/gatsby-image/)
- Deploys to [Netlify](https://www.netlify.com/) directly from Github. Currently takes 4 minutes for the site to build and deploy. I have no idea if that's good or not, but I'll take it 🤷🏻‍♀️

<Spacer size="small" />

<SimpleCard>

If you want to see all the source code yourself, feel free to wander around in the [Github repo](https://github.com/MaggieAppleton/maggieappleton.com).

</SimpleCard>


A video tour through how I build the old version of this site

A Meta-Tour of This Site

The introduction to my thesis on the Quantified Self movement and the culture of self-tracking

Tracking Humanity


<IntroParagraph>

My obsession with metaphor isn't original, it's genetically inherited. My mother <a href='http://www.thelibrarianedge.com/'>Katie Day</a> planted all the original seeds. The paperback copies of [Metaphors We Live By](https://www.google.co.uk/books/edition/Metaphors_We_Live_By/m8Sp5m9vZcwC) and [Women, Fire, and Dangerous Things](https://www.google.co.uk/books/edition/Women_Fire_and_Dangerous_Things/CfCnzSF9de8C) are visceral childhood memories as much as they're current intellectual kindling.

</IntroParagraph>

As a teacher and librarian, her research focuses on using metaphors in pedagogy, digital literacy, and information science. But our worlds overlap in the more fundamental obsession with how we can use metaphors to communicate ideas to others.

We started collecting <a href="https://www.librarything.com/list/20481/all/Metaphors-etc">a metaphorical reading list</a> a few years back that I just rediscovered.

If you're exploring conceptual metaphor and want to start digging deeper, have a look at these

<ResourceBook
  url="https://www.librarything.com/work/63333"
  title="Metaphors We Live By"
  author="George Lakoff & Mark Johnson"
  image="/images/books/mwlb.jpg"
  small
/>

<ResourceBook
  url="https://www.librarything.com/work/45956"
  title="Philosophy in the Flesh"
  author="George Lakoff & Mark Johnson"
  image="/images/books/flesh.jpeg"
  small
/>

<ResourceBook
  url="https://www.librarything.com/work/249581"
  title="The Way We Think"
  author="Gilles Fauconnier & Mark Turner"
  image="/images/books/waywethink.jpeg"
  small
/>

<ResourceBook
  url="https://www.librarything.com/work/63555"
  title="Women, Fire, and Dangerous Things: What Categories Reveal About the Mind"
  author="George Lakoff"
  image="/images/books/womenfire.jpeg"
  small
/>

<ResourceBook
  url="https://www.librarything.com/work/9544846"
  title="Surfaces and Essences: Analogy as the Fuel and Fire of Thinking"
  author="Douglas Hofstadter & Emmanuel Sander"
  image="/images/books/surfaces.jpeg"
  small
/>

<ResourceBook
  url="https://www.librarything.com/work/10674534"
  title="I Is an Other"
  author="James Geary"
  image="/images/books/iother.jpeg"
  small
/>


A collection of my favourite books on conceptual metaphor theory

A Metaphorical Reading Collection


<IntroParagraph>

My previous website was built in a JavaScript framework called [Gatsby.js](https://www.gatsbyjs.org/). It's one of a host of new website builders based around [static site-generation](https://www.netlify.com/blog/2020/04/14/what-is-a-static-site-generator-and-3-ways-to-find-the-best-one/) and [the JAMStack](https://jamstack.wtf/) <Footnote idName={1}>JAM stands for JavaScript, APIs, and Markup. It's a relatively new approach to building websites that's been gaining popularity over the last half decade.</Footnote> If you've heard of Gatsby before but haven't wrapped your head around it yet, this might be for you.

</IntroParagraph>

I already have some illustrated notes up on using the [[JAMStack with Gatsby & Contentful]] and [[Building Gatsby Themes]], but they're a little more advanced.

[Khaled Garbaya](https://khaledgarbaya.net/) put out an egghead course on
[Getting Started with Gatsby](https://egghead.io/courses/get-started-with-gatsby) that's better suited to Gatsby beginners.

## Illustrating the Key Concepts

I made a set of illustrations that capture the _key concepts_ from Khaled's course. They don't summarise all the course content. They're just supporting material that help clarify the most important ideas.

First up is a **big picture view** showing all the essential parts of a Gatsby site.

<BasicImage
  alt="Gatsby is a collection of tools for building static sites"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1597741851/maggieappleton.com/egghead-course-notes/intro-gatsby/IntroGatsby_1_Small.png"
/>

Gatsby sites are able to pull in data from multiple sources all at once. This includes REST API endpoints, classic content management systems like [Wordpress](https://www.gatsbyjs.com/guides/wordpress/) or [Contentful](https://www.gatsbyjs.com/blog/2018-1-25-building-a-site-with-react-and-contentful/), or just your local file system.

These are pulled in through [GraphQL](https://www.graphql.com/), which acts as a _transportation layer_.

[Node.js](https://www.gatsbyjs.com/docs/glossary/node/) is the main engine inside a Gatsby site which generates the pages, nodes, and metadata.

And finally [React](https://www.gatsbyjs.com/docs/glossary/react/) creates all the user interface elements.

### Page Queries vs. Static Queries

Once people wrap their heads around the structure of a Gatsby project, GraphQL is usually one the first sticking points.

If you've never worked with it before, the syntax looks very odd and it's hard to tell what it's doing.

It gets more confusing to learn there are _two types of queries_ - **page queries** and **static queries**

<BasicImage
  alt="Diagram of a pageQuery request inside a page, and a static query request inside a component"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1597741854/maggieappleton.com/egghead-course-notes/intro-gatsby/IntroGatsby_2_Small.png"
/>

It only seems complex on the surface, but it's easy to distinguish these two. Most of your queries will be page queries – these live inside your page files like `blog.js` or `about.js`

Static queries go inside individual component files like `Navbar.js` or `Footer.js`. There's also a handy React hook to handle these for us: [useStaticQuery](https://www.gatsbyjs.com/docs/use-static-query/)

### Progressive Enhancement

One of the main benefits of a Gatsby site is it uses a technique called **Progressive Enhancement** to render pages.

<BasicImage
  alt="Animation of a page rendering static HTML elements first, then being updates with React afterwards"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1597741856/maggieappleton.com/egghead-course-notes/intro-gatsby/IntroGatsby_3_Animation.gif"
/>

This is what makes Gatsby page look like they load quickly. The lightweight static HTML version appears first, and then heavier files and interactive elements are layered on afterwards.

React handles any changes and user interactions. Once an element is clicked or changed, React "[rehydrates](https://www.gatsbyjs.com/docs/react-hydration/)" the page.

<br />

These illustrations are part of the [egghead community notes](https://github.com/eggheadio/eggheadio-course-notes/tree/master/get-started-with-gatsby) on Khaled's [Get Started with Gatsby course](https://egghead.io/courses/migrate-from-create-react-app-to-gatsby).

You can find more notes taken by people who have been through the course on there.
If you take the course yourself, you can also add to them to the shared [github repo](https://github.com/eggheadio/eggheadio-course-notes/tree/master/get-started-with-gatsby).


Illustrated notes on the key concepts of how Gatsby.js works

Illustrating Gatsby's Key Concepts


I've been a [cellular agriculture](https://www.new-harvest.org/cell_ag_101) and [cultured meat](https://en.wikipedia.org/wiki/Cultured_meat) enthusiast for a couple of years now. If you've never heard of cultivated meat, my [illustrated notes](/meat-planet) on the fantastic book **Meat Planet** will get you caught up.

The TLDR is we've found a way to grow meat without killing animals. You can see why this might be intriguing.

At fifteen I read [Fast Food Nation](https://www.librarything.com/work/3735), [The Omnivore's Dilemma](https://www.librarything.com/work/504173), and [Stuffed and Starved](https://www.librarything.com/work/3657642) in quick succession. That was sadly the end of enjoying [hawker stall chicken rice](https://theculturetrip.com/asia/singapore/articles/a-brief-history-of-hainanese-chicken-rice-singapores-national-dish/).

In the 14 years since, I've maintained various levels of Really Bad veganism. <Footnote idName={1}>The highly flawed and non-judgemental variety. I have no interest in policing your personal plate. </Footnote> Which is the state of knowing all the facts, understanding their moral implications, and still only making the "right choice" about 82% of the time.

Because here's the thing; [given the statistics](https://www.statista.com/statistics/237464/share-of-vegans-in-the-united-states/), individuals voluntarily choosing to be vegan, and/or putting enourmous effort into convincing other people into veganism is a terrible game plan for addressing the complex, wide-ranging problems of animal agriculture:

<BasicImage
    width="700px"
    alt="Statistic: Do you consider yourself to be vegan? | Statista"
    src="https://www.statista.com/graphic/1/237464/share-of-vegans-in-the-united-states.jpg"
/>

<Subtext>
    {" "}
    A sad bar chart from <a
        href="https://www.statista.com/statistics/237464/share-of-vegans-in-the-united-states/"
        rel="nofollow"
    >
        Statistica
    </a>{" "}
</Subtext>

---

Rather than judgementally guilt-tripping people into making _hard sacrifices_, exploring alternative ways of making meat (and meat-alternatives that aren't sad lumps of tofurkey) feels like a better use of everyone's time.

The thriving industry of cultured meat and cellular agriculture agrees. Research organisations like the [Good Food Institute](https://www.gfi.org/) and [New Harvest](https://www.new-harvest.org/) have been promoting, funding, and supporting new companies in this space over the last few years.

Keen to get involved, I talked my way into sketchnoting the 2019 [New Harvest conference](/newharvest2019) at the MIT Media Lab.

<br />

## Illustrated notes from the New Harvest 2019 Conference

<TwoColumn>

<img
    alt="illustrated notes on biotechnology and fisheries"
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_800/v1589845700/maggieappleton.com/new-harvest-2019/NH_10-Sullivan.png"
/>

<img
    alt="illustrated notes on decellularized plant scaffolds"
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_800/v1589845680/maggieappleton.com/new-harvest-2019/NH_1-CampuzanoArtboard-1.png"
/>

<img
    alt="illustrated notes on engaging people with cultivated meat by being transparent and clearly labelling food"
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_800/v1589845696/maggieappleton.com/new-harvest-2019/NH_5-Arceolo.png"
/>

<img
    alt="illustrated notes in cellular changes in proteins"
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_800/v1589845711/maggieappleton.com/new-harvest-2019/NH_11-CoxArtboard-1.png"
/>

</TwoColumn>

---

The conference work led to a new initiative with New Harvest; illustrating a series of podcast episodes around their impressive community of [research fellows](https://www.new-harvest.org/current_research_projects).

The [Cultured Meat and Future Foods Show](https://anchor.fm/futurefoodshow/) interviewed each research fellow. For each episode I made a one-shot illustrated summary that explains their research focus.

## Cultured Meat and Future Foods Show illustrations and episodes

### Natalie Rubio on Insect Cell Cultures

<BasicImage
    width="880px"
    alt=""
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_990/v1596579655/maggieappleton.com/notes/new-harvest-podcast/NH1_Rubio_Full.png"
/>

<Podcastiframe
    src="https://anchor.fm/futurefoodshow/embed/episodes/Natalie-Rubio---New-Harvest-Fellowship-Series-eesp9p/a-a2c2nno"
    scrolling="no"
></Podcastiframe>

---

### Sam Peabody on Food Safety

<BasicImage
    width="880px"
    alt=""
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_990/v1596579662/maggieappleton.com/notes/new-harvest-podcast/NH2_Peabody_Full.png"
/>

<Podcastiframe
    src="https://anchor.fm/futurefoodshow/embed/episodes/Sam-Peabody---New-Harvest-Fellowship-Series-efr659/a-a2hpocq"
    scrolling="no"
></Podcastiframe>

---

### Jordan Jones on Decellularized Meat

<BasicImage
    width="880px"
    alt=""
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_990/v1596579667/maggieappleton.com/notes/new-harvest-podcast/NH3_Jones_Full.png"
/>

<Podcastiframe
    src="https://anchor.fm/futurefoodshow/embed/episodes/Jordan-Jones---New-Harvest-Fellowship-Series-ege5pl/a-a2l5264"
    scrolling="no"
/>

---

### Janis Wollschlaeger on 3D Printing

<BasicImage
    width="880px"
    alt=""
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_990/v1596579671/maggieappleton.com/notes/new-harvest-podcast/NH4_Jannis_Full.png"
/>

<Podcastiframe
    src="https://anchor.fm/futurefoodshow/embed/episodes/Jannis-Wollschlaeger---New-Harvest-Fellowship-Series-DE-egnesi/a-a2mpdp7"
    scrolling="no"
></Podcastiframe>

---

### Andrew Stout on Nutritional Engineering

<BasicImage
    width="880px"
    alt=""
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_990/v1596579677/maggieappleton.com/notes/new-harvest-podcast/NH5_Stout_Full.png"
/>

<Podcastiframe
    src="https://anchor.fm/futurefoodshow/embed/episodes/Andrew-Stout---New-Harvest-Fellowship-Series-ehm8uu/a-a2s6l6n"
    scrolling="no"
></Podcastiframe>


Illustrations made for a set of episodes of the Cultivated Meat podcast

New Harvest & Illustrating the Cultivated Meat Podcast


<IntroParagraph>
    
Nearly every computer programme created in the last 68 years was made by typing linear characters into a text editor. <a href="https://en.wikipedia.org/wiki/ASCII"> ASCII</a> symbols arranged from left
to right, top to bottom, are the universal medium of code.

</IntroParagraph>

<img
  width="570px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1627424133/maggieappleton.com/notes/learnable-programming/linear-code_shrink_ss6iqj.png"
  alt="Python code showing a function that solves the FizzBuzz challenge in a text file"
/>

Every language from FORTRAN to Python to Haskell works this way.

It's then unsurprising every major IDE <Footnote idName={1}>IDE stands for intergrated development environment. Essentially a souped up text editor with lots of helpful functionality for programmers baked in.</Footnote> and code editor is designed to optimise working in text; VS Code, Vim, PyCharm, WebStorm, xCode, Atom, Sublime Text are all text-first environments.

<BasicImage
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1627423845/maggieappleton.com/notes/learnable-programming/code-editors_rabptu.png"
  alt="The standard text-heavy interfaces of WebStorm, xCode, and VSCode"
  imageWidth="1300px"
  showalt
/>

This might seem so obvious it's not worth pointing out. Textual programming is the water we swim in. We express computation logic in written text because that must naturally and obviously the best medium for it. At least, this is what we tell ourselves from the vantage point of people who have only ever lived in a textual programming world.

What, exactly, might be the alternative to programming in pure text? Am I suggesting we interpretive dance our way through a function that prints out the Fibonacci sequence?

Not exactly. Although I would like to see someone try.

What I want to explore here is the relative **lack of visuals, graphics, and spatial design** in our current programming environments. While we've crafted widely accessible graphical user interfaces (GUIs) for everyone else, programmers remain in the land of typed commands. As the mediators between meatspace and binary logic, we don't get to click buttons, drag sliders, pan canvases, or select options from dropdown menus while we build. Instead, we type.

There are plenty of good reasons for this – both historical and logical – that we'll get into. Understanding how we ended up in this purely textual place is a necessary first step if we want to question it.

<Spacer size="small" />

## Inventing the End User

In the early 1980's a wide new divide opened up. With the rise of personal computing and the arrival of accessible machines like the Macintosh, we created a clear distinction between "programmers" and "end users." Before that point, the people who designed and wrote computer programmes were primarily the same people who used computer programmes. You couldn't do much of one without the other.

And all of these people were exclusively using text to talk to their machines. Because it was the only show in town.

The aesthetic of bright green blocky text on black terminals isn't just a fun, retro media trope – our pre-GUI interfaces geuinely looked like this.

<BasicImage
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1631569504/maggieappleton.com/notes/learnable-programming/oldinterfaces_shrink_ul4wep.png"
  alt={
    <span>
      Interfaces used between 1980-1990; courtesy of{" "}
      <a href="https://betawiki.net/">betawiki.net</a>
    </span>
  }
  imageWidth="1200px"
  showalt
/>

Before the 1980's showed up with its neon leg warmers and big hair, most computers _didn't even have screens_. You blindly typed commands onto a keyboard that punched holes into paper.

<Draft />

Many, many programmers will argue programming in linear text is simply _better_. And they're not entirely wrong. Textual notation is an extremely efficient way to condense meaning. It's quick to write and allows us to create precise abstractions other programmers can interpret and work with.

By _graphical_ I mean any arrangement of shapes (square, circle, irregular nonagon, what have you) in space that aren't written words.

By _spatial_ I mean the way we use our understanding of being a body with a front, back, left, right, up, and down, to understand the world around us.

Humans are exceptionally skilled at spatial thinking.

Using visual representations like maps, diagrams, and shapes in 2D / 3D space to communicate meaning is something we've been doing far longer than we've been typing text into screens. About 43,832 years longer. <Footnote idName={2}>Taking the 43,900 y.a. hunting scenes <a href="https://www.nature.com/articles/s41586-019-1806-y">found</a> in Sulawesi, Indonesia as a conservative marker of when we first started doing pictorial storytelling on surfaces around us</Footnote> Given all that time, humans are much better at reasoning using graphical and spatial mappings than they are with linear abstract text.

I am certainly not to first to find it odd. People have been harping on about the limitations of textual programming since the beginning of programming. These complainers tend to gather under the umbrella of **Visual Programming** – a field that encompasses so many efforts and projects it's hard to figure out what it wants.

<Spacer size="small" />

## What is Visual Programming?

Good question.

The name itself is a bit of a misnomer since anything we see with our eyes technically counts as _visual._ Which would certainly include linear text. When people use the term they are usually referring to some kind of **spatial** or **graphical** programming environment.

<Spacer size="small" />

## Visual Programming for Learnable Programming

Bret Victor coined the term <b>Learnable Programming</b> in his <a href="http://worrydream.com/LearnableProgramming">canonical essay</a> lamenting the current state of programming education. Bret has a few concerns with the way most of us learn to code. Mainly that the learning environments we drop people into are poorly designed.

These environments tend to look something like this:

<TwoColumn>

<img
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1614174726/maggieappleton.com/notes/learnable-programming/learnprog_1_nsfflv.png"
  alt="repl.it slpit screen interface"
/>
<img
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1614174727/maggieappleton.com/notes/learnable-programming/learnprog_4_dk82q8.png"
  alt="codesandbox split screen interface"
/>
<img
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1614174727/maggieappleton.com/notes/learnable-programming/learnprog_5_tlycev.png"
  alt="free code camp split screen interface"
/>
<img
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1614174726/maggieappleton.com/notes/learnable-programming/learnprog_3_bkslg8.png"
  alt="khan academy split screen interface"
/>

</TwoColumn>

<span
  style={{ textAlign: "center", marginBottom: "var(--space-m)" }}
  className="metadata"
>
  Interfaces from Repl.it, Codesandbox, freeCodeCamp, and Khan Academy
</span>

They're your standard column-based "live coding" interfaces popular across the industry. You write code into one section, and hopefully get the output you expected in another. Syntax is abstracted away from the elements it affects.

<Spacer size="small" />

### Programming into the Void

It's easy to see why these linear, text-based interfaces _seem_ like the best approach. They look identical to the standard interfaces the whole development industry uses to programme.

We write code into an isolated text editor. If you type the correct sequence of words and symbols into the editor, the correct series of events happens somewhere out of view.

We start this process in a context that looks something like this...

<MysteriousVoid />

...and get the output in a separate browser window. God only know what happened in the middle.

Functions ran in an some unseen JavaScript engine, interface elements drew themselves onto the canvas, and somewhere a value changed in a distant database.

We're only shown the end result. To see anything happening in the middle, we have to `console.log` out data at each step of the way. Or dig into dense developer panels and debuggers. The industry has accepted flying blind as standard operating procedure.

<Spacer size="small" />

### Raising the Programming Bar

We're training people in the same kind of environment they'll be working in professionally. In the just-get-a-job-mindset that's an excellent approach. But Bret isn't talking about the ideal way to learn programming in the short-term, bootcampy world view. When he talks about these environments as inadequate, he's referencing a much larger paradigm shift around how we should design human-computer interfaces.

He's pointing out that the standard text-based, disembodied, non-graphical interfaces we all put up with are unintuitive to humans who live in a highly visual, spatial, embodied world. While most of our modern user interfaces have graduated to a graphical, 3D space-based system, programming is staunchly attached to the linear text paradigm.

There's good reason for this. While many people have tried to develop [visual programming languages](https://en.wikipedia.org/wiki/Visual_programming_language), they've largely failed to gain traction. There's lots of [well-reasoned](https://www.outsystems.com/blog/posts/visual-programming-language/) [arguments](https://dzone.com/articles/visual-programming-why-its-a-bad-idea) [explaining](https://mikehadlow.blogspot.com/2018/10/visual-programming-why-its-bad-idea.html) why it's so difficult to design visual systems complex and extensible enough to programme in, so I won't repeat them here.
The fact is that our current visual languages aren't sophisticated enough to do the job, and we're a long way from any system that could.

<Spacer size="small" />

### Visual Programming for Learning

While visual programming isn't great for the scale of complexity professional programmers deal with, it's _ideal_ for people who are learning to code. When we simply need to explain what's happening under the hood, graphical representations are the best way to help people build clear mental models.

Computer history legends like [Alan Kay](https://en.wikipedia.org/wiki/Alan_Kay) and [Seymour Paypert](https://en.wikipedia.org/wiki/Seymour_Papert) were the earliest champions of using intuitive visuals to teach programming. Paypert developed a language called [Logo](<https://en.wikipedia.org/wiki/Logo_(programming_language)>) in the late 1960's where you would type commands to direct a small green turtle around the screen, leaving a visible trail behind it. Through simple instructions like `go(20)` and `turn(90)` and `for i in range(12): go(20) turn(30)` you could draw elaborate graphic patterns. It became widely used in education and a whole generation began their programming lives in Logo.

<img
  width="500px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1622109247/maggieappleton.com/notes/learnable-programming/screenshot_eifk3w.png"
  alt="A classic example of a logo-based interface where you direct a small turtle around a canvas. Source: pythonturtle.org"
  showalt
/>

My own earliest memory of programming involved directing one of these small green amphibians around in circles. If you want a little throwback, you can play with a live Turtle environment at [Turtle Academy](https://turtleacademy.com/playground)

The modern manifestation of Logo is MIT's [Scratch](https://scratch.mit.edu/) learning platform. It expanded the character range beyond just turtles, offering everything from llamas to dancing starfish. It also gives you the syntax as drag-n-drop blocks which visually distinguish variables from loops, logic operations, events, and motion commands.

<ImageFrame
  width="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1400/v1622107452/maggieappleton.com/notes/learnable-programming/scratch_aqp3ts.png"
  alt="The scratch learning platform that allows you to construct clear visual chains of programming commands"
  showalt
/>

If we look past the campy, child-friendly aesthetics of Scratch, it's hard to argue this kind of visual interface isn't helpful. There is no need to memorise the syntax, it's easy to browse through the available commands, and the physical shape and color of each command limits makes clear where you can and can't put it. Hovering over operations shows you whether they're true or false and variables reveal their current value.

<BasicImage
  imageWidth="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1400/v1624617679/maggieappleton.com/notes/learnable-programming/scratch_symbols_shrink_gkiw5q.png"
  alt="A selection of the avaliable programming commands in Scratch"
  showalt
/>

I could wax lyrical about the genius of this approach for paragraphs but I'll spare you. The [autocomplete](https://code.visualstudio.com/docs/editor/intellisense), syntax highlighting, and linter systems in modern IDEs <Footnote idName={3}>IDE stands for integrated development environment. These are pimped out code editors that offer programmers a buffet a helpful tools like debuggers, git logs, and advanced search functionality. VSCode, WebStorm, and XCode are all popular IDEs</Footnote> get us close to this, but offer just enough freedom to still hang ourselves sometimes. You also need to know IDEs exist in the first place, and _then_ learn how to setup and effectively use one; a heady challenge in itself. Many beginners flail around in blank, unresponsive code files with no autocompletion, syntax snippets, or linters to assist them until someone lets them in on the industry secret (speaking from personal experience here).

---

## Principles of Learnable Programming

Let's circle back to Bret Victor and his concept of _learnable programming_. Bret outlined a set of principles he believed all programming environments should follow if they want their learners to make any headway. He argues a good environment should allow learners to:

1. **Read the vocabulary** of a language by making clear what each keyword and function does
2. **Follow the flow** of what happens at each stage in executing a programme
3. **See the state** as the programme changes variables over time
4. **Create by reacting** to how the programme behaves
5. **Create by abstracting** from the simple to the complex

Most of these are explicitly **visual**. We need to make what's happening in the programme _readable_ through visual representations of each syntax element, variable, and change of state over time. As Bret puts it:

> "People understand what they can see. If a programmer cannot see what a program is doing, she can't understand it."

I won't expand on these too much as Bret elaborates on them in the [original piece](http://worrydream.com/#!/LearnableProgramming) and provides plenty of tangible examples of how they might look in an interface. These principles amount to a kind of [[Pattern Language]] - they're a set of design rules that loosely define how a system should work, rather than a strict specification or implementation.

Since Bret wrote his piece in 2012, it's recieved plenty of buzz and cultish admiration (deservedly, IMHO). But I haven't seen it fully applied in any live learning platforms.

The world of programming education has certainly stepped up its visual game over the last decade. It's no longer just two column, text-based execution contexts. We're now swimming in interactive visual environments and gamified educational platforms.

I began researching the field to see how many of them were putting Bret's principles into practice. The examples I looked at ranged from full-on illustrated games to lightly animated sequences of text. As I explored, I started to notice design patterns beyond the principles Bret outlined.

While Bret defined a set of ideals for a hypothetical learning platform, I became more interested in finding patterns in what already exists. While we're a long way from achieving the '_ideal_' system, there's plenty of good design happening here and now.


What's wrong with linear, static programming mediums and how might we improve them?

Making Programming Visual, Spatial, and Learnable

<IntroParagraph>

There are some of us who believe digital life should be lived through a series of keyboard shortcuts. There is nothing quite as satisfying as making one quick keyboard gesture and watching a whole cascade of events unfold before you. This is the definition of programmatic magic.

</IntroParagraph>

I'm not just talking about vanilla hotkeys like `Cmd + S` or `Cmd + Q` that save a file or quit an application.

Any hotkey that triggers a single action like copying text to your clipboard is equally capable of performing multiple actions in quick succession; opening a specific set of files, launching multiple applications, pasting a pre-written string of text, playing a particular song in Spotify, starting a countdown timer, and arranging your desktop windows just the way you want them.

Anything you can manually do on your machine with your two hands can be wrapped up into a programmatic sequence and performed by the machine without you touching it.

These sequences are called **macros** and you don't need to know how to programme to create them. Programmatic plebs (like me) can build powerful automations without needing to write a bunch of BASH commands in the Terminal. <Footnote idName={1}>Programmers traditionally write macro scripts in a language like Bash or Python using the **Terminal** – an application you already have on your machine that allows you to control your computer with text-based commands.</Footnote>

<ImageFrame
  width="700px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1629467741/maggieappleton.com/notes/keyboard-maestro/bash-command_gjxdsh.png"
  alt="The exact kind of programming gibberish you will not be writing"
  showalt
/>

You do need a macro application with a user-friendly interface though. IMHO [Keyboard Maestro](https://www.keyboardmaestro.com/main/) is one of the best designed and easiest to use options.<Footnote idName={2}>Now is the time to diclose that Keyboard Maestro have not paid, bribed, or manipulated me to write this post, and the link above is not an affiliate link. Doing this is all my choice as a KM enthusiast.</Footnote> It's a Mac app (sorry Windows users) that allows you to visually compose small sequences of actions that you can easily trigger at any time.

<img
  width="900px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1629467242/maggieappleton.com/notes/keyboard-maestro/km-demo-1_shrink_ipykkq.png"
  alt="The Keyboard Maestro main window"
  showalt
/>

There are alternative (Windows-compatible) macro applications that can do similar things: [AutoHotKey](https://www.autohotkey.com/), [Automator](https://support.apple.com/en-gb/guide/automator/welcome/mac), and [Macro Recorder](https://www.macrorecorder.com/). However, I haven't personally used these and will only be singing the praises of Keyboard Maestro from here on out.

This isn't going to be a beginner's guide to using Keyboard Maestro (hereafter known as KM), so I suggest you take a look at this [YouTube playlist](https://www.youtube.com/watch?v=C-M2ECt9gIc&list=PLa0EpEatE4TIUSob_dkMuDP7MpPceth30) and this TutsPlus [article series](https://computers.tutsplus.com/tutorials/keyboard-maestro-i-introduction--cms-23415) if that's what you need. If you want to get extra intense about learning KM, David Sparks has created a very [comprehensive course](https://learn.macsparky.com/p/km) that covers everything under the macro sun. There is also an [official wiki](https://wiki.keyboardmaestro.com/doku.php) you can reference, but it throws you into the technical weeds a lot.

Rather than giving you I'm going to jump into the ways I use KM and the particular macros I find useful on a daily basis. By seeing some very tangible examples of what KM can do, perhaps you'll be intruiged and get ideas for what you might want to automate.

<Spacer size="small" />

## Workflow Macros

One of the most basic groups of macros I rely on are what I call _workflow macros._

<ComingSoon />

How to write macros without touching the terminal

Plebian Programming with Keyboard Maestro


<IntroParagraph>

Nature is flourishing down at my local Sainsbury's. The mineral water is natural. The unrefined cane sugar is natural. The low-fat Greek style yogurt is natural. The gluten-free buckwheat toasted muesli is natural. The anti-oxidising cranberry, chocolate, and coconut vegan protein bars are natural.

</IntroParagraph>

"Natural" has become both a ubiquitous and meaningless label on food packaging. This observation is nothing profound. Hundreds of op-ed authors have lamented the lack of governmental regulation stopping producers from putting "natural," "free-range," "wholegrain," "authentic," "superfood," and "organic" on their shiny cereal box of sugar puffs. We have all become comfortably jaded with the empty, hyperbolic language of our food. At least enough to not take it seriously.

But this is not a diatribe about food packaging. The bone I'm picking is not with the label on my chicken, but the chicken's supposed origin – **nature.**

At its core, nature defines the world without humans in it. It is everything that the birds, bacteria, forests, fish, and ocean currents do without our input. We consider it distinct and opposed to the expansion pack that humans brought to life; culture. We think of culture as everything humans layer on top of the natural world; the icing on the cosmic cake.

At least, this is one version of the mythological story; the one most of us accept as historical fact. Hominids sprang up in South Africa 80,000 years ago and began carving wooden digging sticks, smearing red ochre on one another, and threading long necklaces made from shards of ostrich eggs. While they were busy decorating, the cosmic fabric split and created a division. The world before the humans, and the world after. At least this is the story we, the humans, tell ourselves.

<ComingSoon />


Why there is nothing natural about the idea of 'nature'

Natureculture, Moral Purity, and Cultural Boundaries

A walkthrough of how I manage and tend Evergreen notes in Roam

Tending Evergreen Notes in Roam Research

<IntroParagraph>

In the story of Echo and Narcissus, a chatty mountain nymph and a self-obsessed hunter both die from unhealthy obsessions. Echo won't shut up, annoys the wrong goddess, and ends up cursed to repeat the words of others; she's unable to say anything original. She then falls in love with Narcissus, a pretty boy who spends his whole day staring at his reflection and is wholly unimpressed with the woman repeating everything he says. In the end, they both spend so much time staring at Narcissus they forget to eat, bathe, or sleep and slowly waste away.

</IntroParagraph>

<img src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_800/v1617971024/maggieappleton.com/notes/echo-narcissus/800px-John_William_Waterhouse_-_Echo_and_Narcissus_-_Google_Art_Project_zpecxl.jpg" />

This delightful story is a good reminder to eat regular snacks. It's also a fitting metaphor for one of the clubs I run at [Hyperlink Academy](https://hyperlink.academy/)

The [_Echo & Narcissus Writing Club_](https://hyperlink.academy/courses/echo-and-narcissus-writing-club/118) is all about mimicking the work of exceptional writers in order to learn from them.

This might sound scandalous depending on your understanding of creativity. I'm personally a subscriber to the [everything is a remix](https://vimeo.com/14912890) and [great artists steal](https://austinkleon.com/steal/) schools of thought.

I used to think copying was unseemly before one of my writing professors in college filled me in on the big, unkept secret. He handed us a small trove of writing samples from folks like [Joan Didion](https://en.wikipedia.org/wiki/Joan_Didion), [John McPhee](https://en.wikipedia.org/wiki/John_McPhee), [Barbara Kingsolver](https://en.wikipedia.org/wiki/Barbara_Kingsolver), and [Ernest Hemingway](https://en.wikipedia.org/wiki/Ernest_Hemingway). Essentially a Who's Who of New Yorker essayists. We had to copy out their work, then write our own pieces using the copied sentences as 'templates.'

You would take a Didion sentence like '_Only the very young and the very old may recount their dreams at breakfast, dwell upon self, interrupt with memories of beach picnics and favorite Liberty lawn dresses and the rainbow trout in a creek near Colorado Springs_,' and learn how to see it as "Only the **\_\_\_\_** and the **\_\_\_\_** may **\_\_\_\_**, **\_\_\_\_**, **\_\_\_\_** and **\_\_\_\_**." A reusable format for pointing out similarities between two distinct things.

The point is not to rip off Didion, but to begin to see how she uses nouns. Where she places verbs. How she handles semi-colons. Where she begins a story and where she ends it. How she asks a question. How she makes you doubt her credibility as a narrator.

Copying forces you to look at writing techniques under a microscope. You stop seeing your favourite authors as magical beings who pump out great work from behind a veil. Everything you need to know about their process and how to write like them is already on the page in front of you.

Great writers become great by closely studying and copying other great writers.
This is how cultural knowledge works. We learn the foundational skills from each other first, and then get all weird and experimental later on once the normal rules become boring.

<Spacer size="small" />

## Who This is For and What to Expect

If you have a writing practice of any kind, and feel the urge to improve it, this club is for you. You will need to bring along a Narcissus - a writer whose work you love and want to emulate. If you are bad at making choices, you can bring along two.

We keep it casual - the weekly meetings are to chat, compare what we've learned, and give each other feedback in pairs. There won't be lectures or lots of instruction. As a peer learning group, it's simply a way to gather together and support each other on our journey to being less-crap-writers.

It will require a commitment to write. The writing doesn't have to be good or profound or SEO-optimised. It simply needs to try and copy the style of your Narcissus.
We'll write 500 word pieces for the first 4 weeks, and 1000+ words in the final week.

It runs for **6 weeks** and **costs 35 USD**. I find a little skin in the game helps everyone show up on time. Committed folks make the experience better for everyone.

---

## Cohort 1

The first cohort of this club ran from **May 1st** to **June 6th 2021**.

We ended up with a wonderfully committed and insightful group of folks – something you don't always bank on with online learning groups.

Everyone came in with an active writing practice which I think made a significant difference. They already made time to write; publishing to personal blogs, newsletters, or ongoing fiction collections. The club simply directed that writing effort toward certain themes and assignments.

<Spacer size="small" />

#### Our Echos and Narcissus Pairs

[Daniel Miller](https://twitter.com/danielindustri4) echoed William Gibson  
[Jan Sondermann](https://twitter.com/jsoendermann) echoed Steven Pinker  
[Abe Kim](https://twitter.com/ich_bin_abe) echoed Colin Barrett  
[Catherine Woodiwiss](https://twitter.com/chwoodiwiss) echoed George Saunders  
[Dave Bernhard](https://twitter.com/daveforall) echoed Terry Pratchett  
[Keni](https://adagia.org/writer/13) echoed Scott Adams / Trevor Noah  
[Jonathan Yeong](https://twitter.com/JonoYeong) echoed Brandon Sanderson / Ed Yong  
[Shime](https://shime.sh/) and [Andrew Nalband](https://twitter.com/nalband) both echoed Paul Graham  
And I echoed Ursula K. LeGuin / Joan Didion



<Spacer size="small" />

#### Club Logistics

I wanted to run the club in a space where we could take open-ended notes, write individual essays, and leave comments on each other's work. I ended up using [Notion](https://notion.so) which worked great – it became the organising spot for agendas, weekly assignments, resources, and casual chatter:

<ImageFrame
  width="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1623137511/maggieappleton.com/notes/echo-narcissus/The_Echo_Narcissus_Writing_Club_shrink_yfymsh.png"
  alt="Screencapture of our Notion space listing weekly themes and links to other pages"
/>

We all posted our weekly writing to a central database in here. I then used Notion's fancy [linked databases and filtering](https://www.notion.so/Linked-databases-fb007e2798d04c57aee839ecf6ce450a) features to have the right assignments show up in each week's agenda. This made it easy to see everyone compiling notes, analysing texts, and writing over the course of the week.

Here's an example of what each weekly agenda looked like:

<ImageFrame
  width="1000px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1623138078/maggieappleton.com/notes/echo-narcissus/Week_4_-_Descriptions_and_Details_shrink_drzycw.png"
  alt="The agenda, writing pieces, and homework assignment for week 4 of the club"
/>

Notion worked great for this round. For future cohorts I might try running it on the new platform Hyperlink is building (aptly named _Hyperspace_) which is based around wiki-like shared documents.

If you're interested in joining a future cohort, you can sign up to be notified on the [Hyperlink club page](https://hyperlink.academy/courses/echo-and-narcissus-writing-club/118).

A Hyperlink Academy writing club where we mimic the work of others

The Echo & Narcissus Writing Club


> "What app is that?"

<IntroParagraph>

I get asked this question at least once a day on Twitter. People are always keen to hear what tools I use to make illustration. It's frankly daft it's taken me this long to just write a note about it rather than answering a thousand people individually.

</IntroParagraph>

## I'm a Promiscuous Polytooler

I use wide variety of different tools and apps for different kinds of visual creations. I'm not wedded to any one tool in particular – they all have their strengths and weaknesses.
I'll use whatever fits the task at hand and move work between them liberally.

Here's all the apps and hardware that might be involved in a particular creation...

<Tools>

<a href="https://www.adobe.com/products/photoshop.html" noStyling>

<BasicImage
  width="160px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1590318986/maggieappleton.com/notes/tools/photoshop.png"
/>
<h5>Adobe Photoshop</h5>

</a>

<a href="https://www.adobe.com/products/illustrator.html" noStyling>

<BasicImage
  width="160px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1590318986/maggieappleton.com/notes/tools/illustrator.png"
/>
<h5>Adobe Illustrator</h5>

</a>

<a href="https://procreate.art/" noStyling>

<BasicImage
  width="160px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1590318987/maggieappleton.com/notes/tools/procreate.png"
/>
<h5>Procreate</h5>

</a>

<a href="https://www.adobe.com/products/aftereffects.html" noStyling>

<BasicImage
  width="160px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1590318986/maggieappleton.com/notes/tools/ae.png"
/>
<h5>Adobe After Effects</h5>

</a>

<a href="https://www.figma.com/" noStyling>

<BasicImage
  width="160px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1590318987/maggieappleton.com/notes/tools/figma.png"
/>
<h5>Figma</h5>

</a>

</Tools>

<Hardware>

<a href="https://www.apple.com/macbook-pro/" noStyling>

<BasicImage
  width="460px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_420/v1590318986/maggieappleton.com/notes/tools/macbook.png"
/>
<h5>Macbook Pro 15" 2015</h5>

</a>

<a href="https://www.wacom.com/en-us/products/pen-displays/cintiq-22-hd" noStyling>

<BasicImage
  width="460px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_440/v1590318987/maggieappleton.com/notes/tools/wacom.png"
/>
<h5>Wacom 22HD Cintiq Tablet</h5>

</a>

<a href="https://www.apple.com/ipad-pro/" noStyling>

<BasicImage
  width="460px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_400/v1590318987/maggieappleton.com/notes/tools/ipad.png"
/>
<h5>iPad Pro 12.5" 2018</h5>

</a>

</Hardware>

<Subtext>
  None of these are affiliate links - I'm just pointing you to official sites
  for more context
</Subtext>

## Workflows

And here's a couple of my common workflows for different styles of illustrations and visuals...

### 1. Illustrated notes

Anything I make that has a painterly and loose hand-drawn feel was made in Procreate on the iPad or Photoshop on the Wacom Cintiq. Or probably a combination – it's easy to move files back and forth between the two and the tools they offer are very similar.

Illustrations like these...

<TwoColumn>

<BasicImage src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1621767637/maggieappleton.com/notes/tools/Photo_by_Maggie_Appleton_on_June_30_2019._htaur3.jpg" />

<BasicImage src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1621767975/maggieappleton.com/notes/tools/Unfathomable_Meat_wp_wge87m.png" />

</TwoColumn>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1621767505/maggieappleton.com/notes/tools/GitMistakes--large_shrink_qm96ik.png"
/>

Both of these applications allow you to draw in "raster" graphics, meaning you paint pixels onto a canvas. They require a decent level of hand-skills to make sure your lines aren't wobbly, although both applications have smoothing features to help with that.

When I'm in Procreate I use a small selection of brushes I've gathered over the years. It's hard for me to remember where they're all from, and I've customised the majority of them to suit my personal prefs. Most of them were originally from Max Ulichney's [MaxPacks](https://maxpacks.com/) brushes. I have the essentials set ($2), the painters set ($8), and the comics set ($15), and can vouch they're all great.

<ImageFrame
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1621764330/maggieappleton.com/notes/tools/IMG_74BF7CB1E720-1_xpci1a.jpg"
  alt="A screenshot of my iPad with Procreate open and my brushes panel displayed"
/>

I move these pieces to Photoshop if I want to work on a larger screen, or have accidentally enlarged the canvas to a 14000px wide sprawling set of sketches that Procreate can't open without crashing.

<ImageFrame
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1621764627/maggieappleton.com/notes/tools/PhotoshopSnap_bduk6w.png"
  alt="A screenshot of my Photoshop setup"
/>

### 2. Polished vector illustrations

Illustrations that look more "polished" are made primarily in Adobe Illustrator, with a touch of Photoshop at the end for lighting effects and texture.

Pieces like these...

<BasicImage
  alt=""
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1621768811/maggieappleton.com/notes/tools/Linearnotes_shrink_gwvih5.png"
/>

These illustrations are all vector-based, meaning we use mathematical curves to define their shapes, rather than painted pixels. Vectors are great for create hard, crisp edges and working with perfect geometric forms.

<ImageFrame
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1621769123/maggieappleton.com/notes/tools/gatsby-illustrator_l37kgv.png"
  alt="A screenshot of my Adobe Illustrator setup with one of my illustrations on the canvas"
/>

While I love vectors for laying down the foundation shapes of these, I'll move them over the Photoshop once they're 90% done to adjust the colors, add more subtlety to the lighting and shadows, and chuck a bit of texture on the top so they feel more tangible.


A guide to the apps and tools I use to create illustrations

What App is That?


<IntroParagraph>

Every major note-taking app on the market works one way: linearly, in text. [Notion](https://www.notion.so/), [Roam](https://roamresearch.com/), [Evernote](https://evernote.com/), [OneNote](https://www.onenote.com/), [Bear](https://bear.app/), [Obsidian](https://obsidian.md/). They are all centred around writing text documents that flow from left-to-right, then top-to-bottom; the way all text works in English. Even if they support other languages, you'd still write Arabic or Hebrew or Urdu linearly, just right-to-left.

</IntroParagraph>

You might say this is what defines a _note_; it is a chunk of written text, presented as a small piece of digital paper. It's pretending to be a real piece of paper, but without many of the features that make real paper useful. Like the ability make marks on it that are not simply words in a straight line.

<ImageFrame
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1621509754/maggieappleton.com/notes/linear-notes/linear-scrawl_shrink_juilyb.png"
  showalt
  alt="How it might look if we could draw into our notes without being confined to linear text"
  width="900px"
/>

I find it odd that few apps put sincere effort into becoming more paper-like. Most are too busy trying to become more _hyper_, in the _hyper_-text sense. They pride themselves on their multi-device compatibility, cloud synchronicity, and API integration automations. None of them question the central organising medium of linear text.

In this linear text-based ideology, images are second-class citizens. Illustrations, diagrams, graphics, photographs, doodles, drawings, and icons are visitors here.

You're welcome to pop them "inline", like a pseudo-text element that inconveniently isn't subscribing to the rules. But you're going to have to make your images elsewhere. This is a note-taking app, not a drawing app (we have to wonder when those became two separate things). You'll have to draw somewhere else. Probably on another device. Which you'll have to buy separately. And yes, it will be prohibitively expensive. Unless you've found a way to draw by tapping out lines with your keyboard.

If you're lucky, your particular note-taking app might let you change the size of this image. Good luck trying to place two images next to each other though. Multi-column layouts and horizontal movement are beyond our current note-taking capacities.

Physical space is our third-class citizen. Your notes are only allowed to move to the right and down. You cannot move left, upwards, diagonally, in front, behind, or past Go.

<HackyFormatting />

You cannot freely drag things around and place them wherever you like. That would make it too much like the real world, where we can place one sticky note to the left of another, place both above a small notecard, arrange these next to a book with sticky notes inside it, and pile it all on top a ripped out page from a notebook covered in haphazard scribbles and doodles, half of them upside-down.

One wonders how we haven't hung ourselves with this amount of spatial freedom.

So, who is to blame for our linear, textual predicament?

The designers who invented the paper-based desktop metaphor that haunts all modern interface design? The users who behave like blind, inconsiderate drunks when presented with any slightly novel note-taking system? The venture capitalists who exclusively fund these predictable apps? The entire educational system for its incessant focus on textual literacy over spatial and visual literacy?

Surely, Gutenberg has something to answer for.


What we lose when our digital notes remove the freedom to move

The Linear Oppression of Note-taking Apps


<IntroParagraph>

My [[Roam Garden]] is a place I spend between 2-4 hours puttering around in every day according to my <a href="https://www.rescuetime.com/">RescueTime</a> stats. <Footnote idName={1}>RescueTime only tracks the time you're actively focused on a single window, so this measurement has some limitations but sets a nice baseline</Footnote> If I'm staring into something for over twenty hours a week, it better look and
feel like beautiful home that fits my aesthetic tastes. As a maker of aesthetically pleasing things, I'm obviously biased towards the<a href="https://en.wikipedia.org/wiki/Aesthetic%E2%80%93usability_effect">
Aesthetic Usability Effect</a>.

</IntroParagraph>

<BasicImage
  showalt
  width="580px"
  alt="A bar graph of the hours I spend in Roam on a typical week"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_580/v1590188743/maggieappleton.com/notes/roamhours.png"
/>

In that spirit, I've gone all-out on customising the CSS that controls how my Roam looks.

I've used colors and font weight to distinguished internal from external links, added custom colors to particular page names, and shifted the contrast and spacing of elements to fit my own design aesthetic.

<ImageFrame
  width="1100px"
  alt="A screen capture of my visual styling system in Roam"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1720/v1590188713/maggieappleton.com/notes/roam_theme_maggie.png"
/>

## How to paint Roam your own colors

Luckily, this is all fairly easy to do. Roam has a built-in system for
customising how your database looks.

You first need to create a new page called `roam/css`.

<ImageFrame
  width="840px"
  alt="The roam search bar with roam/css entered"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_840/v1607173029/maggieappleton.com/notes/roam-garden/Screenshot_2020-12-05_at_12.47.43.png"
/>

Once there, create a new code block by typing `/code` and selecting the block option.

<ImageFrame
  width="840px"
  alt="Entering /code into the empty page"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_840/v1607173035/maggieappleton.com/notes/roam-garden/Screenshot_2020-12-05_at_12.48.46.png"
/>

Once the code block appears, set the language to `css` from the right-hand drop down menu.

<ImageFrame
  width="840px"
  alt="Selecting the code option from the code block dropdown menu"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1607173038/maggieappleton.com/notes/roam-garden/Screenshot_2020-12-05_at_12.48.56.png"
/>

You're now ready to start customising the CSS of your Roam. Any CSS you enter into this new code block will be applied across your whole database.

To test if it's working, type `h1.rm-title-display span { color: salmon;}` into the box.  
The title of your new page should change to a lovely shade of salmon.

<ImageFrame
  width="840px"
  alt="The page title changing to the color salmon"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1607173750/maggieappleton.com/notes/roam-garden/Screenshot_2020-12-05_at_13.09.01.png"
/>

<SimpleCard>

#### If you've not entirely sure what CSS is, or you've never written any, I strongly suggest you first work through this short course on Khan Academy

<ButtonLink href="https://www.khanacademy.org/computing/computer-programming/html-css/intro-to-css/pt/css-basics">
  Intro to CSS on Khan Academy
</ButtonLink>

It'll take 30 minutes and learning the basics will give you an enourmous
appreciation for how the web works (as well as how to control it for your own
benefit!). After that, check out <a href="https://developers.google.com/web/tools/chrome-devtools/css">
this Google guide</a> to how to look up CSS elements and selectors a live webpage.

</SimpleCard>

### Pre-made Roam Themes

For those of you entirely uninterested in learning CSS who just want to pop a pre-made theme in, Roam has a whole collection of [pre-made themes](https://roamresearch.com/#/app/help/page/fJRcVITNY) you can pick from.

Copy and paste any of them into your new `roam/css` page and the styles will be applied across your whole database

If you want to use my theme **Leyendecker**, the most up-to-date version is avaliable this [Github repo](https://github.com/theianjones/roam-research-themes/blob/master/leyendecker.css). There's a older version listed on the [Roam database](https://roamresearch.com/#/app/help/page/fJRcVITNY).

### Custom Styling Tags and Page Links

Another neat trick I love with CSS and Roam is creating specific styles for different page title and tags. <Footnote idName={3}>Shoutout to fellow Roam user <a href="https://malcolmocean.com/">Malcolm Ocean</a> who lobbied for this as an official feature of the Roam interface. I found out how to do it digging around in their impressively <a href="https://gist.github.com/malcolmocean/03d777a1c8f89be8c98e3d89d6821607">comprehensive CSS files</a></Footnote>. I have a little workflow taxonomy going that covers different kinds of output and the stages they flow through

<BasicImage
  width="880px"
  alt="A screencapture of my Roam database with various colored tags"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1457/v1590193543/maggieappleton.com/notes/datatags.png"
/>

We're able to do this because when we use the double bracket or add a # to create a page tag, Roam adds a new attribute to the HTML markup. If the page is made with a #, it adds a `data-tag` attribute. If it's made with double brackets Roam adds a `data-link-title` attribute

```html
<span data-tag="Ideas" class="rm-page-ref rm-page-ref-tag">
  #Ideas What if I learned how to chuck wood like a Chuck Norris woodchuck
  could?
</span>

<span data-link-title="Ideas" class="rm-page-ref">
  [ [Ideas] ] What if I learned how to chuck wood like a Chuck Norris woodchuck
  could?
</span>
```

We can then target both of those attributes with a CSS selector that looks like this:

```css
span.rm-page-ref[data-tag="Ideas"],
span[data-link-title^="Tweet"] .rm-page-ref {
  color: #fcb815;
  padding: 3px 4px;
  font-weight: 700;
  line-height: 1.4em;
}
```

The first selector, `span.rm-page-ref[data-tag="Ideas"]` changes any # link, and the second `span[data-link-title^="Tweet"] .rm-page-ref` selector changes any link made with [ [ brackets]]

It makes an enormous difference in your user experience to be able to quickly identify different block and note types through visual color association.

If you just want to grab the tag and page styles from my theme , scroll down to the bottom of my <a href="https://github.com/theianjones/roam-research-themes/blob/master/leyendecker.css">CSS theme file</a> to find them.

### Block Level Styling

Roam also allows you to style whole blocks based on tags. <Footnote idName={4}>[Cato Minor](https://twitter.com/catominor3?lang=en) originally wrote a script for doing this in JavaScript, but now it's native to Roam's CSS.</Footnote> In my database I use this heavily when taking book notes to visually distinguish between claims, responses, questions, and evidence.

To style an entire block, and all its child elements, we use:

```css
.roam-block-container[data-page-links*="Comment"] {
  // styles in here
}
```

To style only the child elements but not the parent, add `.rm-block-children` to the end use:

```css
.roam-block-container[data-page-links*="Comment"] .rm-block-children {
  // styles in here
}
```

To style just the block itself but none of the child elements, add `> div.rm-block-main` on:

```css
.roam-block-container[data-page-links*="Comment"] > div.rm-block-main {
  // styles in here
}
```

---

## Alternate Styling with Browser Plugins

If you don't want to use the native Roam CSS functionality, there's a way to apply custom CSS styles to any website using a browser plugin.

This is especially useful if you're part of a **multi-player** Roam where everyone has their own styling preferences. [Stylus](https://stylus-lang.com/) has extensions for both [Firefox](https://addons.mozilla.org/en-US/firefox/addon/stylus/) and [Chrome](https://chrome.google.com/webstore/detail/stylus/clngdbkpkpeebahjckkjfobafhncgmne?hl=en) that allow you to write your own CSS styles in a browser.

<ImageFrame
  width="980px"
  alt="A screen capture of the stylus interface"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1590188865/maggieappleton.com/notes/stylus.png"
/>

They also have <a href="https://github.com/openstyles/stylus/wiki/Editor">good documentation</a> that will walk you through how to use it.

It's good to note that this is not a Roam-specific hack. You can re-paint any webpage you like with a custom CSS styler (go to town on Craigslist!)


How to customise Roam Research with your own CSS themes

Painting Roam Research with Custom CSS


<IntroParagraph>

At the end of last year I got to attend <a href="https://medium.com/mozilla-festival/tagged/mozfest2019">MozFest</a> here in London. Mozilla events are consistently extraordinarily in their format and coordination level. It's a thousand-person unconference that actually works.

</IntroParagraph>

The only issue is immense FOMO as you try to pick between attending a roundtable discussion on gendered voice assistants, a panel on _The Algorithmic Gaze_, or a debate on _The Future of Disinformation_. You can browse through the overwhelming variety of sessions they ran <a href="https://public.zenkit.com/c/2RH604FcHf/schedule?v=LK9b3laIX&hide=workspaceLists">here.</a>

---

One of my favourite sessions was on **Data Unions and the Future of Data** with speakers from [Streamr](https://streamr.network/) and the [Open Data Institute](https://theodi.org/)

I hadn't encountered the concepts of [Data Unions](https://medium.com/streamrblog/what-are-data-unions-how-do-they-work-which-ones-can-i-use-887e67fb7716) and [Data Trusts](https://medium.com/@anoukruhaak/data-trusts-why-what-and-how-a8b53b53d34) before. While we're all acutely aware of the current economic-internet-clusterfuck where we seem to pay nothing for services, and invisibly hand over valuable data, you don't often hear reasonable solutions to the problem.

Other than some vague mumblings about blockchain that are swiftly followed up with an offer to buy into an ICO...

I'm broadly interested in the idea of what [[Local, Artisan Data Storage]] might look like.

I sketched out some notes during the session which should give you a general idea of the model. I can't speak to any of the technical aspects or feasibility of this, but the concept is intriguing.

<BasicImage
  width="1150px"
  alt="An illustrated note on how data unions might work"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1150/v1592296979/maggieappleton.com/notes/MozFest_DataUnion.png"
/>


Illustrated notes on how data unions work and what problems they might solve

Are Data Unions the Future of Data?


Notes (mostly to myself) on how the CSS <b>position</b> property works because I <i>constantly</i> forget. Specifically in relation to building [scrollytelling](https://medium.com/nightingale/from-storytelling-to-scrollytelling-a-short-introduction-and-beyond-fbda32066964) pieces.

Having control over where elements are positioned on a webpage is essential for building scrollytelling stories. We have to understand exactly how elements will behave within the layout, especially in relation to the scrollbar and viewport.

The `position` property determines where an element appears on the page. Sounds simple. But it also includes how an element relates to its parent element, the browser window, how it behaves on scroll, and whether placement properties like `top`, `right`, `bottom`, `left` and `z-index` will have any effect.

## **Position** can have six possible values

### 1. Static

`static` is the default value for elements. They stick to the normal page flow and placement properties (top, left, z-index, etc.) don't have any effect.

<Center>

<StaticCSSPosition />

</Center>

<Spacer />

### 2. Relative

`relative` keeps the element in the normal document flow, but allows us to use placement properties. This means we can move the element up, down, left or right, relative to where it would have been in the normal document flow.

For example, if we nudge this box `-10px` up, and `-10px` to the left, it moves to here:

<Center>

<RelativeCSSPosition />

</Center>

<Spacer size="small" />

In our CSS we would just need to declare a `relative` property on our box, then add `top` and `left` properties:

```css
.redBox {
  position: relative;
  top: -10px;
  left: -10px;
}
```

<Spacer />

### 3. Absolute

`absolute` removes the element from the normal document flow. It places itself on an absolute position relative to the whole document.

The position of the parent has no influence on where the child shows up. Placement values like `top` and `left` are calculated relative to the document.

Declaring `position: absolute`, `left: 10px` and `bottom: 20px` on this `.redBox` element would position it 10 pixels from the left and 10px from the bottom of the document.

<Center>

<AbsoluteCSSPosition />

</Center>

<Spacer />

#### **Relative Parents and Absolute children**

If you declare `position: relative` on the parent element, and `position: absolute` on the child, it now positions itself relative to the parent.

This is useful for creating overlapping elements.

<Spacer />

### 4. Fixed

`fixed` is similar to absolute, but sticks itself to the viewport rather than the document. Fixed elements don't move when you scroll down the page - they are always visible.

Fixed is useful for persistent elements like navigation bars or menus.

Declaring `position: fixed;`, `top: 10px;` and `right: 10px` on an element will position it 10 px from the top and right-hand side of the browser viewport. The rest of the document scrolls behind it.

<Center>

<FixedCSSPosition />

</Center>

<Spacer size="small" />

#### **Annoying Transform Quirk**

If any parent element has a `transform: translate()` property declared on it, `fixed` won't work.

<Spacer />

### 5. Sticky

`sticky` makes an element "stick" to the viewport when it reaches a certain point – usually when the top of the viewport hits the top of the element.

It behaves like a `relative` element until it hits the sticking point, and then becomes `fixed`.

For sticky to work, the parent element needs to have the `relative` property declared.

<Spacer />

### 6. Inherit

`inherit` forces an element to inherit the position property of its parent. This wouldn't otherwise happen as `position` doesn't flow down the cascade.

<References>
  <ReferencesLink
    title="Position: CSS Tricks Almanac"
    href="https://css-tricks.com/almanac/properties/p/position/"
    author="Chris Coyier"
  />
  <ReferencesLink
    title="Advanced Positioning Tutorial"
    href="https://www.internetingishard.com/html-and-css/advanced-positioning/"
    author="Internetting is Hard"
  />
  <ReferencesLink
    title="Easier Scrollytelling with Position Sticky"
    href="https://pudding.cool/process/scrollytelling-sticky/"
    author="The Pudding"
  />
</References>


Notes on how to use the position property in CSS to make scrollytelling stories

Positioning Elements & Scrollytelling in CSS


<IntroParagraph>

The idea of the **Cyborg** was born in 1960 in the thick of the US-Soviet Space Race, to two NASA consultants trying to solve the problem of keeping humans alive in the hostile conditions of outer space.

</IntroParagraph>

Nathan Kline and Manfred Clynes published a paper called '[Cyborgs and Space](http://www.guicolandia.net/files/expansao/Cyborgs_Space.pdf)' where they proposed that rather than trying to construct earth-like environments for humans to live in, we should try altering the humans themselves.

They imagined a _Cybernetic Organism_, or _Cyborg,_ that came with a built-in, self-regulating system that would take care of the bothersome issues of breathing, metabolism, sleep, circulation, and any other biological necessities, "leaving man free to explore, to create, to think, and to feel."

Creations often stray from their origins though.

The idea of the Cyborg has largely become a villainous character in science-fiction – used to explore the danger and discomfort we feel around our tools and systems. Let's just call this 'The Terminator Effect.'

Yet the idea has more philosophical promise and potential in it than Hollywood knows what to do with.

---

Anthropologist [Donna Haraway](https://en.wikipedia.org/wiki/Donna_Haraway) is a pioneer of using the term _Cyborg_ as an imaginative toy in her 1991 essay [The Cyborg Manifesto](/cyborg-manifesto). In Haraway’s writing, the Cyborg becomes a way to explore our cultural assumptions around the dividing lines between "nature" and "culture".

It offers us a chance to question the strict categories and historical boundaries _Western Cosmology_ <Footnote idName={1}>I use the term _Western Cosmology_ as a slightly tounge-in-cheek way of referencing the "_Western_" belief system.<br />Although we should acknowledge "_Western_" isn't really a thing, but can be interpreted as some generic mashup of [WERID](https://en.wikipedia.org/wiki/Psychology#WEIRD_bias), Euro-American, Judeo-Christian cultural ideals.<br />Language is flawed. I apologise for the sweeping generalisation.</Footnote> constructs for us. The firm divisions between humans / machines, natural / artificial, male / female, mind / body, fiction / reality, primitive / civilised, and science / society we are told most definitely exist. Despite the fact they are not in the least bit culturally universal.

Haraway’s insight is not only well ahead of her time, but also remarkably accurate as society now struggles to deal with technological relationships that contradict and question those historical divisions. They are all inherently tied to the issue of understanding where the line between organism and machine gets drawn. Or more accurately, the issue of there being a line at all.

---

Cognitive philosopher [Andy Clark](https://en.wikipedia.org/wiki/Andy_Clark) picked up on the idea of the Cyborg in his 2006 book [Natural-Born Cyborgs](/natural-born-cyborgs).


Notes on the history of cyborgs and why the idea still holds historical weight in Western narratives

A History of Cyborgs


<IntroParagraph>

As a [Digital Anthropology](/digital-anthropology) enthusiast and practioner-in-training, I'm often asked for reading recommendations that are are good entry points into the field. I've compiled a list of gateway drugs.

</IntroParagraph>

This is a collection of books, talks, documentaries, articles, and academic paper that are a mix of "essential reads," plus some of my personal picks.  
It will give you a sweeping overview of what digital anthropologists tend to spend their time thinking about and researching.

Most of them aren't overly academic, so you don't need to worry about trugding through too much Foucauldian theory or references to Marxist [reification](<https://en.wikipedia.org/wiki/Reification_(Marxism)>) (no promises though, sometimes it just comes out of left field).

<Center>

### Books

</Center>

<ResourceBook
  image="/images/books/addiction.jpg"
  title="Addiction By Design"
  author="Natasha Dow Schull"
  description=""
  url="/addiction-by-design"
>
  A beautiful ethnography of machine gamblers in Las Vegas. Dow Schull explores
  the nature of addictive relationships with machines, experiences of
  embodiment, and the ethics of designing technological systems.
</ResourceBook>

<ResourceBook
  image="/images/books/cyborg.jpg"
  title="A Cyborg Manifesto"
  subtitle="Science, Technology, and Socialist-Feminism"
  author="Donna Haraway"
  url="/cyborg-manifesto"
>
  While a bit academically dense to read, Haraway's reframing of the Cyborg is
  an eternal classic.
</ResourceBook>

<ResourceBook
  image="/images/books/comingofage.jpg"
  url="https://www.librarything.com/work/5284404"
  title="Coming of Age in Second Life"
  author="Tom Boellstroff"
>
  An ethnography conducted entirely within the virtual world of Second Life.
  This is widely considered the first substantial ethnography of an online
  community. Tom Boellstroff pioneered the idea digital spaces should be taken
  seriously as cultural fieldsites.
</ResourceBook>

<ResourceBook
  url="https://www.librarything.com/work/5642301"
  image="/images/books/twobits.jpg"
  title="Two Bits: the Cultural Significance of Free Software"
  author="Christopher Kelty"
/>

<ResourceBook
  image="/images/books/diviningdigital.jpg"
  url="https://www.librarything.com/work/10840289"
  title="Divining a Digital Future"
  author="Genevieve Bell & Paul Dourish"
/>

<ResourceBook
  url="https://www.librarything.com/work/13246426"
  image="/images/books/codingfreedom.jpg"
  title="Coding Freedom: The Ethics and Aesthetics of Hacking"
  author="Gabriella Coleman"
/>

<Center>

### Talks & Documentaries

</Center>

<TwoColumn alignItems="flex-start" maxWidth="1000px">

<LinkCard url="https://www.youtube.com/watch?v=GQw02-me0W4" title="Our Digital Selves: My Avatar is Me" author="Tom Boellstorff & Donna Davis">

A documentary that follows the research of Tom Boellstorff & Donna Davis on
embodiment in the virtual world of Second Life

</LinkCard>

<LinkCard url="https://www.youtube.com/watch?v=5aKZwKFFDYw" title="Magical Thinking: Fear, Wonder & Technology" author="Genevieve Bell">

Genevieve Bell presenting at Stanford on the mythological narratives we tell around technical systems

</LinkCard>

</TwoColumn>

<Center>

### Papers & Articles

</Center>

<TwoColumn alignItems="flex-start" maxWidth="1000px">

<LinkCard
  url="https://www.brown.edu/Departments/Joukowsky_Institute/courses/materialworlds/files/1108595.pdf"
  title="The Technology of Enchantment and the Enchantment of Technology"
  author="Alfred Gell"
/>

<LinkCard
  url="https://journals.sagepub.com/doi/full/10.1177/2053951717738104"
  title="Algorithms as Culture"
  author="Nick Seaver"
/>

</TwoColumn>


A few favourite books from the field of digital anthropology

A Digital Anthropology Reading List


<IntroParagraph>

Using the [GreenSock](https://greensock.com/) web animation library (also known as gsap) in vanilla JavaScript isn't too complex. But when we want it to play nicely with a frontend framework like React, we run into some finicky issues.

</IntroParagraph>

This guide is specifically about using React Hooks with GreenSock, as many of the [existing guides](https://greensock.com/react/) only explain how to set it up with the old style of class components.

This isn't an introduction to the GreenSock library itself – head over to my post on [[The Bare Essentials of Greensock]] for that.

<br />

## React, Meet GreenSock

The issue with combining these two libraries is that React acts as a DOM interloper – it sits between the code we write and the DOM, managing it for us.

React builds it's own internal "tree" of DOM nodes based off our code, and only updates the actual DOM as needed (a concept previously known as the [[React Virtual DOM]]) <Footnote idName={1}>The React team has gone off the term of the _virtual DOM_ and prefer to talk about the _render tree_. Potatoes, potataos. For more on how the virtual DOM works, I have an [illustrated guide](/react-vdom)</Footnote>

<BasicImage
  alt="A diagram of React generating all the DOM nodes for us"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1400/v1600973172/maggieappleton.com/notes/gsap/react-greensock-2.png"
/>

Meanwhile, the GreenSock library usually works by directly animating our DOM elements. Perhaps you can sense the tension in the room...

Since the GreenSock library needs access to the DOM in order to animate it, we need to tell React about our Greensock animations. Otherwise the two end up in awkward arguments that can end in tears (primarily mine).

## Bring in the React Hooks

There's two essential React hooks we'll use to connect our React code to our Greensock code: **useRef** and **useEffect**

<SimpleCard>

**useRef** lets us access and directly target our DOM nodes

**useEffect** lets us to perform side effects – any functions or data requests that we want to run _after_ rendering the component to the DOM

</SimpleCard>

If you're not completely comfortable with [React Hooks](https://www.freecodecamp.org/news/beginners-guide-to-using-react-hooks/) yet and those technical explanations mean nothing to you, don't worry we're going to slowly walk through this. With illustrations. Because who the fork properly understands _"side effects"_?

---

### Getting Setup

We first need to run `yarn install gsap` or `npm install gsap` into our React project repo <Footnote idName={2}>**gsap** is short for _GreenSock Animation Platform_ and it's the way we reference the Greensock library in all our code sytax</Footnote>

<SimpleCard>

Feel free to open up a Codesandbox project to work through the steps while you read. I've set one up for you with React and Greensock already installed:

<ButtonLink href="https://codesandbox.io/s/reacthooks-greensock-demo-xjoti?file=/src/AnimatedBox.js">
  Jump into CodeSandbox
</ButtonLink>

</SimpleCard>

<br />

### Building our Animation Component

Let's start by creating a React component called `<AnimatedBox/>` that is going to hold all our Greensock code. We're going to build a simple `<div>` element and have it animate across the page (exciting!).

We'll need to import the Greensock library into our component with `import { gsap }from 'gsap'`, as well as React and our two hooks with `import React, { useRef, useEffect } from 'react'`

```js
import React, { useRef, useEffect } from "react";
import { gsap } from "gsap";

const Animation = () => {
  return (
    <div
      style={{
        width: "160px",
        height: "160px",
        background: "salmon",
      }}
    />
  );
};
```

I've set some basic width, height, and color CSS styles on our div to make
it visible on the page.

<p>
  <div
    style={{
      margin: "2em auto",
      width: "120px",
      height: "120px",
      background: "salmon",
      borderRadius: "4px",
    }}
  />
</p>

<Center>

Good looking div, right? Salmon is always the right color choice.

</Center>

---

## Adding the useRef Hook

We're now going to add _references_ to our animation with the **useRef** hook.

We create a new reference by adding `const boxRef = useRef()` anywhere outside of our return statement. Call it anything you like, but _boxRef_ is a good enough name for this example.

We then add a `ref={boxRef}` attribute on our `<div>` element.

```js
const Animation = () => {
  const boxRef = useRef();

  return (
    <div
      ref={boxRef}
      style={{
        width: "120px",
        height: "120px",
        background: "salmon",
      }}
    />
  );
};
```

This tells React we want to be able to control our `<div>` element with the `boxRef` reference once our component is mounted onto the DOM.

---

## Adding the useEffect Hook

Next we're going to add our **useEffect** hook, and write our GreenSock animation inside of it.

If you're already familiar with greensock this will look fairly straightforward.

```js
const Animation = () => {
  const boxRef = useRef();

  useEffect(() => {
    gsap.to([boxRef.current], {
      x: "400px",
      duration: 2,
    });
  });

  return (
    <div
      ref={boxRef}
      style={{
        width: "120px",
        height: "120px",
        background: "salmon",
      }}
    />
  );
};
```

We declare a normal `gsap.to()` tween, but instead of passing in an id or class name as the target element, we use `[boxRef.current]`.

This means we want gsap to animate the `.current` property of our `boxRef` reference – which is the `<div>` element we put that reference on.

```js
gsap.to([boxRef.current], {});
```

We then pass in our variables object, which tells Greensock to move our div 400px along the _x_ axis over a duration of 2 seconds:

```js
{ x: 400px, duration: 2 }
```

And thus, our div animates...

<p>

<Tween
  to={{
    scrollTrigger: {
      trigger: "#boxRef",
      start: "top 60%",
      end: "+=500",
      scrub: true,
    },
    x: "400%",
  }}
  duration={2}
  ease="back.out(1.3)"
>
  <div
    id="boxRef"
    style={{
      margin: "2em",
      width: "120px",
      height: "120px",
      background: "salmon",
      borderRadius: "4px",
    }}
  />
</Tween>

</p>

<Center>

# Tada <span>🎉</span>

</Center>

So by this point, you hopefully have a working animation in that [Codesandbox project](https://codesandbox.io/s/reacthooks-greensock-demo-xjoti?file=/src/AnimatedBox.js) or a local repo.

---

If you don't feel like mucking around with **useRef** and **useEffect**, [John Lindquist](https://johnlindquist.com/use-greensock-with-react-hooks/) created a simple React hook called **use-gsap** that hides them away.


How to use the Greensock animation library inside React using React hooks

GreenSock Animations with React Hooks


_"Drawing the Invisible: React Explained in Five Visual Metaphors"_ is one of my conference talks about the importance of visual metaphors in explaining programming concepts.

It's perhaps also known as the **'React is a Potato'** talk. Due to the fact potatoes make a rather bold appearance in the middle. <span>🥔</span><span>🥔</span><span>🥔</span>

Here's the debut version of it from the [Women of React](https://womenofreact.com/) Conference in 2020

<Video src="https://www.youtube.com/embed/MQGe9zxlRdk" />

<Spacer size="small" />

I've since recorded an expanded version you can [watch on egghead](https://egghead.io/talks/javascript-drawing-the-invisible-react-explained-in-five-visual-metaphors/).

<Center>

# The Slides

</Center>

<BasicImage
  width="900px"
  alt=""
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532709/maggieappleton.com/notes/react-potato-slides/react-metaphors01.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532728/maggieappleton.com/notes/react-potato-slides/react-metaphors12.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532757/maggieappleton.com/notes/react-potato-slides/react-metaphors18.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532760/maggieappleton.com/notes/react-potato-slides/react-metaphors19.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532792/maggieappleton.com/notes/react-potato-slides/react-metaphors26.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532801/maggieappleton.com/notes/react-potato-slides/react-metaphors29.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532815/maggieappleton.com/notes/react-potato-slides/react-metaphors34.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593532817/maggieappleton.com/notes/react-potato-slides/react-metaphors35.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537413/maggieappleton.com/notes/react-potato-slides/react-metaphors42.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537417/maggieappleton.com/notes/react-potato-slides/react-metaphors43.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537425/maggieappleton.com/notes/react-potato-slides/react-metaphors47.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537443/maggieappleton.com/notes/react-potato-slides/react-metaphors54.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537448/maggieappleton.com/notes/react-potato-slides/react-metaphors58.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537452/maggieappleton.com/notes/react-potato-slides/react-metaphors57.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537463/maggieappleton.com/notes/react-potato-slides/react-metaphors62.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537471/maggieappleton.com/notes/react-potato-slides/react-metaphors69.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537485/maggieappleton.com/notes/react-potato-slides/react-metaphors71.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537481/maggieappleton.com/notes/react-potato-slides/react-metaphors73.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537479/maggieappleton.com/notes/react-potato-slides/react-metaphors75.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537490/maggieappleton.com/notes/react-potato-slides/react-metaphors77.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537499/maggieappleton.com/notes/react-potato-slides/react-metaphors79.png"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1593537502/maggieappleton.com/notes/react-potato-slides/react-metaphors80.png"
/>


The written version of my talk on explaining React through visual metaphors

Drawing the Invisible: React Explained in Five Visual Metaphors


<IntroParagraph>

When it comes to web animation libraries, [Greensock](https://greensock.com/) is the Rolls Royce of options. It's what powers most of those ridiculously fancy [Awwwards](https://www.awwwards.com/) websites.

</IntroParagraph>

<p>It's also been on my learning wish list for too long. I assumed it would be too complex. Everyone talks about how powerful the library is.

It's usually safe to assume powerful === complex.

But once I started digging in I realised the core of the library was actually quite easy to get the hang of. There's plenty of advanced mechanisms and complexity to get wrapped up in if you want to. But they're entirely optional.

This is a **one-scoop-plain-vanilla introduction to Greensock**.  
Without any sprinkles, nuts, or advanced functionality.</p>

<GsapScroller />

<h3>Tweens</h3>

<p>
Tweens are the basic building blocks of a Greensock animation. A tween is a single transition – an element changing from state A to state B.

To create a tween, we target an _element_ (this can be any HTML element like a `<div>, <p>, or <svg>`) and pass in _variables_.
Variables define how the element should change over the course of the animation - whether it should move, change opacity or color, grow big or small – you get it.

Let's say we want to make a box go from navy blue to red, move 40% of the way across the screen <Footnote id={1}>I've used `40vw` units in this example which tells the browser to calculate 40% of the **view width**. `vw` is a handy unit for responsive design to make this work on little screens as well as big</Footnote> on the X axis (horizontal), and grow in scale by 1.4 times the original:

</p>

<Center>

<TweenRedBigBox />

</Center>

Here's the code to do that in Greensock:

```js
<div class="giantRedBox" background="navyblue" width="100px" height="100px" />;

gsap.to(".giantRedBox", 2, { x: 40vw, scale: 1.4, background: "red" });
```

<p>

First we target the element using it's classname: `giantRedBox`.  
We then pass in a _duration_ that defines how long it should take the animation to move from state A to state B – here it's 2 seconds.  
Finally we pass in an object that contains our animation _variables_:  
`{ x: 40vw, scale: 1.4, background: 'red' }`

</p>

---

### Types of Tweens

There's three types of tweens:

<ul>
  <li>to</li>
  <li>from</li>
  <li>fromTo</li>
</ul>

In _to_ we define the final state of the animation – what it looks like by the end.
It begins in the position defined in our HTML & CSS, and moves _to_ the state we define inside our greensock tween.

```js
<div class="spinningBox" background="navyblue" width="100px" height="100px" />;

gsap.to(".spinningBox", 3, { x: 40vw, rotation: 360 });
```

<Center>

<TweenSpinningBox />

</Center>

<Spacer />

In _from_ we define the beginning state of the animation, and it moves back to it's state defined in the HTML & CSS

```js
gsap.from(".reverseSpinningBox", 3, { x: 40vw, rotation: 360 });
```

<Center>

<TweenReverseSpinningBox />

</Center>

<Spacer />

In _fromTo_ we declare two states we want the animation to move between.

```js
gsap.fromTo(".hotBox", 3, { background: "#93D0D9" }, { background: "#D93654" });
```

<Center>

<TweenBlueRedBox />

</Center>

---

### Timelines

Timelines are made up of tweens.
They group them together into a sequence.

Once we declare a timeline, we can chain sets of tweens onto it.

```js
const boxTimeline = gsap.timeline();

boxTimeline
  .to(".flyingBox", 2, { x: 100, scale: 1.5 })
  .to(".floatingBox", 3, { x: 10 })
  .to(".flippingBox", 1, { rotation: 360 });
```

---

You may see references around to multiple varieties of tweening and timelines called `TweenMax`, `TweenLite`, `TimelineMax`, and `TimelineLite`.

In late 2019 GSAP [updated to version 3](https://greensock.com/3-release-notes) and got rid of the all lite / max varieties so feel free to ignore that distinction in older code examples or.

<br />


Notes on the basics of the Greensock animation llibrary

The Bare Essentials of Greensock


A gift economy is a _system of exchange_ based on gift giving.

Valuables are given without explicit agreement of future rewards between individuals, or within a contained community of people.

<BasicImage
  width="880px"
  alt="Gift economies are systems of exchange based on gift-giving"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1589328834/maggieappleton.com/notes/gift-economy.jpg"
/>

Gift economies have a few key qualities. They are...

1. **Loosely and informally tracked** - it is bad form to calculate the exact value of gifts you receive, or keep an obsessive log of it the way we do with business finances
2. **Indirect** - it is not always two individuals giving back and forth. Instead gifting is generalised to a whole community where you may give to people who have not given directly to you
3. **Delayed** - we do not reciprocate gifts the minute we receive them, but instead wait to repay the offering at a later date

The emphasis in a gift exchange is on **strengthening the bond between the givers and receivers.**

It creates a kind of "positive debt," where two people or groups are now tied to one another - one party will always owe the other something. It's a purposeful way of entwining lives and communities together.

## Why do we feel compelled to reciprocate gifts?

The grand mystery of gifting and gift economies is why we feel _obliged_ to reciprocate. When someone gives you something, it sparks a strong desire to return in kind.

We don't have a pat answer to where this compulsion comes from, but we can certainly argue generosity and social connection are useful evolutionary traits if we want to get biologically reductive about it.

[Marcel Mauss](https://en.wikipedia.org/wiki/Marcel_Mauss) is perhaps the most infamous Anthropologist to explore this question in his book [The Gift](https://www.librarything.com/work/69346) <Footnote idName={1}>Not to be mistaken with [Lewis Hyde's book](https://www.librarything.com/work/258760) of the same name, although it's more focused on art and creation as a gift. Not a bad read, but a bit of a title hijack.</Footnote>

<br />

<ResourceBook
  url="https://www.goodreads.com/book/show/201766.The_Gift"
  image="/images/books/gift.jpg"
  title="The Gift"
  author="Marcell Mauss"
>
  An anthropological classic on gift theory and gift economies. Published in
  1923, Marcel Mauss explores how systems of exchange work in traditional
  societies around the world in relation to politics, power, and kinship.
</ResourceBook>

Mauss concluded that the objects we are given _"are seen to partake of something of the personality of the giver"_. 154

Mauss described it through the idea of the Maori idea of **hau** - the "spirit of the gift" where the giver's 'soul', or some kind of personal quality, is entangled with the gift object that wishes to return home to its owner. Thus compelling the receiver to make a return.

This interpretation of Maori **hau** ended up being strongly criticised as a misunderstanding and vast oversimplification of the true cultural meaning.

But the deeper idea Mauss was trying to get at is still worth highlighting. Just without a culturally appropriated term.

## Reciprocating Appropriately

When we return a gift, our offering has to be of **similar or slightly higher value** than the original. But not by too much.

If you bring me a ginger biscuit with my cup of tea, and two days later I reciprocate with a gourmet, two-tiered red velvet cake with your name in icing, we would all consider that an awkward, creepy, and overall a socially inappropriate response.

Just giving you a ginger biscuit back works well enough. Returning a gift of the exact same value resolves the debt, but also breaks the cycle.

Everyone is now even, and there’s no more need to continue biscuit-gifting. We can safely return to the pre-biscuit-gifting-days, but doing so also weakens our social connection.

If I have a particular political or personal interest in strengthening our social relationship, I need to give you a treat of slightly higher value – perhaps a chocolate hobnob or home-made scone.

Which both demonstrates I'm invested in this relationship, and also leaves you slightly indebted to me, thus compelling the gift cycle onwards.

## Gift Economies and Market Economies

We often contrast the Gift Economy with the Market Economy. This is a wild oversimplification, but humans like to think in Cultural Dichotomies.

<BasicImage
  width="840px"
  alt="We often contrast gift economies with market or barter economies"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1596572154/maggieappleton.com/notes/market-barter-economy.png"
/>

Market Economies are _systems of exchange based on buying and selling things with money_. A market exchange is **specific, quantifiable, direct, immediate, founded upon an explicit agreement**. As in, this croissant costs £1 right now.

Buying an irrationally overpriced granola bar from an airport vending machine is an example of a pure market exchange without a social layer. It’s me, a machine, and a £3 bar of sugar to help me survive this long layover.

I want food, and whoever owns this machine wants money. This is not the time or the place for a gift economy. It would be terribly inconvenient for me to rely on an unpredictable system of granola bar gifts from the strangers around me while starving in an unfamiliar airport.

There are humans who own this vending machine, who will eventually get that money. But they are very far away in time and space – both geographically and socially.

If challenged, I would have a terrible time tracking them down and having a chat. I have only the weakest sense of a human relationship with them, and there is hardly a social bond being woven – this granola bar is about an immediate and specific exchange of needs.

Here, the market economy works wonders. Life necessities like food, shelter, and water are not good candidates for a gifting system. Which is why we tend to gift luxury items, novelties, and socks.

This is also why it's problematic when food, shelter, and water are framed as "gifts" which is sometimes how charitable donations work – as _optional_ acts of generosity.


Illustrated notes on the idea of Gift Economies and cultural historys of economic exchange

The Gift Economy


<IntroParagraph>

We all know the "head the family" is not just referring to a floating human head, but instead the entire person who holds the power in a family unit. It's a shorthand way of giving us something small, specific, and often visible to refer to, especially when the whole concept is a more abstract.

</IntroParagraph>

> Using part of something to refer to the larger whole is called **Synecdoche**

We refer to a collection of businessmen as **suits**.  
For politicians who run a national government we use the physical places they meet like **Parliament**, or **Number 10**, or **the White House**.  
To tell someone we like their car we say that's a nice **set of wheels**.  
We might ask for **a hand** carrying in the groceries, when we really need a whole human to come help out.

We pick physical symbols like bits of clothing, buildings, limbs, or locations to give us a tangible reference point for a less tangible group of people or an idea.

Synecdoche is especially important in creating Visual Explanations and Visual Metaphors, as it allows us to reference non-physical concepts in visible, physical symbols we can draw.

It's an offshoot of **Metonymy** - when we refer to one concept using a different but related symbol.


Notes on the metaphorical varieties of synecdoche and metonymy

Synecdoche: Drawing the Part for the Whole


<IntroParagraph>

In September of 2019 I went through the [Building a Second Brain](https://www.buildingasecondbrain.com/) course<Footnote idName={1}>And took illustrated notes that you can take a look at [here](/basb)</Footnote> – an enormously popular online guide to improving your "_Personal Knowledge Management_" system.<Footnote idName={2}>Or PKM as it's commonly known, is a novel name for an old concept. The art of filtering, curating, and cultivating what you read and encounter. And then being able to turn it into "useful output" of some variety. </Footnote> The course did wonders for my information streams and note taking organisation, but the core ethos left me with questions.

</IntroParagraph>

> What does it mean to build a "second brain," and why do we think that's a **Good** and **Valuable** thing to do?

What strange historical and cultural paths led us to this cerebral cyborgian dream?

Many of these questions and themes align with concepts I explored in [[Tracking Humanity]] - my anthropology thesis on the Quantified Self movement.

Luckily I have a small community of fellow BASB enthusiasts here in London to explore these questions with.  
At our March 2020 meetup I put together a lightning talk exploring how Second Braining relates to our notions of cyborgs, our embodied experiences, and the historical legacies that landed us here.

<Center>

## The Talk

<Video
  src="https://www.youtube.com/embed/yOGi9RfC3Eg"
  title="How to be a neo-cartesian cyborg talk"
/>

## Slides and Notes

</Center>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548502/maggieappleton.com/notes/neocyborgs/cyborgs_19.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548503/maggieappleton.com/notes/neocyborgs/cyborgs_20.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548501/maggieappleton.com/notes/neocyborgs/cyborgs_13.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548500/maggieappleton.com/notes/neocyborgs/cyborgs_11.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548502/maggieappleton.com/notes/neocyborgs/cyborgs_14.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548499/maggieappleton.com/notes/neocyborgs/cyborgs_4.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548499/maggieappleton.com/notes/neocyborgs/cyborgs_5.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548499/maggieappleton.com/notes/neocyborgs/cyborgs_6.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548500/maggieappleton.com/notes/neocyborgs/cyborgs_8.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548500/maggieappleton.com/notes/neocyborgs/cyborgs_7.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548498/maggieappleton.com/notes/neocyborgs/cyborgs_2.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548499/maggieappleton.com/notes/neocyborgs/cyborgs_3.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548500/maggieappleton.com/notes/neocyborgs/cyborgs_9.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548502/maggieappleton.com/notes/neocyborgs/cyborgs_18.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548500/maggieappleton.com/notes/neocyborgs/cyborgs_10.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548508/maggieappleton.com/notes/neocyborgs/cyborgs_39.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548508/maggieappleton.com/notes/neocyborgs/cyborgs_40.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548502/maggieappleton.com/notes/neocyborgs/cyborgs_16.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548502/maggieappleton.com/notes/neocyborgs/cyborgs_15.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548507/maggieappleton.com/notes/neocyborgs/cyborgs_37.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548508/maggieappleton.com/notes/neocyborgs/cyborgs_41.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548505/maggieappleton.com/notes/neocyborgs/cyborgs_30.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548503/maggieappleton.com/notes/neocyborgs/cyborgs_24.jpg"
/>

<img
  alt=""
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548504/maggieappleton.com/notes/neocyborgs/cyborgs_25.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548504/maggieappleton.com/notes/neocyborgs/cyborgs_26.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548505/maggieappleton.com/notes/neocyborgs/cyborgs_31.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548499/maggieappleton.com/notes/neocyborgs/cyborgs_1.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548508/maggieappleton.com/notes/neocyborgs/cyborgs_42.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548509/maggieappleton.com/notes/neocyborgs/cyborgs_43.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548505/maggieappleton.com/notes/neocyborgs/cyborgs_27.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548503/maggieappleton.com/notes/neocyborgs/cyborgs_23.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548503/maggieappleton.com/notes/neocyborgs/cyborgs_22.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548503/maggieappleton.com/notes/neocyborgs/cyborgs_21.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548507/maggieappleton.com/notes/neocyborgs/cyborgs_38.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548509/maggieappleton.com/notes/neocyborgs/cyborgs_44.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548505/maggieappleton.com/notes/neocyborgs/cyborgs_29.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548506/maggieappleton.com/notes/neocyborgs/cyborgs_34.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548506/maggieappleton.com/notes/neocyborgs/cyborgs_33.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548506/maggieappleton.com/notes/neocyborgs/cyborgs_35.jpg"
/>

<img
  alt="Slides from my talk on becoming a neo cartesian cyborg"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_960/v1594548506/maggieappleton.com/notes/neocyborgs/cyborgs_36.jpg"
/>

<Center>

## Books Mentioned in the Talk

</Center>

<ResourceBook
  url="https://www.librarything.com/work/68400"
  image="/images/books/naturalcyborgs.jpg"
  title="Natural-Born Cyborgs"
  author="Andy Clark"
>
  Philosopher and cognitive scientist Andy Clark proposes that what makes humans
  so different from other species is our capacity to fully incorporate tools and
  supporting cultural practices into our existence.
</ResourceBook>

<ResourceBook
  url="/descarteserror"
  image="/images/books/descarteserror.jpg"
  title="Descartes Error: Emotion, Reason, and the Human Brain"
  author="Antonio Damasio"
>
  Through a series of neuroscience case studies, Antonio Damasio challenges
  traditional ideas about the connection between emotions and rationality.
  Damasio shows that emotions are not a luxury, but an essential part of
  rational thinking and normal social behaviour.
</ResourceBook>

<ResourceBook
  url="https://www.librarything.com/work/63333"
  image="/images/books/mwlb.jpg"
  title="Metaphors We Live By"
  author="George Lakoff & Mark Johnson"
>
  The now-classic Metaphors We Live By changed our understanding of metaphor and
  its role in language and the mind. Lakoff and Johnson argue that metaphor is a
  fundamental mechanism of mind, one that allows us to map our physical and
  social experiences onto countless other subjects.
</ResourceBook>

<ResourceBook
  url="https://www.librarything.com/work/45956"
  image="/images/books/flesh.jpeg"
  title="Philosophy in the Flesh"
  author="George Lakoff & Mark Johnson"
>
  Lakoff and Johnson philosophically examine our historical understanding of
  minds, bodies, and reasoning through a radically new and detailed
  understandings of modern cognitive science. They re-examine the basic concepts
  of the mind, time, causation, morality, and the self.
</ResourceBook>


A lightening talk I gave on second brains and cyborg embodiment

How to Become a Neo-Cartesian Cyborg


<IntroParagraph>

A[ndy Matuschak](https://andymatuschak.org/) proposed the term [Evergreen Notes](https://notes.andymatuschak.org/z4SDCZQeRo4xFEQ8H4qrSqd68ucpgE6LU155C) to describe a system of note-taking that aspires towards cumulative personal knowledge, rather than simply information capture.

</IntroParagraph>

<BasicImage
  width="1000px"
  alt="Evergreen notes are a fundamental unit of knowledge work. They're a way to build up a personal library of clear opinions, beliefs, and original thoughts."
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1200/v1626013083/maggieappleton.com/notes/evergreen-notes/Evergreen_Notes_03_cyjnrl_shrink_urtoqe.png"
/>

The idea builds off many other note-taking philosophies like Niklas Luhmann's [Zettelkasten](https://en.wikipedia.org/wiki/Zettelkasten) method <Footnote idName={1}>Andy also wrote a good post [Comparing Evergreens vs Zettles](https://notes.andymatuschak.org/z4AX7pHAu5uUfmrq4K4zig9x8jmmF62XgaMXm)</Footnote>, and Sonke Ahren's [How to Take Smart Notes](https://www.librarything.com/work/21425376) system.

My personal notes system has been heavily influenced by the Evergreening ethos. In both my [[Roam Garden]] and on this very [[Digital Gardening]] website. My notes taxonomy flows from "Seedlings" to "Budding" to "Evergreens"

To help myself internalise some of the main Evergreen principles, I illustrated them out below. <Footnote idName={2}>These aren't a comprehensive explanation, so I recommend reading the [original source material](https://notes.andymatuschak.org/z4SDCZQeRo4xFEQ8H4qrSqd68ucpgE6LU155C) if this piques your interest.</Footnote>

<br />

<Center>

## Evergreen Notes Should Be...

</Center>

<BasicImage
  width="750px"
  alt="Atomic notes should capture one single idea concisely and in its entirety"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_900/v1626013083/maggieappleton.com/notes/evergreen-notes/Evergreen_Notes_13_ecugdv_shrink_o8p6pr.png"
/>

<BasicImage
  width="750px"
  alt="Densely-linked notes help you connect them through organic associations rather than heirarchical structures"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_900/v1626013083/maggieappleton.com/notes/evergreen-notes/Evergreen_Notes_05_bz2g7l_shrink_nlx03o.png"
/>

<BasicImage
  width="850px"
  alt="Notes should have imperative and declarative titles that make clear statements"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1000/v1626013083/maggieappleton.com/notes/evergreen-notes/Evergreen_Notes_09_qaql67_shrink_kzbsed.png"
/>

<BasicImage
  width="1000px"
  alt="Notes should be concept-oriented. This means they're based around big ideas rather than specific books, articles, or media"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1626013083/maggieappleton.com/notes/evergreen-notes/Evergreen_Notes_17_cqejme_shrink_vyhjaq.png"
/>


Illustrated notes on the concept of 'Evergreen notes' and how to write them

Growing the Evergreens


I've been looking into both [[Pattern Languages]] and [[Computer-Supported Collaborative Learning]] over the past month.

The [Knowledge Hydrant](http://www.industriallogic.com/papers/khdraft.pdf) is where these two meet in a lovely swirl of collaborative learning and organically emergent systems.

It's a draft document written up by [Joshua Kerievsky](https://twitter.com/JoshuaKerievsky) in 1999. The mini-manifesto describes a set of **Design Patterns** that people can use to set up their own indie study groups outside of formal structures like universities.

While the original focused on IRL, "co-present" <Footnote idName={1}>Getting real good at the [[Computer-Supported Collaborative Learning]] buzzwords and jargon over here</Footnote> groups, I'm fascinated by how we might adapt these patterns and turn them into internet-friendly, distributed digital versions.

Here's notes on the original while I'm thinking it through...

<BasicImage
  width="900px"
  alt="A fire hydrant framed by the words 'The knowledge hydrant'"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_800/v1593449022/maggieappleton.com/notes/knowledge-hydrant/knowledge-hydrant-1.png"
/>

<BasicImage
  width="1000px"
  alt="There are 21 patterns split into four groups – spirit, atmosphere, roles, and customs"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_800/v1593449021/maggieappleton.com/notes/knowledge-hydrant/knowledge-hydrant-2.png"
/>

<BasicImage
  width="1000px"
  alt="Step 1 is to find your knowledge hydrant – your source of important and worthwhile material"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1593449020/maggieappleton.com/notes/knowledge-hydrant/knowledge-hydrant-3.png"
/>

<BasicImage
  width="1000px"
  alt="Step 2 is to create a pool of insight – establihs a regular study group to discuss and debate key texts"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1593449020/maggieappleton.com/notes/knowledge-hydrant/knowledge-hydrant-4.png"
/>


Illustrated notes on the Knowledge Hydrant guide to collaborative learning

The Knowledge Hydrant


<IntroParagraph>

S[tian Håklev](http://reganmian.net/blog/), a fellow [[Roam Gardener]] and twitter friend, clued me in to the field of <b>Computer-Supported Collaborative Learning</b>.<Footnote idName={1}>Stian is a fascinating thinker, and I'd recommend <a href="https://louis-and-kyle.simplecast.com/episodes/stian-haklev-012">this podcast interview</a> to hear about his PhD in CSCL and applying it at <a href="https://www.minervaproject.com/">The Minerva Project</a></Footnote> Much like the name suggests, it's an academic discipline exploring the possibilities of pedagogy and education where **collaboration** and **computers** are first-class considerations.

</IntroParagraph>

Rather than treating digital mediums as a supportive system or extra add-on in a normal classroom environment, they're **The Main Thing**. And rather than focusing on how _individuals_ learn and understand, knowledge building as a _group_ is prioritised.

It's a reaction against what's known as the _"direct transmission"_ model – the view that learning is an individual experience of **passively receiving content** from someone lecturing at you.

TLDR; it's an entire academic discipline studying how we can build digitally-mediated [Communities of Practice](http://edutechwiki.unige.ch/en/Community_of_practice) for learning <Footnote idName={2}>Or, in their own words... "CSCL is a field of study centrally concerned with meaning and the practices of meaning-making in the context of joint activity, and the ways in which these practices are mediated through designed artifacts." <br/> <a href="http://www.gerrystahl.net/hci/cscl2002intro.pdf">Stahl, G. (2002) Computer Support For Collaborative Learning</a></Footnote>.

Stian warned me that, like almost all academic disciplines, they haven't mastered the art of [Learning in Public](https://www.swyx.io/writing/learn-in-public/). Some cursory research made it clear the main medium of communication for these folks is obscure academic conference papers and £200 scholarly publications.

The buzzwords and acronyms are stacked high.

This page is a record of my research as I wander into the world of CSCL – wide-eyed, naive, and excitable.

## Key Concepts and Essential Questions

#### Collaborative Learning Not Guaranteed

CSCL does not claim collaboration is a silver bullet solution to effective learning. Quite the opposite.

All the papers makes clear that collaboration in and of itself doesn't magically produce understanding. **Instead, it needs to be designed, structured, and carefully facilitated to lead to learning.**

The most effective techniques are not surprising...

- Meaningful discussion, debate, and negotiation that forces us to question our assumptions and revise our conclusions.
- Explaining your thinking to another human, out loud or in writing, quickly shows how well you know the material.
- Solving a problem, then comparing your solution to someone elses, and mutually agreeing upon the strengths and weaknesses of each.

Most of the research focuses on designing these intentional collaborative experiences. As well as the systems that make them possible (aka. apps, tools, platforms, all that jazz).

These are not new pedagogical findings, but CSCL is exploring how digital mediums are particularly well-suited to enabling them. Not just within small groups, but at scale.

Computer magic means we can have multiple, intertwining discussions all going on simultaneously. With a far wider range of expertise, experiences, and perspectives. Hence, Twitter.

<br />

<TwoColumn maxWidth="1200px" alignItems="flex-start">

<SimpleCard alignLeft>

"Collaborative Learning does not just mean that individual learning is enhanced by participation in small groups; <mark>it means that it is the groups themselves that learn."</mark> Knowledge is a product of the collaboration process: it <b>arises through interaction of different perspectives</b>, heats up in the cauldron of public discourse, is gradually refined through negotiation, and is <b>codified and preserved in cultural or scientific artifacts</b>"

<p className="subtext">
  Computer Support For Collaborative Learning: Foundations for a CSCL Community
  – <a href="http://www.gerrystahl.net/hci/cscl2002intro.pdf">Stahl (2002)</a>
</p>

</SimpleCard>

<SimpleCard alignLeft>

"Collaboration leads to positive outcomes only when students engage in **knowledge generative interactions** such as **giving explanations**, and engaging in **argumentation, negotiation, conflict resolution or mutual regulation**""

<p className="subtext">
  Designing Integrative Scripts –{" "}
  <a href="https://www.researchgate.net/publication/227598981_Designing_Integrative_Scripts">
    Dillenbourg and Jermann (2007)
  </a>
</p>

</SimpleCard>

<SimpleCard alignLeft>

"The occurrence of **knowledge-generative interactions** is not a
given: such <mark>interactions do not necessarily emerge spontaneously"</mark> (Cohen 1994; Salomon and Globerson 1989)

<p className="subtext">
  Computer Supported Collaborative Learning and Intelligent Tutoring Systems –{" "}
  <a href="https://www.cs.cmu.edu/~bmclaren/pubs/TchounikineEtAl-CSCLandITS-ITSBook2010.pdf">
    Tchounikine, Rummel, and McLaren (2010)
  </a>
</p>

</SimpleCard>

</TwoColumn>

### Creating Structure with Macro-scripts

It quickly became clear that **macro-scripts** are the bread and butter of CSCL systems. These are the [[Pattern Languages]] of the field that create structured collaboration.

CSCL Macro-scripts describe how a learning experience will play out.
On a general level, they define **a sequence of activities** focused around **a learning goal.** The learners all have assigned **roles** and follow a set of **constraints and rules for interaction.**

It sets up the whole dinner party for you, so participants can just show up and know all the learning logistics are taken care of.

That might sound a bit prescriptive. Until you realise every social interaction you engage in works this way. But most of the time our scripts and roles are so internalised they become invisible.

When we walk into a grocery store we play the role of shopper and follow the put-stuff-in-basket script. It would be disastrously off-script to begin eating a fresh croissant while standing in the bakery aisle, or to walk behind a checkout counter and begin scanning our own groceries. We have all been <Tooltip tiptext={<span>"The process by which people learn the dynamics of their surrounding culture and acquire values and norms appropriate or necessary in that culture and worldviews" - <a href="https://en.wikipedia.org/wiki/Enculturation">Enculturation on Wikipedia</a></span>}><i>enculturated</i></Tooltip> to follow the script. <Footnote idName={3}>What I'm describing is a well-established social theory developed by many people, but my favourite is <a href="https://en.wikipedia.org/wiki/Erving_Goffman">Erving Goffman</a>'s account that he presented in the classic book <a href="https://en.wikipedia.org/wiki/Frame_analysis">Frame Analysis</a>. Goffman refers to the social setting that scripts play out in as a "Frame"</Footnote>

Scripts make it much more likely learners will **develop a thorough understanding of the material**, and come away with **original perspectives on it.**

There's also a need for a fine balance of structure and improvisation. If scripts are too weak the learning experience falls apart. If they're too rigid or irrelevant, interactions become boring, sterile, and rote.

<br />

<TwoColumn maxWidth="1200px" alignItems="flex-start">

<SimpleCard alignLeft>

"CSCL scripts are primarily considered as support devices enabling learners to **stick to an effective pattern of collaboration more easily** and to obtain improved learning outcomes" (156)

<p className="subtext">
  Scripting Computer-Supported Collaborative Learning: Cognitive, Computational
  and Educational Perspectives –{" "}
  <a href="https://www.researchgate.net/publication/321610653_Scripting_Computer-Supported_Collaborative_Learning_Cognitive_Computational_and_Educational_Perspectives">
    Fischer, F. et al. (2007)
  </a>
</p>

</SimpleCard>

<SimpleCard alignLeft>

"Free collaboration does not systematically produce learning. One way to enhance the effectiveness of collaborative learning is to **structure interactions by engaging students in well-defined scripts**. A collaboration script is a set of instructions prescribing how students should form groups, how they should interact and collaborate and how they should solve the problem"

<p className="subtext">
  Over-scripting CSCL: The risks of blending collaborative learning with
  instructional design –{" "}
  <a href="https://pdfs.semanticscholar.org/1556/e5d2f93f6400457b422a011d7d93a3aa29fe.pdf">
    Dillenbourg (2002)
  </a>
</p>

</SimpleCard>

</TwoColumn>

### Playing the Role

One of the most intruiging elements of macro-scripts is that they define **clear roles** for each participant.

Most of us have been in meetings with assigned _facilitators_ and _scribes_, but we rarely expand beyond these.

Why stop there? What if we add in...

- A _Research-Runner_ who is in charge of fetching up links and references mentioned in the discussion.
- A _Sceptic_ or _Devil's Advocate_ who (constructively) raises objections and counter-opinions
- A _Timekeeper_ who moves us through the learning plan on schedule
- A _Summariser_ who captures the group's conclusions in succinct statements
- A _Reflector_ who mirrors people's points back to them in their own words
- An _Explorer_ responsible for gathering wildly off-beat references outside the traditional domain

There's a huge range of role options that you can pick and choose from depending on the size, synchronicity, and goals of the group.

The [Group Work Roles](http://edutechwiki.unige.ch/en/Group_work_roles) page on EduTech Wiki (an overall great place) elaborates on this list.

### What's a "Community of Practice"?

Coined by [Etienne Wegner](https://wenger-trayner.com/), a community of practice is a group of people "who **share a concern, a set of problems, or a passion about a topic**, and who deepen their knowledge and expertise by interacting on an ongoing basis."<Footnote idName={4}><a href="https://wenger-trayner.com/introduction-to-communities-of-practice/">Introduction to <br />communities of practice</a> - Etienne and Beverly Wenger-Trayner (2015)</Footnote>

It's a collection of people who are into the same stuff as you, that you end up stumbling into organically. In an ad-hoc decentralised way, you start collectively problem-solving and learning with them in a weird, emergent, beautiful process.

No one plans the community. No one regulates or controls it. There is no central calendar of events.

You earn membership by proving you have the right domain expertise and [Cultural Capital](https://en.wikipedia.org/wiki/Cultural_capital) to belong there. This doesn't necessarily mean an official domain like Biochemical Engineering. Knitting clubs and Favela gangs have equally valid kinds of domain expertise.

CSCL mentions Communities of Practice a lot. While much of the research focuses on your typical K-12 formal school institutions, there's a decent branch of it trying to figure out how we can foster and facilitate better CoP's.


Notes on the academic field of CSCL and major papers in the discipline

A Naive Exploration of Computer-Supported Collaborative Learning


<IntroParagraph>

There's an established concept called **Silent Meetings**. Much like it sounds, it's a meeting where for the most part no one talks.

</IntroParagraph>

Rather than one PowerPoint dictator lecturing to a room full of checked out people, silent meetings shift discussion into online collaborative documents.

Everyone sits quietly on their own device and comments on a **"Table Read"** – a shared document in Google Docs or Figma or a webpage annotated with <a href="https://hypothes.is">Hypothes.is</a>

People add comments and discussion points to the document directly. They're able to easily refer to specific parts, respond to other people's comments, and **run multiple threaded discussions**. Instead of one leader or instructor talking **at** many people, it's many people all talking **to** each other.

David Gasca wrote up a <a href="https://medium.com/swlh/the-silent-meeting-manifesto-v1-189e9e3487eb">comprehensive manifesto</a> on the phenomenon in 2019 that dives into the implementation details for using them at companies.

While it's a great concept for Corporateland, I'm keen to explore how we could use it for collaborative learning communities online.

Many of my [[Cozy Web]] communities are full of voracious readers. We're often looking for ways to run ad-hoc book clubs and reading groups, but the established formats are fairly vanilla. Standard Zoom calls. Or async stream discussions in Slack-esque apps.

The tools are janky. The [[Pattern Languages]] aren't well established. Systems like [[the Knowledge Hydrant]] give us good starting points, but aren't design with an online environment in mind.

One challenge of distributed learning is the coordination around timing. **Async reading doesn't focus collective attention in one place at one time.**

Picking a single time to 'meet' in a document gives people a structured frame to fully focus on reading, thinking, and discussing

The opportunity to follow up with a video or voice call right after also creates space for social bonding, nuanced conversations, and collaborative meaning-making. It prevents Twitter-esque brutality and presumptive misunderstandings.

I'm beginning to try this out. TBD


Notes on how to run silent meetings and reading sessions

Silent Synchronous Reading Sessions


<IntroParagraph>

Suspense is [an upcoming React feature](https://reactjs.org/docs/concurrent-mode-suspense.html) that's part of the new "concurrent mode." Since everyone is getting all hyped up about it, I wanted to figure out what the excitement was and drew some quick summary notes.

</IntroParagraph>

<BasicImage
  width="800px"
  alt="Wtf is React supense?"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1592262756/maggieappleton.com/egghead-course-notes/reactsuspense/WftReactSuspense_1.png"
/>

<BasicImage
  alt="Allows us to suspend rendering parts of our app until a particular condition is met, such as waiting until our data load. This keeps our interface interactive."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262756/maggieappleton.com/egghead-course-notes/reactsuspense/WftReactSuspense_2.png"
/>

<BasicImage
  alt="This allows us to prioritize the order that elements render in, based on those conditions. From high priority to low priority."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262754/maggieappleton.com/egghead-course-notes/reactsuspense/WftReactSuspense_4.png"
/>

<BasicImage
  alt="We create a suspense boundary around our components, and declare a fallback element to display while the data is loading."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262755/maggieappleton.com/egghead-course-notes/reactsuspense/WftReactSuspense_3.png"
/>

This is a pretty lightweight intro, but you get the gist of it. CSS-Tricks has a nice in-depth write up on [React Suspense in Practice](https://css-tricks.com/react-suspense-in-practice/)

If you're looking to properly learn how React suspense works, [Kent C. Dodds](https://twitter.com/kentcdodds) and [Michael Chan](https://twitter.com/chantastic) both made egghead courses on it

<ImageLink href="https://egghead.io/courses/use-suspense-to-simplify-your-async-ui">
  <ImageFrame
    width="800px"
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/use-suspense-to-simplify-your-async-ui"
  />
</ImageLink>

<ImageLink href="https://egghead.io/courses/build-an-app-with-react-suspense">
  <ImageFrame
    width="800px"
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/build-an-app-with-react-suspense"
  />
</ImageLink>

### Want to know what the fork is going on with other web development topics?

Take a look at [[What the Fork is xState?]], [[What the Fork is Rust?]], or the [[What the Fork is Babel?]]


Illustrated notes on how React suspense works

What the Fork is React Suspense?


<IntroParagraph>

I've made plenty of illustrated notes for <a href="https://egghead.io/">egghead</a> courses.  
On everything from [[Building Custom React Hooks]] to [[Fixing Common Git Mistakes]] to [[The Basics of Rust]]

</IntroParagraph>

They've always been artefacts made in post-production. I draw them after the course has already been planned, and the videos are all recorded. Over the last month I've been experimenting with a more collaborative approach.

Rather than treating our illustrations as a shiny add-on made by one person, I wanted to directly involve our course instructors and figure out how to **directly pair their expertise with my visual thinking skills**. So I started running visual workshopping sessions.

We hop on a Zoom call and open up a shared canvas in <a href="https://miro.com/">Miro</a> or <a href="https://excalidraw.com/">Excalidraw</a>. <Footnote idName={1}>They're both great and do the trick for the task at hand. I recommend playing with both!</Footnote>
We pick out a few of the toughest concepts, and begin making extremely rough diagrams. Experimental ugliness is the whole point.

We just did our first trial of this with <a href="https://tlakomy.com">Tomasz Lakomy</a>'s new course on <a href="https://egghead.io/courses/build-an-app-with-the-aws-cloud-development-kit">AWS Cloud Development</a>.

Here's Tomasz thinking very hard about API Gateways and Lambda Functions

<ImageFrame
  width="1200px"
  alt="A screenshot of the zoom video call where we're drawing out rough diagrams"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1200/v1592314229/maggieappleton.com/notes/visual-aws/workshop-screen.png"
/>

## The Process

The visuals we made during the workshopping session were mostly made of boxes
and arrows and labels like this:

<ImageFrame
  width="950px"
  alt="A sketchy diagram of the elements inside an AWS data centre"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1592317154/maggieappleton.com/notes/visual-aws/aws-cdk-post-10.png"
/>

It's all you really need to establish the basics. Nouns (things) are boxes,
and verbs (actions and events) are arrows.

After the workshopping call I looked back over the diagrams, and sketched out
an illustrated version that adds a bit more clarity and dimension to the
scene:

<ImageFrame
  width="950px"
  alt="A blue pencil sketch of the elements inside an AWS data centre and how they connect to a React app"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1592317154/maggieappleton.com/notes/visual-aws/aws-cdk-post-11.png"
/>

I ran the sketch by Tomasz to make sure all the technical details were
correct. Then did a final linework pass over the top to neaten everything up:

<BasicImage
  width="950px"
  alt="A refined ink ilustration showing the relationship between a React app, AWS API gateway, and lambda functions"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317154/maggieappleton.com/notes/visual-aws/aws-cdk-post-12.png"
/>

We ended up with five of these illustrations that cover all the main concepts of
the course

<Center>

## The Whole Series

</Center>

<TwoColumn maxWidth="1400px" alignItems="flex-start">

<ImageFrame
  width="720px"
  alt="Rough sketches of the location of AWS data centres"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317152/maggieappleton.com/notes/visual-aws/aws-cdk-post-7.png"
/>

<ImageFrame
  width="720px"
  alt="Blue pencil sketches of the location of AWS data centres"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317153/maggieappleton.com/notes/visual-aws/aws-cdk-post-8.png"
/>

</TwoColumn>

<BasicImage
  width="950px"
  alt="Final illustration of the location of AWS data centres"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317155/maggieappleton.com/notes/visual-aws/aws-cdk-post-9.png"
/>

---

<TwoColumn maxWidth="1400px" alignItems="flex-start">

<ImageFrame
  width="720px"
  alt=""
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317155/maggieappleton.com/notes/visual-aws/aws-cdk-post-13.png"
/>

<ImageFrame
  width="720px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317156/maggieappleton.com/notes/visual-aws/aws-cdk-post-14.png"
/>

</TwoColumn>

<BasicImage
  alt=""
  width="950px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1592317155/maggieappleton.com/notes/visual-aws/aws-cdk-post-15.png"
/>

<BasicImage
  alt=""
  width="950px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1592317157/maggieappleton.com/notes/visual-aws/aws-cdk-post-16.png"
/>

---

<TwoColumn maxWidth="1400px" alignItems="flex-start">

<ImageFrame
  alt=""
  width="720px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317152/maggieappleton.com/notes/visual-aws/aws-cdk-post-4.png"
/>

<ImageFrame
  alt=""
  width="720px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317151/maggieappleton.com/notes/visual-aws/aws-cdk-post-5.png"
/>

</TwoColumn>

<BasicImage
  alt=""
  width="950px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317153/maggieappleton.com/notes/visual-aws/aws-cdk-post-6.png"
/>

---

<TwoColumn maxWidth="1400px" alignItems="flex-start">

<ImageFrame
  alt=""
  width="720px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317151/maggieappleton.com/notes/visual-aws/aws-cdk-post-1.png"
/>

<ImageFrame
  alt=""
  width="720px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317152/maggieappleton.com/notes/visual-aws/aws-cdk-post-2.png"
/>

</TwoColumn>

<BasicImage
  alt=""
  width="950px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592317152/maggieappleton.com/notes/visual-aws/aws-cdk-post-3.png"
/>

If you're just here for all the gritty details of AWS you might want to check out the course itself. If you're here for the visual process, I popped a few more thoughts below..

<ImageLink href="https://egghead.io/courses/build-an-app-with-the-aws-cloud-development-kit">
  <ImageFrame
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/build-an-app-with-the-aws-cloud-development-kit"
  />
</ImageLink>

## Collaborative Minds > Beginners Mind

I may know a few things about how to visually explain ideas, but I usually
know _next to nothing_ about the topic of any given course.

There are some advantages to this.
Beginners mind is a beautiful thing.

But it has it's limitations. Because in order to visually explain something _well_, you need to truly understand it.

When we draw there are no vague relationships or fuzzy edges.  
You have to make clear how all the parts of a system are related.  
What's above and below. What's a container and what's a substance.  
What actions and events are happening between elements.

It requires a nuanced understanding of the material.

My old beginners notes are still useful - they make the implicit explicit.
They explain concepts the expert would never think to.

But they also fall short in lots of ways. I make mistakes. I skim the surface of material. I can't dive deep on technical details.

Collaborative workshopping gives us the best of both worlds. I still get to ask dumb questions (purposefully), like **"is the React app above or below the GraphQL request?"** or **"does an S3 bucket have a lid?"**

It's the Socratic method for visual thinking.

Asking these odd questions helps us establish a vocabulary of shapes, sizes, colors, metaphors, and spatial relationships.

Our instructors have the deep context to answer these kind of questions well, and reason through why certain visual arrangements make more sense than others.

I'm just there to prod them in certain directions, and add a bit of polish afterwards.

We're doing plenty more of these. I can't wait <span>🤓</span>


Some insights into how I collaborative with experts to create illustrated notes on technical topics

Visually Workshopping the AWS Cloud


<IntroParagraph>

In September of 2019 I took a course called <a href='https://www.buildingasecondbrain.com'>Building a Second Brain</a> by <a href='https://twitter.com/fortelabs'>Tiago Forte</a>.

Much like it sounds, Building a Second Brain is about creating a reliable system – outside your physical skin-and-bone bodily boundaries – for storing, organising, digesting, and eventually transforming information into Good Creative Output.

</IntroParagraph>

Much like any well-integrated tool, the mental distance between you and the system grows small.  
It's a lovely little closed feedback loop – <a href="https://en.wikipedia.org/wiki/Cybernetics">a cybernetic system</a>.  
At this point almost all of my daily workflow revolves around my second brain. as, articles, books, papers, podcasts, and half-formed thoughts go in.  
These build into notes and develop over time – they merge, meander, and mature into talks and blog posts and illustrations.  
It is hard to remember what my workflow looked like without it.

For tools I'm currently using <a href="https://roamresearch.com/">Roam Research</a>, backed up by <a href="https://www.keyboardmaestro.com/main/">Keyboard Maestro</a> for some fancy automation elements.

These illustrated cover all the sections of the course. Enjoy!

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586173192/maggieappleton.com/basb/Basb1-4_2x.jpg"
  alt="Building a second brain (BASB) illustrated notes on the PARA system of organising content projects, areas, resources, and archives"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586173190/maggieappleton.com/basb/Basb1-2_2x.jpg"
  alt="BASB sketchnotes on putting projects in priority order and defining the desired outcome"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586173188/maggieappleton.com/basb/Basb1-1_2x.jpg"
  alt="BASB sketchnotes on wiping the slate clean and setting up PARA as a folder structure"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586173189/maggieappleton.com/basb/Basb1-3_2x.jpg"
  alt="BASB sketchnotes on creating metaplans before you start your project"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586173064/maggieappleton.com/basb/Basb2-1_2x.jpg"
  alt="BASB sketchnotes on digital cognition and building a personal knowledge base"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586173065/maggieappleton.com/basb/Basb2-2_2x.jpg"
  alt="BASB sketchnotes on your notes being unpolished, personal, open-ended, and diverse"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586173061/maggieappleton.com/basb/Basb2-3_2x.jpg"
  alt="BASB sketchnotes on considering 12 favourite problems to focus on"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172896/maggieappleton.com/basb/Basb3-1_2x.jpg"
  alt="BASB sketchnotes on balancing discoverability with understanding in your notes"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172898/maggieappleton.com/basb/Basb3-2_2x.jpg"
  alt="BASB sketchnotes on putting your notes through 5 layers of progressive summarisation"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172894/maggieappleton.com/basb/Basb3-3_2x.jpg"
  alt="BASB sketchnotes on focusing on what resonates when summarising your notes"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172982/maggieappleton.com/basb/Basb4-1_2x.jpg"
  alt="BASB sketchnotes on thinking of return on attention like ROI"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172879/maggieappleton.com/basb/Basb4-2_2x.jpg"
  alt="BASB sketchnotes on flow state as the pinnacle of experience, learning, and performance. As well as the biochemistry of flow state."
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172878/maggieappleton.com/basb/Basb4-3_2x.jpg"
  alt="BASB sketchnotes on solving the interruptability of flow with placeholding and breaking work down into smaller packets"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172879/maggieappleton.com/basb/Basb4-4_2x.jpg"
  alt="BASB sketchnotes on wrestling with knowledge by interacting with it in meanginful ways"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172864/maggieappleton.com/basb/Basb5-1_2x.jpg"
  alt="Just in time project management helps us balance our workflow between capture and delivery."
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172865/maggieappleton.com/basb/Basb5-2_2x.jpg"
  alt="Your orderly system of notes is like mise en place – everything in its place"
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172873/maggieappleton.com/basb/Basb5-4_2x.jpg"
  alt="We need flexible strategies, not static workflows. We diagnose the problem, form a guiding policy to tackle it, and write an action plan to implement it. "
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172866/maggieappleton.com/basb/Basb5-3_2x.jpg"
  alt="Some workflow strategies we can use include context switching, changing the form of our notes, and adding color commentary through annotations and highlights."
/>

<BasicImage
  width="1100px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:best,w_1100/v1586172858/maggieappleton.com/basb/Basb6-1_2x.jpg"
  alt="The final section of BASB covers how to make a personal knowledge management canvas"
/>

---

To be clear there's no affiliate as or kickback involved in these notes.
I'm not being paid to say nice things about the course.

Tiago's ideas and systems are just good. He thinks everything through in a way that feels rare on the insta-internet.

Hope it gave you a bit of insight into the BASB system.
There's plenty more to explore on Tiago's <a href="https://praxis.fortelabs.co/">Forte Labs Blog</a> and he's <a href="https://twitter.com/fortelabs">good at tweeting</a>.


Illustrated notes on the Building A Second Brain course

Building a Second Brain: The Illustrated Notes


<BasicImage
  width="750px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1576769959/maggieappleton.com/git-mistakes/FixGitMistakes_4.png"
  alt="Fixing common git mistakes"
/>

Illustrated notes I made while working through [Chris Achard](https://chrisachard.com/)'s [Fix Common Git Mistakes](https://egghead.io/courses/fix-common-git-mistakes) course on egghead.

<ImageLink href="https://egghead.io/courses/fix-common-git-mistakes">
  <ImageFrame
    alt="Course illustration of a set of git pipes being repaired"
    src="https://og-image-egghead-course.now.sh/fix-common-git-mistakes"
  />
</ImageLink>

<br />

<BasicImage
  width="1050px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1590015687/maggieappleton.com/git-mistakes/FixGitMistakes_3.png"
  alt="Fixing common git mistakes"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1590015790/maggieappleton.com/git-mistakes/FixGitMistakes_1.png"
  alt="Fixing common git mistakes"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1590015637/maggieappleton.com/git-mistakes/Artboard_2.png"
  alt="Fixing common git mistakes"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1590015638/maggieappleton.com/git-mistakes/Artboard_3.png"
  alt="Fixing common git mistakes"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1590015643/maggieappleton.com/git-mistakes/Artboard_4.png"
  alt="Fixing common git mistakes"
/>

<BasicImage
  width="950px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1590015844/maggieappleton.com/git-mistakes/FixGitMistakes_2.png"
  alt="Fixing common git mistakes"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_980/v1590015640/maggieappleton.com/git-mistakes/Artboard_4_copy.png"
  alt="Fixing common git mistakes"
/>

### Want more illustrated notes on web development?

Take a look at [[Building Custom React Hooks]], [[What the Fork is Rust?]] or find out [[How Are Compilers & Transpilers Different?]]


Illustrated notes on common mistakes people make in Git, and how to fix them

Fixing Common Git Mistakes


<IntroParagraph>

The **Cozy web** is <a href="https://venkateshrao.com/">Venkatesh Rao</a>'s term for the private, gatekeeper bounded spaces of the internet we have all retreated to over the last few years.

</IntroParagraph>

Venkat first proposed the term in one of his _Breaking Smart_ emails on <a href="https://breakingsmart.substack.com/p/the-extended-internet-universe">The Extended Internet Universe</a>, and mentioned Yancey Strickler's companion idea of <a href="https://onezero.medium.com/the-dark-forest-theory-of-the-internet-7dc3e68a7cb1">the **Dark Forest**</a>

Loving both of these notions, I felt compelled to bring them together into an illustrated diagram of our current Social Internet Situation.

<br />

<BasicImage
    width="1000px"
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1589323597/maggieappleton.com/notes/cozyweb-tw.png"
    alt="Layered diagram of the cozy web as a series of underground burrows beneath the dark forest"
/>

We create tiny underground burrows of Slack channels, Whatsapp groups, Discord chats, and Telegram streams that offer shelter and respite from the aggressively public nature of Facebook, Twitter, and every recruiter looking to connect on LinkedIn.

It's the digital realm of <a href="https://www.ribbonfarm.com/series/domestic-cozy/">Domestic Cozy</a> Gen-Z vibes.  
Casual, comfy, and not trying to kick up a fuss.

The cozy web works on "(human) protocol of everybody cutting-and-pasting bits of text, images, URLs, and screenshots across live streams", hopefully one day evolving "from cut-and-paste to a personal blockchain of context-permissioned, addressable, searchable, interlinked clips" as Venkat puts it.

It's since become a standard part of the Venkat Vocabulary for fellow Ribbonfarmers and Yaks, and remains one of my favourite [[Neologisms]] of this year.


An illustrated diagram exposing the inner layers of the dark and cozy web

The Dark Forest and the Cozy Web


I got the chance to chat with <a href='https://www.henryzoo.com'>Henry Zhu</a> on his <a href="https://maintainersanonymous.com/">Maintainers Anonymous</a> podcast.

<Podcastiframe
  scrolling="no"
  src="https://share.transistor.fm/e/9d389287"
></Podcastiframe>

<Spacer size="small" />

It's a show about people who maintain things in the world. Whether it's code, cities, infrastructure, or museum archives, someone has to keep the decks clean and the engine stoked.

I'm not a maintainer (the only thing I reliably maintain is an obsessive tea habit), but I went on to chat to Henry about the overlap between the <a href="https://en.wikipedia.org/wiki/Open-source-software_movement">open source software</a> and the anthropological theory of [[Gift Economies]].

Gift theory, reciprocity, and economic anthropology are all side obsessions of mine. I originally trained as a cultural anthropologist, and it's still an enormous part of how I understand and operate in the world.

Like any good cult, once you're indoctrinated you can never leave.

<BasicImage
  alt="Illustration of a gift and the open source software symbol"
  width="300"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1593552785/maggieappleton.com/notes/spot_gift.png"
/>

Henry and I began discussing the parallels between gift economies and open source software (OSS) last summer.

At the time I barely knew anything about OSS. Which made me fairly typical. 99.9% of the world haven't a clue about the rich, dramatic cultural history of Linux, or Xerox PARC, or the browser wars. Despite the fact 99.9% of the software we all depend upon is built using open source projects. It's invisibility and pervasiveness alone makes it worth a closer look.

Henry earned his stripes in the OSS world as the core maintainer of [[Babel]] - an open-source javascript [[transpiler]] that's used by the vast majority of javascript-based websites.

The Babel project, and Henry as its steward, is a fascinating case study in the open source software economy and where it's headed.

<Center>

### Not sure what Babel is?

Take a quick look at my [[WTF is Babel?]] illustrated explanation

</Center>

<BasicImage
  width="500px"
  alt="Illustrated words reading 'wtf is babel?'"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_600/v1593552781/maggieappleton.com/notes/babel_crop.png"
/>

Our chat is wide ranging discussion where we're both thinking out loud and exploring ideas, rather than coming to insightful or profound conclusions. We're doing some follow-up episodes in the coming months as well.

<p>
  <a href="https://maintainersanonymous.com/">Subscribe to the podcast</a> if
  you don't want to miss them.
</p>

## Things we Mention in the Episode

- What can Open Source Software learn from the anthropology of gift economies?
- <a href="https://en.wikipedia.org/wiki/Emic_and_etic">Emic vs. Etic</a> types of
  research in anthropology
- The three types of <a href="https://en.wikipedia.org/wiki/Reciprocity_(cultural_anthropology)">reciprocity</a> proposed by anthropologist Marshall Sahlins: _Generalised, Balanced, and Negative_. <Footnote idName={1}>Originally outlined in his 1972 book <a href="https://www.goodreads.com/book/show/28254.Stone_Age_Economics">Stone Age Economics</a></Footnote>
- The <a href="https://en.wikipedia.org/wiki/Kula_ring">Kula Ring</a> of the Trobriand islands as the prototypical anthrolopogy example of a [[Gift Economy]].
- The <a href="https://allcontributors.org/">All Contributors</a> system that acknowledges open source contributions for a wide range of skills
- <a href="https://en.wikipedia.org/wiki/Negative_liberty">Negative</a> vs. <a href="https://en.wikipedia.org/wiki/Positive_liberty">
    positive
  </a> freedom - Freedom from external constriants vs. the ability to act out of
  free will
- New tools that are enabling OSS communities – <a href="https://www.patreon.com/">Patreon</a>, <a href="https://github.com/sponsors">Github Sponsors</a>, and <a href="https://opencollective.com/">Open Collective</a>
- How can we make the interactions and exchanges between contributors and maintainers more personal and relationship-based?
- Developers have enourmous cultural power in the world that is rarely acknowledged in the community. What developers value and believe comes out in what tools get built, which in turn shapes how culture evolves.
- The [[quantified self]] movement and the presumed value of quantifiying everything.
- <a href="https://en.wikipedia.org/wiki/Epistemology">Epistemology</a> and how we
  know what we know. The value of tacit, subjective truth in addition to explicit,
  objective truth. We're in a historical moment where the emphasis on the disembodied
  rationalist view has drowned out the value of embodied, personal knowing.
- <a href="https://www.goodreads.com/book/show/282032.Personal_Knowledge">
    Personal Knowledge
  </a> by Michael Polanyi
- <a href="https://www.goodreads.com/book/show/34459.Metaphors_We_Live_By">
    Metaphors We Live By
  </a> by George Lakoff
- Traditional hacker culture glorifying programming as a cerebral, disembodied activity.
  We haven't yet figured out how to make our digital tools embodied. Which carries over into how we experience social relationships through them.
- <a href="https://www.goodreads.com/book/show/253076.Tools_for_Conviviality">
    Tools for Conviviality
  </a> by Ivan Illich
- The more professionalised skills become, the harder it is for people to join. Programming at least tries to knock down those gatekeepers and trumpets the narrative that we roll out the welcome mat for people. Open source often acts as that open door.

<Spacer size="small" />

<References>

#### Papers and Talks

- <a href="https://m.signalvnoise.com/open-source-beyond-the-market/">
    Open source beyond the market
  </a> by David Heinemeier Hansson
- <a href="https://www.jstor.org/stable/26179346">
    The Moral Economy of Digital Gifts
  </a> by Dave Elder-Vass
- <a href="https://www.researchgate.net/publication/326331925_The_Plural_economy_of_gifts_and_markets">
    The Plural Economy of Gifts and Markets
  </a> by Ioana Negru

#### Books

<ResourceBook
  url="https://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar"
  image="/images/books/bazaar.jpeg"
  title="The Cathedral and the Bazaar"
  author="Eric Raymond"
>
  Perhaps the most infamous book on this topic, Raymond gives an insiders view
  of the history and practice of OS from the 1940s up to 1999. He proposes a
  foundational philosophy for the community, and a series of maxims for
  effective OS work
</ResourceBook>

<ResourceBook
  url="https://www.goodreads.com/book/show/14891812-coding-freedom"
  image="/images/books/codingfreedom.jpg"
  title="Coding Freedom: The Ethics and Aesthetics of Hacking"
  author="Gabriella Coleman"
>
  A distinctly anthropological exploration of OS, Coleman covers its history,
  philosophy, and cultural structures. Coleman is anthropologist specialising in
  open source hacker culture, Anonymous, 4chan, and all their tangential worlds
</ResourceBook>

<ResourceBook
  url="https://www.goodreads.com/book/show/201766.The_Gift"
  image="/images/books/gift.jpg"
  title="The Gift"
  author="Marcell Mauss"
>
  An anthropological classic on gift theory and gift economies. Published in
  1923, Marcel Mauss explores how systems of exchange work in traditional
  societies around the world in relation to politics, power, and kinship."
</ResourceBook>

<ResourceBook
  url="https://www.goodreads.com/book/show/28254.Stone_Age_Economicst"
  image="/images/books/stoneage.jpeg"
  title="Stone Age Economics"
  author="Marshall Sahlins"
>
  A comparive study of economic structures exploring the wide variety found
  among hunter-gatherer societies. Discusses the meaning of affluence, material
  wealth, and how comminities build rituals around exchange and acts of
  reciprocity.
</ResourceBook>

<ResourceBook
  url="https://books.google.co.uk/books/about/Economies_and_cultures.html"
  image="/images/books/economiescultures.jpg"
  title="Economies and Cultures: Foundations of Economic Anthropology"
  author="Richard Wilks"
>
  Okay, yes it's a textbook. But it's not as dry as most and gives a sweeping
  tour through the history of anthropological thought on economics, value
  systems, and social exchange.
</ResourceBook>

</References>


Notes from my podcast episode Open Source and Gift Economies on Maintainers Anonymous

A Chat with Henry Zhu on OSS & Gift Economies


<IntroParagraph>

Between IoT botnet attacks, Bitcoin ransomware, and the weekly cadence of high-profile data breaches, doing anything on the internet feels like playing Russian Roulette.

</IntroParagraph>

And that's just for normal people using it.

If you're a developer, you're partially **responsible** for protecting all those normal people from the horrors of whatever [LulzSec](https://en.wikipedia.org/wiki/LulzSec) are up to right now. The least you can do is make sure your website isn't an accessory to their nefarious activities.

Thankfully, you do not have to brave the black hat darkness alone.

[Mike Sherov](https://twitter.com/mikesherov) made an [egghead](https://egghead.io/courses/web-security-essentials-mitm-csrf-and-xss) course that covers a whole series of web security essentials

<ImageLink href="https://egghead.io/courses/web-security-essentials-mitm-csrf-and-xss">
  <ImageFrame
    width="800px"
    alt="Course illustration of objects in 3D space"
    src="https://og-image-egghead-course.now.sh/web-security-essentials-mitm-csrf-and-xss"
  />
</ImageLink>

I am (thankfully) not responsible enough for anyone to put me in charge of security for an important website. But I was still curious.

I wanted to know what the current landscape of internet risk looks like. How, _exactly_, is LulzSec going to hack into my mainframe in 2020?

Here's my illustrated notes from Mike's course that should give you a big picture overview of what to should look out for.

<BasicImage
  width="850px"
  alt="Web security essentials - Let's look at three common attacks"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_780/v1592262535/maggieappleton.com/egghead-course-notes/websecurity/web-security-1.png"
/>

Turns out there's a small set of fairly well-known and easy to defend attacks that we can protect ourselves from:

- Man in the Middle (MITM)
- Cross-Site Request Forgery (CSRF)
- Cross-Site Scripting (XSS)

Shielding yourself from these three is a great starting point. It's at least enough to keep the [script kiddies](https://en.wikipedia.org/wiki/Script_kiddie) out.

<BasicImage
  width="1000px"
  alt="First, man in the middle is a piece of software that intercepts data between a client and a server"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262537/maggieappleton.com/egghead-course-notes/websecurity/web-security-2.png"
/>

<BasicImage
  width="950px"
  alt="If this connection is over HTTP all your data packets are readable cleartext. Anyone on the network can use a packet sniffer to see your data. Instead we use HTTPS to encrypt packets."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262538/maggieappleton.com/egghead-course-notes/websecurity/web-security-6.png"
/>

<BasicImage
  width="1000px"
  alt="How to protect yourself. Use HSTS headers. Require HTTPS everywhere. Redirect HTTP to HTTPS"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262533/maggieappleton.com/egghead-course-notes/websecurity/web-security-7.png"
/>

<BasicImage
  width="1000px"
  alt="Cross-site request forgery is an attack that tricks the user into visiting a malicious site while they're already logged into a trusted site"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262538/maggieappleton.com/egghead-course-notes/websecurity/web-security-3.png"
/>

<BasicImage
  width="1000px"
  alt="This is possible because browsers send cookies between sites by default. How to protect yourself. Cookies come with a 'sameSite' property that prevents them from being passed between sites. Set it to 'lax' or 'strict'"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262536/maggieappleton.com/egghead-course-notes/websecurity/web-security-4.png"
/>

<BasicImage
  width="1000px"
  alt="Cross-site scripting is an attack that injects malicious code into a trusted site. This can happen is the site allows user input to appear on the page without validating or encoding it. Protect yourself with a content security policy which manages which types of resources are allowed to load and where"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262536/maggieappleton.com/egghead-course-notes/websecurity/web-security-5.png"
/>

Keeping out this trio of attacks will go a long way.

If (unlike me) you _are_ responsible enough to be in charge of security for a moderately-sized website, it might be worth double checking you have these protections in place.

Better safe than sorry. Especially when sorry means you end up on the front page of Hacker News in this week's edition of obviously preventable security breaches.

<br />

<BasicImage
  alt="The fully illustrated notes on web security essentials"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262538/maggieappleton.com/egghead-course-notes/websecurity/web-security-final--small.png"
/>

---

### Want more illustrated notes on web development?

Take a look at [[Testing Apps with Cypress]], [[The JAMStack, Gatsby & Contentful]] or [[A Fresh Serving of JavaScript ES2019]]


Illustrated notes on the essentials of web security

Defend Your Cookies with Essential Web Security Tactics


[xState](https://xstate.js.org/) is a snazzy way to manage JavaScript application state using visual state charts.
It's a pretty wonderful tool for making sure you think through every possible edge case of an application.

There's also a handy [visualiser tool](https://xstate.js.org/viz/) that synchronizes your code and visuals. If you edit one, the other changes to match. <span aria-role="image">✨</span>

<ImageFrame
  alt="Screenshot of the xState visualizer"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_920/v1592930602/maggieappleton.com/egghead-course-notes/xstate/Screenshot_2020-06-23_at_17.41.45.png"
/>

<br />

It's perfect for visual thinkers. If someone could just build one of these for the entire of JavaScript I'll be all set.

Here's a little more illustrated detail on how this works:

<BasicImage
  width="900px"
  alt="Xstate is a tool that helps you plan out all the possible states in a JavaScript app"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1592931672/maggieappleton.com/egghead-course-notes/xstate/xState_5.png"
/>

<BasicImage
  width="800px"
  alt="There's a handy interactive visualizer tool at xstate.js.org/viz"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_860/v1592262779/maggieappleton.com/egghead-course-notes/xstate/xState_2.png"
/>

<BasicImage
  width="900px"
  alt="A sequence of light bulbs swapping states between unlit, lit, dim, and broken."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262781/maggieappleton.com/egghead-course-notes/xstate/xState_3.png"
/>

<BasicImage
  width="900px"
  alt="We can add extra options onto our states such as actions, services, guards, and activities"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262777/maggieappleton.com/egghead-course-notes/xstate/xState_4.png"
/>

If you're keen to learn more xState there's two courses up on egghead that cover all the basics:

<ImageLink href="https://egghead.io/courses/introduction-to-state-machines-using-xstate?af=54fd64">
  <ImageFrame
    width="800px"
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/introduction-to-state-machines-using-xstate"
  />
</ImageLink>

<ImageLink href="https://egghead.io/courses/construct-sturdy-uis-with-xstate?af=54fd64">
  <ImageFrame
    width="800px"
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/construct-sturdy-uis-with-xstate"
  />
</ImageLink>

---

### Want more illustrated notes on web development?

Take a look at [[Building VR Apps with React360]], [[A Journey into Vue-Router]], or [[Immutable Data with Immer and Personal Assistant Bots]]


Illustrated notes on how to build state machines with the xState library

What the Fork is xState?


<IntroParagraph>

I haven't explored the [Vue](https://vuejs.org/) framework much but it's got a thriving community, and I wanted to see how it compared to React, Svelte, and the 20 other font-end framework options.

</IntroParagraph>

<BasicImage
  width="500px"
  alt="A box with green vue roads coming out of it"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262763/maggieappleton.com/egghead-course-notes/vuerouter/thumb_2x.png"
/>

I got to see inside the Vue-machine a little while working through [Laurie Barth](https://twitter.com/laurieontech)'s [egghead course](https://egghead.io/courses/a-journey-with-vue-router) on how to set up routes between Vue pages and components.

I made a few illustrated notes on the main concepts

<BasicImage
  width="1050px"
  alt="Journey with Vue Router"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262764/maggieappleton.com/egghead-course-notes/vuerouter/VueRouter_1.png"
/>

<BasicImage
  width="1050px"
  alt="To setup, install and import vue router, create an empty array of routes, and pass that array into a new router function"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262762/maggieappleton.com/egghead-course-notes/vuerouter/VueRouter_2.png"
/>

<BasicImage
  width="1050px"
  alt="When making new routes, each one needs a path and a component. We can also pass parameters to our routes"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262765/maggieappleton.com/egghead-course-notes/vuerouter/VueRouter_3.png"
/>

<BasicImage
  width="1050px"
  alt="The wild card path acts as a cacthall for unknown routes"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262764/maggieappleton.com/egghead-course-notes/vuerouter/VueRouter_4.png"
/>

<br />

If you're a Vue person and want to dive into this more, you can check out Laurie's course here...

<ImageLink href="https://egghead.io/courses/a-journey-with-vue-router">
  <ImageFrame
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/a-journey-with-vue-router"
  />
</ImageLink>

### Want more illustrated notes on web development?

Take a look at [[Instachatting with Vue & Socket.io]], [[Immutable Data with Immer and Personal Assistant Bots]], or [[What the Fork is xState?]]


Illustrated notes on how routing works in Vue.js

A Journey into Vue-Router


<IntroParagraph>

The <a href="https://www.rust-lang.org/">Rust programming language</a> keeps winning the middle-school popularity contest of the developer world: "most loved" on <a href="https://insights.stackoverflow.com/survey/2019#technology">Stack Overflow surveys</a>.

</IntroParagraph>

<ImageFrame
  alt="Chart showing rust at the top of the rankings for most loved languages with 83.5%"
  width="800px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1592262509/maggieappleton.com/egghead-course-notes/wtf-rust/stackoverflow.png"
/>

So, what's this Rust thing and why is everyone enamoured?  
Let's explore...

<BasicImage
  width="800px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_800/v1592262461/maggieappleton.com/egghead-course-notes/wtf-rust/WTFRust_1.png"
  alt="An Introduction to Rust"
/>

<BasicImage
  width="900px"
  alt="Rust is a programming language mainly used to build 'system software.' Which means any software that acts as a platform for other software to run on top of it. iOS, linux, and windows are all system software. Rust is also becoming popular for making web apps. We can compile rust files into web assembly, which lets us run them in the browser."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1592262462/maggieappleton.com/egghead-course-notes/wtf-rust/WTFRust_2.png"
/>

<BasicImage
  width="900px"
  alt="The power of rust is that it balances speed and safety. Safety here means memory safety. Mishandling how we store data on physical microchips can lead to bugs and security flaws. High-level languages are abstract and safer. Low-level languages work directly with memory, making them dangerous but fast. Rust lives in the happy middle ground"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1592262462/maggieappleton.com/egghead-course-notes/wtf-rust/WTFRust_4.png"
/>

This happy balance Rust manages to strike – between speed, control over memory, and human-friendliness is what makes it so popular.

The kind of programmes you can write with Rust would otherwise be made in a language like <a href="https://en.wikipedia.org/wiki/C_(programming_language)">C</a> or <a href="https://en.wikipedia.org/wiki/C%2B%2B">C++</a>. A lot of developers find the C-suite challenging to work with, so this friendly alternative is very welcome!

> It's got the <a href='https://en.wikipedia.org/wiki/Goldilocks_principle'>Goldilocks Effect</a> going on. Not too slow, not too dangerous, not too complicated – just right.

The Rust community is also infamous for being welcoming, open, and encouaging to newcomers. Fostering that kind of culture is very likely why it's gained so much traction in the last few years.

Anyone who hangs out in Developer World long enough realises frameworks and languages are identities much more than they're tools. You _belong_ to Team React, or Camp Python, or the Rust Crew.

And no one wants to join a bunch of judgey gatekeepers.

<BasicImage
  width="900px"
  alt="The rust install package comes with 'rustc' - the compiler, 'cargo' - the package manager, and 'rustup' - the toolchain"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1592262461/maggieappleton.com/egghead-course-notes/wtf-rust/WTFRust_3.png"
/>

<BasicImage
  width="900px"
  alt="Rust is statically typed. This means the data type of every variable must be known at compile time. You can declare data types or let rust make an educated guess. Rust's compiler is strict. It won't let you mix data types."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1592262462/maggieappleton.com/egghead-course-notes/wtf-rust/WTFRust_5.png"
/>

<BasicImage
  width="900px"
  alt="Rust is obsessed with ownership. Every value belongs to a variable. Values are like pet hamsters, they need an owner. If LeBron owns this hamster, then we assign LeBron to Shaq, ownership move to Shaq. LeBron no longer owns the hamster."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_960/v1592262465/maggieappleton.com/egghead-course-notes/wtf-rust/WTFRust_6.png"
/>

I've just done a sweeping and completely incomplete overview of Rust here. But it's enough to point you in the right direction. There's plenty more to explore.

<p>
  While researching and making these I watched{" "}
  <a href="https://twitter.com/PascalPrecht">Pascal Precht</a>'s new egghead
  course that shows you how to{" "}
  <a href="https://egghead.io/courses/write-your-first-program-with-the-rust-language">
    Write Your First Program with Rust{" "}
  </a>
</p>

<ImageLink href="https://egghead.io/courses/write-your-first-program-with-the-rust-language">
  <ImageFrame
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/write-your-first-program-with-the-rust-language"
  />
</ImageLink>

Pascal covers more specific details like how Rust handles variables, mutability, functions, pointers, borrowing, loops, and errors.

If you're curious to start Rusting, worth taking a look.

<br />

### Want more illustrated notes on web development?

Take a look at [[Building Custom React Hooks]], [[Fixing Common Git Mistakes]], or [[JavaScript Bits You Skipped the First Time Around]]


Illustrated notes on the core concepts in Rust

What the Fork is Rust?


More illustrated notes, this time on [Gatsby themes](https://www.gatsbyjs.org/docs/themes/what-are-gatsby-themes/).

They're one of the newer features in [Gatsby.js](https://www.gatsbyjs.org/) – little building blocks of site functionality you can mix n' match n' share on NPM.

[Chris Biscardi](https://twitter.com/chrisbiscardi) made [an extensive course](https://egghead.io/courses/composable-gatsby-themes) on egghead on how to build your own.

<ImageLink href="https://egghead.io/courses/composable-gatsby-themes?af=54fd64">
  <ImageFrame
    width="800px"
    alt="Composable Gatsby Themes"
    src="https://og-image-egghead-course.now.sh/composable-gatsby-themes"
  />
</ImageLink>

This whole site is built in Gatsby so I'm always trying to level up my understanding of how it works under the hood. Makes it easier to play.

<BasicImage
  width="1000px"
  alt="Building composable gatsby theme title"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_850/v1576769939/maggieappleton.com/egghead-course-notes/gatsby-themes-notes/GatsbyThemes_1.png"
/>

<BasicImage
  width="1000px"
  alt="Gatsby themes let you break a site into reusable chunks of functionality"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1576769938/maggieappleton.com/egghead-course-notes/gatsby-themes-notes/GatsbyThemes_2.png"
/>

<BasicImage
  width="1000px"
  alt="Yarn workspaces are ideal for developing gatsby themes. It lets us have multiple packages in a single repo"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1576769939/maggieappleton.com/egghead-course-notes/gatsby-themes-notes/GatsbyThemes_3.png"
/>

<BasicImage
  width="1000px"
  alt="We're building 3 themes here - marketing, shopify, and blog"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1576769938/maggieappleton.com/egghead-course-notes/gatsby-themes-notes/GatsbyThemes_4.png"
/>

---

I also made the course illustration for this one:

<BasicImage
  width="900px"
  alt="A set of sketches and colour palette tests for the main illustration"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1579731535/maggieappleton.com/egghead-course-notes/gatsby-themes-notes/Twitter.png"
/>

My <a href="/drawinginvisibles1">process for making these</a> usually sticks to Procreate, Adobe Illustrator, and Photoshop <Footnote idName={1}>You can read more [here](/apps) on what tools and hardware I use</Footnote>, but I experimented with some 3D rendering in Cinema 4D for this one. Certainly sped up the process a bit, though made the final look a little more stiff than usual. Trade offs.

<BasicImage
  width="860px"
  alt="A 3D mockup of a house made of blocks"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1579731531/maggieappleton.com/egghead-course-notes/gatsby-themes-notes/Twitter_2.png"
/>

### Want more illustrated notes on web development?

Take a look at [[Speaking the GraphQL Query Language]], [[The JAMStack, Gatsby & Contentful]], or the [[Essential Web Security Tactics]]


Illustrated notes on building Gatsby themes

The Art and Craft of Gatsby Themes


<BasicImage
  width="700px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_700/v1580828081/maggieappleton.com/egghead-course-notes/advancedjs-notes/AdvancedJS_1_2x.png"
  alt="Advanced JavaScript Fundamentals"
/>

<IntroParagraph>

Being humans, we rarely learn things linearly. No one begins their JavaScript journey by reading [the TC39 language specification](https://www.ecma-international.org/ecma-262/5.1/) line-by-line like a pedantic masochist.

</IntroParagraph>

```js
let banana = "banana";
let apple = "apple";

console.log(banana);
console.log(apple);
```

Instead we all cobble together a good-enough understanding, leaving holes here and there to fill in later.

So far I've stumbled along without 100% grokking prototypical inheritance, or how `call, apply,` and `bind` work on functions.

It's fine. Stuff mostly works. Until it doesn't ¯\_(ツ)\_/¯

But at some point, it's useful to stop stumbling about and peek back at those holes.

<ImageLink href="https://egghead.io/courses/advanced-javascript-foundations">
  <ImageFrame
    alt="Course illustration of a building with a bright yellow foundation floor for advanced javascript foundations"
    src="https://og-image-egghead-course.now.sh/advanced-javascript-foundations"
  />
</ImageLink>

<p>
  <a href="https://twitter.com/iamtylerwclark">Tyler Clark</a>'s egghead course
  on{" "}
  <a href="https://egghead.io/courses/advanced-javascript-foundations">
    Advanced JavaScript Foundations
  </a>{" "}
  that was exactly that hole-filling opportunity for me.
</p>

As usual, I drew some notes...

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1580828081/maggieappleton.com/egghead-course-notes/advancedjs-notes/AdvancedJS_2_2x.png"
  alt="Advanced JavaScript foundations"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1580828082/maggieappleton.com/egghead-course-notes/advancedjs-notes/AdvancedJS_3_2x.png"
  alt="Advanced JavaScript foundations"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1580828081/maggieappleton.com/egghead-course-notes/advancedjs-notes/AdvancedJS_4_2x.png"
  alt="Advanced JavaScript foundations"
/>

<BasicImage
  width="900px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1580828081/maggieappleton.com/egghead-course-notes/advancedjs-notes/AdvancedJS_5.png"
  alt="Advanced JavaScript foundations"
/>

### Want more illustrated notes on web development?

Take a look at [[JavaScript's ...spread Operator]], [[Building Custom React Hooks]] or [[Fixing Common Git Mistakes]]


Illustrated notes on advanced but fundamental topics in JavaScript

JavaScript Bits You Skipped the First Time Around


<img
  width="500px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_500/v1591783100/maggieappleton.com/egghead-course-notes/custom-react-hooks/thumb_2x.png"
  alt="Objects hanging off a series of hooks"
/>

<IntroParagraph>

Last year the [React](https://reactjs.org/docs/hooks-intro.html) team released a feature called "hooks" that lets you do some powerful stuff we couldn't do as easily before... Managing state. Accessing DOM elements. Using side effects.

</IntroParagraph>

It's fair to say the React community had a collective melt-down over this. For the better part of 2019, hooks turned into an all-encompassing obsession.

Hooks came with a bunch of pre-made options, but also allowed you to remix the default options to create **custom hooks**

<ImageLink href="https://egghead.io/courses/shareable-custom-hooks-in-react">
  <ImageFrame
    width="800px"
    alt="Shareable Custom Hooks in React"
    src="https://og-image-egghead-course.now.sh/shareable-custom-hooks-in-react"
  />
</ImageLink>

<p>
  <a href="https://twitter.com/jsjoeio/">Joe Previte</a> made a whole egghead
  course on{" "}
  <a href="https://egghead.io/courses/shareable-custom-hooks-in-react/">
    Shareable Custom Hooks in React
  </a>
  . While working through the material I made a set of illustrated notes on the main
  ideas
</p>

<br />

<BasicImage
  width="1000px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1578937254/maggieappleton.com/egghead-course-notes/custom-react-hooks/customhooks-1.png"
  alt="Making shareable custom react hooks"
/>

<BasicImage
  width="1000px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1578937254/maggieappleton.com/egghead-course-notes/custom-react-hooks/customhooks-2.png"
  alt="Making shareable custom react hooks"
/>

<BasicImage
  width="1000px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1578937257/maggieappleton.com/egghead-course-notes/custom-react-hooks/customhooks-3.png"
  alt="Making shareable custom react hooks"
/>

<BasicImage
  width="1000px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1578937255/maggieappleton.com/egghead-course-notes/custom-react-hooks/customhooks-4.png"
  alt="Making shareable custom react hooks"
/>

<BasicImage
  width="1000px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1578937255/maggieappleton.com/egghead-course-notes/custom-react-hooks/customhooks-5.png"
  alt="Making shareable custom react hooks"
/>

### Want more illustrated notes on web development?

Take a look at [[What the Fork is React Suspense?]], [[Building VR Apps with React360]] or [[A Journey into Vue-Router]]


Illustrated notes on building custom React hooks

Building Custom React Hooks


<IntroParagraph>

Let's talk about **immutable data**. With socks. And personal assistant bots. I know, you're already so excited.

</IntroParagraph>

**Immutability** and **state** are two developer buzzwords it took me forever to "get."

Their underlying meanings aren't necessarily that complex. But it's tough to fully comprehend what they mean, and why they're important, until you see them in action.

[State](<https://en.wikipedia.org/wiki/State_(computer_science)>) just means the way an application is at a single point in time.

For example, if we've typed _"how does CSS grid work"_ into the search bar, and there are three checkboxes ticked, and we have a dropdown menu open that's the current "state" of things. If we close the menu that's a state change.

Behind the scenes in apps we have to account for every state an app could be in (which gets expontential very quicky). This is usually called ["managing state"](https://codeburst.io/state-management-in-javascript-15d0d98837e1) and appears to be a [neverending problem](https://medium.com/razroo/the-history-of-javascript-state-management-in-2019-161491d588ed)

> **Immutable State** is one approach to solving our complex state problem – it simply means making a second copy of things before you change them.

It's the same as copying and pasting a new _ImportantThing_Version2_Draft.md_ document before liberally changing enourmous chunks of it.
Then when you realise your poor editing choices and want to go back to the original version, it's there waiting for you.

Writing [immutable code](https://en.wikipedia.org/wiki/Immutable_object) is a [wildly](https://medium.com/tribalscale/understanding-immutability-fdd627b66e58) [popular](https://itnext.io/why-concept-of-immutability-is-so-damn-important-for-a-beginner-front-end-developer-8da85b565c8e) concept in general. And a good idea when you don't want to muck everything up.

---

Okay now you're all caught up on the jargon. Lets get to some illustrated notes.

These are from a course [Michel Weststrate](https://twitter.com/mweststrate) made about their elegant new tool [Immer](https://immerjs.github.io/immer/docs/introduction) – it helps handle manage immutable state in a sane way.

<ImageLink href="https://egghead.io/courses/immutable-javascript-data-structures-with-immer">
  <ImageFrame
    width="800px"
    alt="Immutable JavaScript Data Structures with Immer"
    src="https://og-image-egghead-course.now.sh/immutable-javascript-data-structures-with-immer?af=54fd64"
  />
</ImageLink>

Michel walks us through building a gifting app with React & Immer that seamlessly handles all the messy state work.

<BasicImage
  width="1100px"
  alt="Immer is a small JS library that makes working with immutable state easy and enjoyable. It's like a small assistant that helps you make copies and edits to documents."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262596/maggieappleton.com/egghead-course-notes/immer/immer-1.png"
/>

<BasicImage
  width="1100px"
  alt="Immer's produce function does all the work - it takes a state object and runs a draft function telling the state how it should change."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262597/maggieappleton.com/egghead-course-notes/immer/immer-2.png"
/>

<BasicImage
  width="1100px"
  alt="The product function supports currying - which is when we nest functions inside others to make our code composable"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262597/maggieappleton.com/egghead-course-notes/immer/immer-3.png"
/>

<BasicImage
  width="1100px"
  alt="We can easily use immer with other libraries like React and write callback functions using immer's produce function"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262596/maggieappleton.com/egghead-course-notes/immer/immer-4.png"
/>

<br />

<TwoColumn maxWidth="900px">

<BasicImage
  width="400px"
  alt="CSS is awesome cup"
  src="https://images-na.ssl-images-amazon.com/images/I/51graM2SdzL._SX466_.jpg"
/>

Yes the cup in the illustration is based on this classic CSS one that I don't own, but kind of want to.

</TwoColumn>

### Want more illustrated notes on web development?

Take a look at [[Testing Apps with Cypress]], [[The JAMStack, Gatsby & Contentful]] or [[A Fresh Serving of JavaScript ES2019]]


Illustrated notes on how work with immutable data in the Immer state library

Immutable Data with Immer and Personal Assistant Bots


<IntroParagraph>

G[raphQL](https://graphql.org/) is undoubtedly one of the popular kids on the Web Development playground right now. If you haven't heard of GraphQL, the TLDR is that it's a new way to request data from an API. <Footnote idName={1}>If you're unsure what an API is, head on over to my illustrated article on [WTF is an API?](/api)</Footnote> One that's easier, faster, better, and stronger than the old [RESTful API system](https://en.wikipedia.org/wiki/Representational_state_transfer)

</IntroParagraph>

<BasicImage
  width="400px"
  alt="Small GraphQL schema dictionary illustration"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_300/v15928510008/maggieappleton.com/egghead-course-notes/graphql/thumb_2x.png"
/>

If you're lucky enough to already grok GraphQL, you'll know the _QL_ stands for _Query Language_ – aka. the language we talk to our GraphQL API in.

It's not a terribly complex language, but you'll still need to do some syntax studying to get the hang of it.

Thankfully the magnificent [Eve Porcello](https://twitter.com/eveporcello) made an [egghead course](https://egghead.io/courses/graphql-query-language) that runs you through the full GraphQL vocabulary.

<ImageLink href="https://egghead.io/courses/graphql-query-language">
  <ImageFrame
    alt="Course illustration of a set of dictionary books with the word 'schema' across them"
    src="https://og-image-egghead-course.now.sh/graphql-query-language"
  />
</ImageLink>

It's a wonderful introduction for anyone new to the GraphQL ecosystem – Eve explains all the parts of the playground interface that are not in the least bit intuitive. I'd been stumbling about in my own GraphQL queries lost and afraid until I worked through this.

Anyways, as usual I drew some things:

<BasicImage
  width="750px"
  alt="How to talk to a GraphQL API. We can use the graphQL playground to send queries to a GraphQL endpoint. The playground lets us explore our data before making any requests"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1592262603/maggieappleton.com/egghead-course-notes/graphql/graphql1.png"
/>

<BasicImage
  width="1100px"
  alt="A query is a request for data. We open it with the query keyword and a set of curly braces. Curly braces wrap around a selection and say go look inside this object. Blank spaces at the end of a line are fields that say I want his data please. We can also add the 'total' and 'all' keywords in front of any list of objects."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1100/v1592262605/maggieappleton.com/egghead-course-notes/graphql/graphql4.png"
/>

<BasicImage
  width="800px"
  alt="Inside the playground, ctrl + space is a magic combination that reveals all the available fields of a query"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_800/v1592262603/maggieappleton.com/egghead-course-notes/graphql/graphql2.png"
/>

<BasicImage
  width="1100px"
  alt="We can filter our data by adding arguments to our queries. This means we only get the data we want. We can also use mutations to change the data. This includes creating, updating, and deleting data."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1100/v1592262604/maggieappleton.com/egghead-course-notes/graphql/graphql3.png"
/>

<BasicImage
  width="1100px"
  alt="The full GraphQL query language illustrated note"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262601/maggieappleton.com/egghead-course-notes/graphql/graphql_sketchnotes--mini.png"
/>

<Center>

## Bonus Poster

</Center>

Twitter kept bugging me to make prints out of these illustrated notes, so this one is now purchaseable as a real life object on the [egghead store](https://store.egghead.io/).

There's framed versions and unframed, depending on how fancy you feel. You can [buy one here](https://store.egghead.io/product/poster-graphql-query-language) if you so desire.

<TwoColumn gridGap="1em">

![a framed graphql illustrated print](https://store.egghead.io/static/ab87b8544078b8d5049501abf8b2eac7/e9055/thumb-graphql-query-language-by-eve-porcello_2x_dd5b8572-fca2-4c36-9e4e-d4bfc00a35fb.png)

![a close-up image of one section of the print](https://store.egghead.io/static/91261ff8c8395dbc141635030e138734/fd7f1/perspective_2x_420b9d42-49db-41ac-8aee-1b8fa25c56eb.png)

</TwoColumn>

### Want more illustrated notes on web development?

Take a look at [[A Fresh Serving of JavaScript ES2019]], [[The JAMStack, Gatsby & Contentful]] or [[Essential Web Security Tactics]]


Illustrated notes on the basics of the GraphQL query language

Speaking the GraphQL Query Language


<BasicImage
  width="700px"
  alt="New features in JavaScript ES2019"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_700/v1592262624/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-Title.png"
/>

## A new version of JavaScript has landed!

Every year JavaScript gets a handful of new features and functions for everyone to play with.

The [TC39 committee](https://tc39.es/) have released the 2019 additions to [ECMAScript](https://www.ecma-international.org/memento/tc39.htm), which is the generally accepted version of JavaScript we all know and ~~love~~ tolerate.

You can take a look at the [TC39 Github](https://github.com/tc39) to track the progress of proposed features, including all the ones they've [accepted into the official language](https://github.com/tc39/proposals/blob/master/finished-proposals.md).

I drew up my own notes on the 7 big changes below:

- Optional Catch Binding
- Stable `array.sort()`
- Flatten Arrays with `flat()`
- Flatten & Map Arrays with `flatMap()`
- Cut out Whitespace with `trimStart()` & `trimEnd()`
- Descriptions on Symbols
- Create Objects from Entries with `fromEntries()`

<BasicImage
  width="880px"
  alt="Gifts in the latest language update from the TC39 committee"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262624/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-Intro.png"
/>

<BasicImage
  width="840px"
  alt="Optional Catch Binding"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262622/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-1-Optional.png"
/>

<BasicImage
  width="840px"
  alt="Stable array.sort"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262624/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-2-Stable.png"
/>

<BasicImage
  width="840px"
  alt="Flatten Arrays with flat"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262621/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-3-Flatten.png"
/>

<BasicImage
  width="840px"
  alt="Flatten & Map Arrays with flatMap"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262623/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-4-FlatMap.png"
/>

<BasicImage
  width="840px"
  alt="Cut out Whitespace with trimStart & trimEnd"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262619/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-5-Trim.png"
/>

<BasicImage
  width="840px"
  alt="Descriptions on Symbols"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262622/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-6-Symbol.png"
/>

<BasicImage
  width="840px"
  alt="Create Objects from Entries with fromEntries"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262623/maggieappleton.com/egghead-course-notes/es2019/es2019-sketchnotes-7-ObjectEntries.png"
/>

These notes are all based off Mike Sherov's egghead course on [JavaScript ES2019 in Practice](https://egghead.io/courses/javascript-es2019-in-practice?af=54fd64) which is a good summary of all the new shiny bits, as well as how they apply in IRL dev situations.

<ImageLink href="https://egghead.io/courses/javascript-es2019-in-practice?af=54fd64">
  <ImageFrame
    alt="JavaScript ES2019 in Practice"
    src="https://og-image-egghead-course.now.sh/javascript-es2019-in-practice"
  />
</ImageLink>

### Want more illustrated notes on web development?

Take a look at [[JavaScript Bits You Skipped the First Time Around]], [[What the Fork is Babel?]] or [[JavaScript's ...spread Operator]]


Illustrated notes on the new language changes in JavaScript ES2019

A Fresh Serving of JavaScript ES2019


<IntroParagraph>

If you've been keeping up with the sweetest new static-site generation tools, you'll have heard of the JAMstack. <Footnote idName={1}>And if you havent, don't worry it's a niche web developer thing - <a href="https://jamstack.wtf/">Jamstack WTF</a> explains it pretty well.</Footnote>

</IntroParagraph>

The TLDR here is that combining JavaScript, APIs, and Markup (JAM) makes it easy to build sites that work well across all kinds of devices and data loading speeds. Which, like jam, makes everyone happy.

<BasicImage
  width="300px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_300/v1592855269/maggieappleton.com/egghead-course-notes/gatsby-contentful/thumb_2x.png"
  alt="A stack of jam toast"
/>

Two popular tools for building JAMstack sites are [Gatsby](https://www.gatsbyjs.org/) and [Contentful](https://www.contentful.com/). Gatsby is a framework for building the actual site, and Contentful is a Content Management System (CMS) - aka. where you stick all the images, text, and data.

[Khaled Garbaya](https://khaledgarbaya.net/) created a whole [egghead course](https://egghead.io/courses/build-content-rich-progressive-web-apps-with-gatsby-and-contentful) that walks you through hooking these two up

<ImageLink href="https://egghead.io/courses/build-content-rich-progressive-web-apps-with-gatsby-and-contentful?rc=272bjb">
  <ImageFrame
    alt="Course illustration of contentful media running into a Gatsby machine, for the Build Content Rich Progressive Web Apps with Gatsby and Contentful course"
    src="https://og-image-egghead-course.now.sh/build-content-rich-progressive-web-apps-with-gatsby-and-contentful"
  />
</ImageLink>

Here's some notes I took while working through it...

<BasicImage
  width="700px"
  alt="Build progressive web apps with contentful and gatsby"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_700/v1592262609/maggieappleton.com/egghead-course-notes/gatsby-contentful/gatsbycontentful1.png"
/>

<BasicImage
  width="950px"
  alt="The JAM stack is a new way to build web apps for speed and scalability. It uses JavaScript, APIs, and Markup."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1592262609/maggieappleton.com/egghead-course-notes/gatsby-contentful/gatsbycontentful2.png"
/>

<BasicImage
  width="950px"
  alt="These two work well together - contentful feeds the data into gatsby. You structure all your content inside contentful, which then goes into gatsby through the gatsby-source-contentful plugin."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1592262609/maggieappleton.com/egghead-course-notes/gatsby-contentful/gatsbycontentful3.png"
/>

<BasicImage
  width="950px"
  alt="We can create new pages for our site inside gatsby-node.js. The gatsby node API gives us a creatPage action"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_950/v1592262611/maggieappleton.com/egghead-course-notes/gatsby-contentful/gatsbycontentful4.png"
/>

<BasicImage
  width="1100px"
  alt="The full gatsby and contentful illustrated note"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1100/v1592262613/maggieappleton.com/egghead-course-notes/gatsby-contentful/gatsbycontentful_sketchnotes--mini.png"
/>

### Want more illustrated notes on web development?

Take a look at [[JavaScript Bits You Skipped the First Time Around]], [[Speaking the GraphQL Query Language]] or [[Fixing Common Git Mistakes]]


Illustrated notes on the JAMstack, Gatsby & Contentful

The JAMStack, Gatsby & Contentful


<IntroParagraph>

The _intantness_ of chat apps has always been a mystery to me.  
The technical details of moving emojis through The Internet Pipes and across continents in 0.004 miliseconds is well beyond my paygrade.

</IntroParagraph>

But I got a tiny window of insight into the magic while illustrating notes for [Mark Barton's course](https://egghead.io/courses/vue-and-socket-io-for-real-time-communication) on building chat apps with [Vue](https://vuejs.org/) and [Socket.io](https://socket.io/)

<ImageLink href="https://egghead.io/courses/vue-and-socket-io-for-real-time-communication">
  <ImageFrame
    alt="Course illustration of a Vue logo and multiple chat bubble floating above it"
    src="https://og-image-egghead-course.now.sh/vue-and-socket-io-for-real-time-communication"
  />
</ImageLink>

Turns out it's not magic, but instead done through [websockets](https://en.wikipedia.org/wiki/WebSocket). Which are like little portals that hold open a consistent connection between two machines.

I obviously still haven't a clue what goes on inside that dark little portal. Thankfully using tools like Vue & Socket.io save us from that level of depth.

<BasicImage
  width="700px"
  alt="Vue and socket.io for real-time communication"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_700/v1592262571/maggieappleton.com/egghead-course-notes/vuesocket/vuesocket1.png"
/>

<BasicImage
  width="900px"
  alt="Socket.io gives us bidirectional communication between two clients"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262575/maggieappleton.com/egghead-course-notes/vuesocket/vuesocket2.png"
/>

<BasicImage
  width="800px"
  alt="The emit method lets us send and recieve any knd of event. We can target specific users or a group of users"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_800/v1592262574/maggieappleton.com/egghead-course-notes/vuesocket/vuesocket3.png"
/>

<BasicImage
  width="1100px"
  alt="The full vue and socket sketchnote"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1100/v1592262568/maggieappleton.com/egghead-course-notes/vuesocket/vuesocket_sketchnotes--mini.png"
/>

### Want more illustrated notes on web development?

Take a look at [[Essential Web Security Tactics]], [[Speaking the GraphQL Query Language]] or [[A Fresh Serving of JavaScript ES2019]]


Illustrated notes on how to implement web sockets with Vue.js and Socket.io

Instachatting with Vue & Socket.io


<IntroParagraph>

Turns out you can build almost anything in React now... including VR and AR apps inside a web browser. There's a version of React called [React 360](https://facebook.github.io/react-360/) that simplifies the otherwise niche and overly-complex challenge of making things fly around in virtual 3D space.

</IntroParagraph>

<BasicImage
  width="500px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,f_auto,q_auto:good,w_500/v1592262587/maggieappleton.com/egghead-course-notes/react360/thumb_2x.png"
  alt="3D objects flying out of a browser"
/>

[Tomasz Lakomy](https://egghead.io/instructors/tomasz-lakomy) made an entire egghead course that walks you through building [VR Applications Using React 360](https://egghead.io/courses/vr-applications-using-react-360).

<ImageLink href="https://egghead.io/courses/vr-applications-using-react-360">
  <ImageFrame
    alt="Course illustration of objects in 3D space"
    src="https://og-image-egghead-course.now.sh/vr-applications-using-react-360"
  />
</ImageLink>

Here's all my illustrated notes on the material.

<BasicImage
  width="750px"
  alt="VR apps with React 360"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1592262587/maggieappleton.com/egghead-course-notes/react360/react360_p1_2x.png"
/>

<BasicImage
  width="900px"
  alt="Let's us build 3D and VR apps on the web - without needing to learn crazy complex tools like WebGL. Instead we can just use React"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262588/maggieappleton.com/egghead-course-notes/react360/react360_p2_2x.png"
/>

<BasicImage
  width="1000px"
  alt="Uses flexbox for layouts. On the web it flexes across rows by default. But in VR it flexes downwards in a stacked columns. To add CSS styles to our views, we make a special React 360 stylesheet and then we pass them to the style tag"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1000/v1592262589/maggieappleton.com/egghead-course-notes/react360/react360_p3_2x.png"
/>

<BasicImage
  width="800px"
  alt="Add 3D models to your components with the Entity tag. We can apply CSS transforms to these"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_800/v1592262587/maggieappleton.com/egghead-course-notes/react360/react360_p4_2x.png"
/>

<BasicImage
  width="1100px"
  alt="The full React 360 illustrated note"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_1000/v1592262590/maggieappleton.com/egghead-course-notes/react360/react360_full_2x.png"
/>

### Want more illustrated notes on web development?

Take a look at [[Building Custom React Hooks]], [[Speaking the GraphQL Query Language]] or [[What the Fork is React Suspense?]]


Illustrated notes on building VR web apps with React360

Building VR Apps with React360


<IntroParagraph>

Illustrated notes on [Brett Cassette](http://twitter.com/brettcassette)'s egghead course all about testing apps with [Cypress.io](https://www.cypress.io/).

</IntroParagraph>

<ImageLink href="https://egghead.io/courses/test-production-ready-apps-with-cypress?af=54fd64">
  <ImageFrame
    alt="Test Production Ready Apps with Cypress"
    src="https://og-image-egghead-course.now.sh/test-production-ready-apps-with-cypress"
  />
</ImageLink>

<BasicImage
  width="750px"
  alt="Cypress.io is a handy tool for end to end testing"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_750/v1592262637/maggieappleton.com/egghead-course-notes/cypress/CyTesting01_2x.png"
/>

<BasicImage
  width="860px"
  alt="It includes all levels of the stack - from the UI to front-end data stores, to XHR, to APIs, to your database. It's able to test all of these at the same time. It runs a virtual browser that clicks through all the things on all the pages"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_860/v1592262636/maggieappleton.com/egghead-course-notes/cypress/CyTesting02_2x.png"
/>

<BasicImage
  width="860px"
  alt="It lets us write custom tests that assert true or false statements on specific parts of our app. It also alerts us if any of those tests fail. The tool uses the chai assertion library which makes it easy to write chains of selectors."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_860/v1592262637/maggieappleton.com/egghead-course-notes/cypress/CyTesting03_2x.png"
/>

### Want more illustrated notes on web development?

Take a look at [[The JAMStack, Gatsby & Contentful]], [[A Fresh Serving of JavaScript ES2019]] or [[A Fruitful Guide to JavaScript's Comparison Operators]]


Illustrated notes on how to test web apps with Cypress

Testing Apps with Cypress


After learning about [[Babel]], I stumbled into the "is Babel a compiler or a transpiler?" debate. To help clarify things, I did a little research and illustrated it.

<BasicImage
    width="860px"
    alt="Compilers and Transpilers"
    src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262869/maggieappleton.com/egghead-course-notes/Compile_Transpile_Final.png"
/>


Illustrated notes on how compilers and transpilers are different

How Are Compilers & Transpilers Different?


<BasicImage
  width="400px"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_400/v1592833720/maggieappleton.com/egghead-course-notes/fruit-comparison/thumb_2x.png"
  alt="One small apple being compared to a large pile of apples"
/>

<IntroParagraph>

Comparing values is one of those essential developer skills that helps you write **conditionals**, **if / then statements, filters**, and plenty more. Here's the apples and oranges guide to using them in JavaScript.

</IntroParagraph>

<img
  alt="JavaScript's comparison operators give us a way of comparing values"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262865/maggieappleton.com/egghead-course-notes/fruit-comparison/FruitComparison_P1.png"
/>

<img
  alt="Equality comes in loose and strict varieties. You should always use strict equality."
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262864/maggieappleton.com/egghead-course-notes/fruit-comparison/FruitComparison_P2.png"
/>

<img
  alt="Inequality follows the same loose and strict rules as equality"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262862/maggieappleton.com/egghead-course-notes/fruit-comparison/FruitComparison_P3.png"
/>

<img
  alt="Relational equality let's us check which value is greater"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262863/maggieappleton.com/egghead-course-notes/fruit-comparison/FruitComparison_P4.png"
/>

### Want more illustrated notes on web development?

Take a look at [[JavaScript Bits You Skipped the First Time Around]], [[JSX is a Lovechild]] or [[JavaScript's ...spread Operator]]


Illustrated notes on how JavaScript's comparison operators work

A Fruitful Guide to JavaScript's Comparison Operators


<IntroParagraph>

If you've build anything on the modern web, you've used [Babel](https://babeljs.io/). Nothing works without it. When I first started learning web development I didn't pay much attention to it. But once I got deeper into learning [[JSX]] and React (more on that in my [[React is a Potato]] talk) and I needed a to understand what was up with the all the `.babelrc` files in my projects.

</IntroParagraph>

Here's my quick one-shot summary of it:

<BasicImage
  width="860px"
  alt="Babel is a translator that turns different varieties of JS into ES5 - a commonly shared version"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262873/maggieappleton.com/egghead-course-notes/Babel_Final_Sm_2x.png"
/>

A good follow-up read is [[How Are Compilers & Transpilers Different?]]


What the Fork is Babel?


If you've had the pleasure of trying to stumble your way through learning React, you'll have been through the adjustment phase with JSX. Putting HTML and JS side-by-side feels like it's violating the internet rules at first. It's just a new mashup - an awkward lovechild.

<BasicImage
  width="950px"
  alt="JSX is like the lovechild of HTML and JS. It mixes the best of both worlds"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262858/maggieappleton.com/egghead-course-notes/JSX_Final_2x.png"
/>

### Want more illustrated notes on web development?

Take a look at [[JavaScript's ...spread Operator]], [[A Fruitful Guide to JavaScript's Comparison Operators]] or [[A Fresh Serving of JavaScript ES2019]]


Illustrated notes on how JSX in React works

JSX is a Lovechild


<BasicImage
  width="550"
  alt="A drawing of the react logo and two browser windows stacked on top of each other"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_400/v1592834724/maggieappleton.com/egghead-course-notes/react-vdom/thumb_2x.png"
/>

<br />

<IntroParagraph>

When I was first [[learning React]] I couldn't quite wrap my head around why it was any different to JavaScript.

</IntroParagraph>

The idea of the virtual DOM system helped clarify a few things for me. Primarily it got me to understand the DOM, the virtual DOM, and your React app are all separate systems talking to one another. Not one big mesh. While learning it I drew out an explanation you can see below.

<br />

<Alert>

## Disclaimer

The React team no longer uses the **"Virtual DOM"** as a mental model for how React works under the hood.

<TweetEmbed tweetId="1066328666341294080" />

Instead Dan wrote up a nice long explanation on <a href="https://overreacted.io/react-as-a-ui-runtime/">React as a UI Runtime</a> which clarifies the details how React updates the UI.

They still have a section of the docs about the [Virtual DOM](https://reactjs.org/docs/faq-internals.html), but it's not an essential piece of the React ecosystem to learn about.

The below explanation will still help you understand the basic concept that React figures out what needs to change on the DOM before changing it, but go to other sources if you want a more in-depth explanation.

</Alert>

<img
  alt="One of the reasons React is so darn fast at updating changes  is that it uses a virtual DOM"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262854/maggieappleton.com/egghead-course-notes/react-vdom/ReactVDom_1_2x.png"
/>

<img
  alt="All the code we write in React only interacts with this virtual DOM"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262852/maggieappleton.com/egghead-course-notes/react-vdom/ReactVDom_2_2x.png"
/>

<img
  alt="This is helpful because passing the actual DOM lots of changes is slow"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262852/maggieappleton.com/egghead-course-notes/react-vdom/ReactVDom_3_2x.png"
/>

<img
  alt="React's DOM runs a diffing algorithm"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/v1592262854/maggieappleton.com/egghead-course-notes/react-vdom/ReactVDom_4_2x.png"
/>

### Want more illustrated notes on web development?

Take a look at [[Building Custom React Hooks]], [[JSX is a Lovechild]] or find out [[What the Fork is Babel?]]


Illustrated notes on how the React virtual DOM works

What the Fork is the React Virtual DOM


<IntroParagraph>

Spreading the elements from one array and copying them into is one of those handy shorthands for moving data around in JavaScript.

</IntroParagraph>

I started looking into it after seeing `<ComponentName {...props} />` in lots of React projects, and couldn't figure out what on earth was going on with the props syntax.

Mystery solved...

<img
  alt="JavaScript's spread operator copies the content of one array, and dumps them out into another"
  src="https://res.cloudinary.com/dg3gyk0gu/image/upload/c_scale,w_900/v1592262848/maggieappleton.com/egghead-course-notes/Spread.png"
/>

### Want more illustrated notes on web development?

Take a look at [[JSX is a Lovechild]], [[How Are Compilers & Transpilers Different?]] or [[A Fruitful Guide to JavaScript's Comparison Operators]]


Illustrated notes on how JavaScript's spread operator works

JavaScript's ...spread Operator


<h2 className="micro">The Context</h2>

Our web browsing experience hasn't changed much over the last three decades.

Here's Mosaic, the first browser that made the web popular outside niche academic circles. Built in 1993, its _"killer feature"_ was inline images.<Footnote idName={1}>As opposed to images you had to download and open in a separate window</Footnote>

<ImageFrame
  width="900px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_900/v1642358019/maggieappleton.com/patterns/moasic_fxat9i.png"
  alt="The Mosaic web browser interface in 1993"
/>

And here's Chrome, currently the most widely used browser, 29 years later:

<ImageFrame
  width="1100px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1100/v1642358018/maggieappleton.com/patterns/chrome_wbjk5d.png"
  alt="The Chrome browser interface from 2019"
/>

On the surface, not much has changed. The layouts, icons, and button arrangement haven't moved. Address bar at the top. Arrow icons to move between pages. Access to the same basic controls; print, refresh, save, and search.

Modern Chrome certainly gained the veneer of minimalist modern design; we've reduced the interface to a low-contrast sea of whitespace. It's also vastly more powerful; 1993 Mosaic certainly couldn't load 20 tabs running WebGL animations.

But from a user's perspective, the core browsing experience isn't different. Enter URL, load the page, click on links, move forwards and backwards in browser history. We can only see one website at a time, or max two if we stack our browser windows in columns.

Chrome and Mosaic are not uniquely similar. All the major characters in this browser drama – Firefox, Safari, Opera, and Internet Explorer/Edge – feel like they're wearing the same outfit.

This historical consistency is impressive. Perhaps it means we nailed this interface pattern on the first try. Or perhaps it means building browsers is an enourmously complex challenge, and the only companies with enough engineering resources to dedicate towards it aren't interested in mucking about. They're too busy keeping up with W3C web standards and negotiating cross-compatability concerns, leaving little room for experimental interface patterns.

This isn't for lack of want though. There have been plenty of calls to _"reinvent"_ the browser. Places like [The Browser Company](https://thebrowser.company/) make a lot of noise about it (but we've yet to see a product demo). Foundations like Mozilla have funded extensive [experimental explorations](http://patrykadas.com/browser.html) of alternative browsers.

There's a steady stream of ideas and speculative sketches floating around Twitter that prompt us to reconsider our browsery assumptions and ask good design questions:

<TweetEmbed tweetId="1418749070336684034" />

<TweetEmbed tweetId="1450479522609090562" />

<TweetEmbed tweetId="1256317316452810755" />

The dreams in some of these speculative suggestions are starting to materialise.

<Spacer />

<h2 className="micro">The Pattern</h2>

There are some new apps appearing that offer alternative ways of browsing the web, but sidestep the problem of needing to build an entire browser.

Through the use of `<iframe>` embeds (or sometimes darker magic like live-updating screenshots in `<img>` tags), these apps are creating a form of web inception; allowing us to embed tiny browser windows inside a larger canvas. <Footnote idName={2}>This is a tricky as many websites deny access if they're embedded inside other webpages. This isn't out of malice; they're trying to protect themselves from cross-site scripting attacks</Footnote>

This canvas-based approach adds _spatial_ dimension to the web browsing experience; they allow us to arrange browser windows above, below, to the left, and right of other browser windows.

The same way we're able to put an open book next to a piece of paper and below a row of sticky notes in meatspace. Arranging objects in space to create groupings, indicate relationships, and build hierarchies is one of those classical human skills that never goes out of style.

#### Spatial Browsing Apps

1. [Kosmik](https://lithium.paris/) is a canvas-based note-taking app for iOS and Mac app that includes frames for web browsing. It's still in early development, but as a native app it doesn't seem to have the same cross-site blocking issues as web apps.

<ImageFrame
  width="1200px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1642582738/maggieappleton.com/patterns/kosmik_rm0rpy.jpg"
  alt="A Kosmik canvas with three open browsers arranged next to one another"
/>

2. [Nette](https://www.nette.io/) is a browsing app designed for researchers that allows you to open multiple browser windows, draw physical connections between frames, pull out key concepts, and write markdown notes directly into your canvas. <Footnote idName={3}>Still pre-release but looking promising</Footnote>

<ImageFrame
  width="1200px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1642543667/maggieappleton.com/patterns/nette_kjqsgj.jpg"
  alt="A Nette canvas with open browsers, diagrams, and notes arranged next to one another"
/>

3. [Sprout](https://sprout.place/) is designed with social interaction in mind – an open, multiplayer canvas where you can video/voice chat, write notes, and browse webpages together. It cleverly sidesteps the issue of cross-site blocking by using screenshots in `<img>` tags instead of true `<iframe>` elements.

<ImageFrame
  width="1200px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1642543667/maggieappleton.com/patterns/sprout_ffcyrn.jpg"
  alt="A Sprout canvas with two open browsers arranged next to one another"
/>

4. [Natto.dev](https://natto.dev/) isn't designed to be a browsing or knowledge management app, but inadvertently implements this pattern. It's a spatial canvas for programming that happens to allow HTML elements, such as `<iframe>`:

<ImageFrame
  width="1200px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/c_scale,f_auto,q_auto:good,w_1200/v1642543667/maggieappleton.com/patterns/natto_cfqkov.jpg"
  alt="A Natto canvas with three open browsers arranged next to one another"
/>

All of these examples allow you to add different blocks and elements to your canvas other than simply browsers. This turns the interface into a true research space. You can add notes, images, and links connected to these browsers – pulling out information in order to arrange it in ways that make sense to you.

At least... in theory. The above platforms are promising, but they're all at beta/alpha stage for the moment. They're worth playing with, but not stable enough to build up an extensive database of notes and browser trails in.

We're so close though. Here's to hoping we have widely useable spatial browsing tools within the next year or two.

#### Postscript

I should touch on the impulse to bring in even more dimensions here. When you search for "_spatial web browsing_," you'll find there are whole engineering teams trying to stick web browsers on [walls within 3D AR/VR](https://venturebeat.com/2021/05/13/spatial-unveils-web-browser-collaboration-in-3d-workspace-and-nft-virtual-galleries/) environments. To me this feels like putting the cart before the poorly rendered, nausea-inducing horse, given we haven't built tools to properly browse the web in 2D space yet.

<References>
  <ReferencesLink
    title="Browser.html speculative research"
    href="http://patrykadas.com/browser.html"
    author="Patryk Adas"
  />
  <ReferencesLink
    title="Spatial Interfaces"
    href="https://darkblueheaven.com/spatialinterfaces/"
    author="John Palmer"
  />
  <ReferencesLink
    title="Spatial Software"
    href="https://darkblueheaven.com/spatialsoftware"
    author="John Palmer"
  />
</References>


Adding spatial affordances to the experience of browsing the web

Spatial Web Browsing


<AssumedAudience>
  Active readers and writers of the web. Particularly ones frustrated by context
  collapse and the proliferation of generic articles that try to accomodate
  every possible audience online
</AssumedAudience>

<h2 className="micro">The Context</h2>

Readers are a problem for every writer. Writers have to write for a specific person. That specific person is almost always imaginary. Anytime you put writing in public, posted somewhere a vast range of people might happen upon it, imagining the reader becomes an exercise in desperate speculation.

Who is truly reading this? I haven't a clue.

All I can do it guess. I have to _assume_ things about you. Assumptions I make based off the other people my Twitter neighbourhood and extended gardening network.

This includes how much you know about the history of hypertext. Whether you're caught up on the latest JavaScript framework gossip. How much you can tell me about embodied cognition and its role in interface design. Whether you know who Clifford Geertz, Bret Victor, Ted Nelson, and George Lakoff are.

If I assume incorrectly, I'll lose you in the middle of a sentence – either because I'll assume you know more than you do, and drown you in unfamiliar words and alienating jargon. Or I'll assume too little and bore you with basic, repetitive definitions of things you personally helped invent.

If I don't make clear who I'm writing for, and you don't know who should be reading this, we're far more likely to end up in an unsatisfying reader/writer mismatch.

<Spacer size="small" />

<h2 className="micro">The Pattern</h2>

At the beginning of many of my posts, I have a small informational box that tells you my **assumed audience** – who I think I'm writing this piece for.

A few examples to illustrate the point:

<AssumedAudience>
  JavaScript developers who have some familiarity with data visualisation,
  interactive narratives, and/or scrollytelling articles.
</AssumedAudience>

<AssumedAudience>
  People who understand the basic historical arc of postmodernism,
  post-postmodernism, the rationalist movement, and the post-rationalists. Would
  describe yourself as Very Online.
</AssumedAudience>

These small boxes free both of us of unspoken obligations and expectations. As the writer, I am now free to write for an informed audience without defining every term and qualifying every statement. We can jump straight to the gritty details and contentious debates rather than doing a full literature review of the field.

You still might no have a clue what I'm talking about, but you were forewarned. You have chosen to venture into this article as a bemused voyeur – willing to sacrifice comprehension to feed your curiosity.

The same way you might eavesdrops on a conversation between two Dev Ops engineers vehemently fighting over the practicality of kubernetes. None of us know what they're saying, but the jargon is to die for.

<References>
  <ReferencesLink
    title="Assumed Audience: everyone on the internet"
    href="https://v4.chriskrycho.com/2018/assumed-audiences.html"
    author="Chris Krycho"
  />
</References>


Naming your invisible audiences to free yourself from unspoken obligations

Assumed Audiences


<h2 className="micro">The Context</h2>

For most of the words we read online, we have a limited amount of context about the writer and how much effort they've put into the piece we're reading.

We might have a name and tiny 32px profile image. We don't know how long it took them to write these words, how many hundreds of tabs they read through, or whether they spent years earning a graduate degree on the topic. We rarely have a rich backstory with a comprehensive educational and professional history at hand.

If we disagree with their points, we're more likely to be ungenerous Epistemic Peers who assume the worst: they've barfed this garbage up in a single, frenzied caffeine rush and haven't so much as opened Google Scholar to check for prior art.

That might all be true. Which is fine. As long as they _disclose_ the situation up front. The only true source of dissapointment – in both reading and life – is unmet expectations.

<Spacer size="small" />

<h2 className="micro">The Pattern</h2>

At the beginning of a piece of writing, the author writes a sentence or two about the **epistemic status** of the work. _Epistemology_ is the study of knowledge – how we know things, the methods we use to gain knowledge, and how we validate knowledge as "true." So an _epistemic status_ usually covers how the author came to know what they know. This includes how much effort they put into researching it, how they validated the information, and how sure they are about their conclusions.

Scott Alexander of [Slate Star Codex](https://slatestarcodex.com/) was one of the earliest well-known bloggers to do this. Many of his posts include statuses that range from "total conjecture" to "pretty good, but I make no claim this is original." Here's a few more choice examples:

<ImageFrame
  style={{ margin: "0 auto 1rem" }}
  width="900px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1641161435/maggieappleton.com/patterns/epistemic1_w0umsf.png"
  alt="A Scott Alexander post with the epistemic status more crackpottish than usual"
/>

<ImageFrame
  style={{ margin: "0 auto 1rem" }}
  width="900px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1641161787/maggieappleton.com/patterns/epistemic2_syifue.png"
  alt="A Scott Alexander post with the epistemic status very speculative"
/>

<ImageFrame
  style={{ margin: "0 auto 2rem" }}
  width="900px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1641161787/maggieappleton.com/patterns/epistemic3_meynmd.png"
  alt="A Scott Alexander post with the epistemic status very speculative and not necessarily endorsed"
/>

[Gwern](https://www.gwern.net/) is another blogger who adds rich metadata to each post. They have a numerical "certainty" rating on each post:

<ImageFrame
  style={{ marginTop: 0 }}
  width="900px"
  src="https://res.cloudinary.com/dxj9qr5gj/image/upload/v1641198514/maggieappleton.com/patterns/gwernepistemic_1_jpo0dp.png"
  alt="A Gwern post on spaced repetition with a certainty rating of highly likely"
/>

The rationalist and Effective Altruist communities have been particularly enthusiastic about the pattern. In true Rationalist style, one person write up a comprehensive proposal to [standardize epistemic statuses](https://www.reddit.com/r/LessWrong/comments/eesr4y/a_proposal_for_standardizing_epistemic_status/) on the r/LessWrong subreddit.

<References>
  <ReferencesLink
    title="Epistemic Effort on LessWrong"
    href="https://www.lesswrong.com/posts/oDy27zfRf8uAbJR6M/epistemic-effort"
    author="Raemon"
  />
  <ReferencesLink
    title="Epistemic Statuses are Lazy and that is a Good Thing"
    href="https://devonzuegel.com/post/epistemic-statuses-are-lazy-and-that-is-a-good-thing"
    author="Devon Zuegal"
  />
</References>


Maggie makes visual essays about programming, design, and anthropology.

Designer, illustrator, anthropologist, and mediocre developer
Currently leading design at
HASH

The Garden

Essays

A Brief History & Ethos of the Digital Garden

How to Draw Invisible Programming Concepts: Part I

A Short History of Bi-Directional Links

Transclusion and Transcopyright Dreams

Notes

The Eponymous Laws of Programming

Neologisms

Frequently Asked Questions

The Finest Narrative Non-Fiction Essays

A Picture Worth a Thousand Programmes

Pink, Soft, Glittering Developers

The Best Illustration Books and Courses

Tools for Thought as Cultural Systems, not Computational Objects

Pattern Languages in Programming and Interface Design

The Cultural Anthropology of React

A Meta-Tour of This Site

Tracking Humanity

Patterns

Spatial Web Browsing

Assumed Audiences

Epistemic Disclosure

Algorithmic Transparency

Library

Projects

Gatsby Theme Jam

New Harvest 2019 Conference

Egghead Courses