feat: add notes section

SKalt · SKalt · commit ae34f7602fdb · 2024-03-23T15:15:28.000-04:00
diff --git a/content/notes/_index.md b/content/notes/_index.md
@@ -0,0 +1,6 @@
+---
+draft: false
+title: Notes
+---
+
+# Notes
diff --git a/content/notes/culture/_index.md b/content/notes/culture/_index.md
@@ -0,0 +1,3 @@
+---
+title: Culture, communications, and management
+---
diff --git a/content/notes/culture/architecture_md.md b/content/notes/culture/architecture_md.md
@@ -0,0 +1,30 @@
+---
+link: https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html
+title: ARCHITECTURE.md
+date: 2021-02-06
+tags:
+  - documentation
+---
+
+TL;DR:
+
+- add an `ARCHITECTURE.md` document to make contributing to your codebase easier for newcomers
+- A high-level map of the codebase architecture helps newcomers find where to start reading
+- An `ARCHITECTURE.md` document should cover:
+  - how different sections of the codebase work _together_
+  - things that don't change often (once or twice a year at most)
+
+<!-- more -->
+
+> _Do_ name important files, modules, and types.
+> _Do not_ directly link them (links go stale).
+
+I'm optimistic that CI hooks using [`lychee(1)`](https://github.com/lycheeverse/lychee) can prevent links from going stale, and I like linking directly to the code.
+However, it's up to a team to decide if the convenience of direct links is worth the chore of fixing them.
+
+> Explicitly call-out architectural invariants.
+> Often, important invariants are expressed as an absence of something, and it’s pretty hard to divine that from reading the code.
+> [...]
+> Point out boundaries between layers and systems as well.
+
+In other words, when you're deciding "what modules have what responsibilities", `ARCHITECTURE.md` might be a good place to document those decisions.
diff --git a/content/notes/culture/boring_tech.md b/content/notes/culture/boring_tech.md
@@ -0,0 +1,13 @@
+---
+link: https://boringtechnology.club/
+title: Use Boring Technology
+date: 2018-01-01
+tags:
+  - architecture
+  - culture
+---
+
+TL;DR:
+
+- Use tech your team is familiar with if it gets the job done
+- shiny new tech has lots of unknown unknowns
diff --git a/content/notes/culture/executive_role.md b/content/notes/culture/executive_role.md
@@ -0,0 +1,11 @@
+---
+link: https://apenwarr.ca/log/20190926
+title: What do executives do, anyway?
+date: 2019-09-26
+---
+
+TL;DR:
+
+> "to define and enforce culture and values for their whole organization, and to ratify good decisions."
+>
+> That's all.
diff --git a/content/notes/culture/how_to_ask_good_questions.md b/content/notes/culture/how_to_ask_good_questions.md
@@ -0,0 +1,24 @@
+---
+link: https://jvns.ca/blog/good-questions/
+date: 2016-12-31
+title: How to ask good questions
+tags:
+  - culture
+---
+
+TL;DR:
+
+- do research
+- state what you know
+- ask factual questions
+
+<!-- more -->
+
+<!--
+My personal recipe for a good **debugging** question is:
+
+1. what I observed that surprised me (e.g. something **specific** not working)
+1. state hypothesis (e.g. what I thought might be wrong)
+1. how I tested the hypothesis (e.g. what docs/people I consulted, what tests I ran -- and the results I got!)
+1. either where to look next or alternate hypotheses
+-->
diff --git a/content/notes/culture/is_it_worth_the_time.md b/content/notes/culture/is_it_worth_the_time.md
@@ -0,0 +1,7 @@
+---
+title: Is It Worth the Time?
+link: https://xkcd.com/1205/
+date: 2013-04-29
+---
+
+TL;DR: quickly calculate how much time you'd save before automating a task.
diff --git a/content/notes/culture/no_hello.md b/content/notes/culture/no_hello.md
@@ -0,0 +1,10 @@
+---
+link: https://nohello.net
+title: No Hello
+date: 2020-06-16
+tags:
+  - communications
+  - humor
+---
+
+TL;DR: Instead of texting "hi" and waiting for a response, say "hi" and ask your question in one message.
diff --git a/content/notes/humor/_index.md b/content/notes/humor/_index.md
@@ -0,0 +1,3 @@
+---
+title: Humor
+---
diff --git a/content/notes/humor/aws_iam.md b/content/notes/humor/aws_iam.md
@@ -0,0 +1,6 @@
+---
+title: How it feels to use AWS
+link: https://www.youtube.com/watch?v=xeQCRKXiRpo&t=290s
+---
+
+TL;DW: an enormous speed boost followed immediately by crashing straight into IAM's guardrails.
diff --git a/content/notes/humor/grug_brain.md b/content/notes/humor/grug_brain.md
@@ -0,0 +1,9 @@
+---
+link: https://grugbrain.dev/
+title: The Grug-Brained Developer
+date: 2022-07-22
+tags:
+  - humor
+---
+
+TL;DR: we're all operating on the same hardware that cavemen operated on. Here's one modern caveman distilling lessons any caveman can understand based from a career in software development.
diff --git a/content/notes/humor/mickens_usenix_keynote.md b/content/notes/humor/mickens_usenix_keynote.md
@@ -0,0 +1,13 @@
+---
+title: Why Do Keynote Speakers Keep Suggesting That Improving Security Is Possible?
+link: https://www.youtube.com/watch?v=ajGX7odA87k&t=2839s
+date: 2018-08-16
+tags:
+  - security
+  - humor
+  - ai
+  - ml
+  - talk
+---
+
+TL;DR: an in-depth talk by tenured Harvard professor James Mickens describing why unexplainable ML models will **always** be a security risk.
diff --git a/content/notes/humor/microservices.md b/content/notes/humor/microservices.md
@@ -0,0 +1,9 @@
+---
+title: microservices
+link: https://youtu.be/y8OnoxKotPQ
+date: 2020-03-25
+tags:
+  - humor
+---
+
+TL;DR: a video of a typical microservices architecture meeting.
diff --git a/content/notes/laws/_index.md b/content/notes/laws/_index.md
@@ -0,0 +1,3 @@
+---
+title: '"Laws"'
+---
diff --git a/content/notes/laws/conways_law.md b/content/notes/laws/conways_law.md
@@ -0,0 +1,7 @@
+---
+link: https://en.wikipedia.org/wiki/Conway%27s_law
+date: 1967-01-01
+title: "Conway's law"
+---
+
+> Organizations tend to produce designs which mimic their internal communication structure
diff --git a/content/notes/laws/hyrums_law.md b/content/notes/laws/hyrums_law.md
@@ -0,0 +1,12 @@
+---
+link: https://www.hyrumslaw.com/
+title: "Hyrum's Law"
+date: 2020-01-01
+---
+
+> With a sufficient number of users of an API,
+> it does not matter what you promise in the contract:
+> all observable behaviors of your system
+> will be depended on by somebody.
+
+See also: https://xkcd.com/1172/
diff --git a/content/notes/laws/linuses_law.md b/content/notes/laws/linuses_law.md
@@ -0,0 +1,11 @@
+---
+title: Linus's law
+date: 2001-01-01
+link: https://writing.kemitchell.com/2022/12/06/This-Rich-to-Open-Source
+---
+
+> A "hacker" is a person who has gone past using his computer for survival ("I bring home the bread by programming") to the next two stages [("social life," and "entertainment")].
+>
+> -- Linus Torvalds in "What Makes Hacker’s Tick? a.k.a Linus’s Law", prologue to Pekka Himanen’s The Hacker Ethic, 2001
+
+See also: [This Rich to Open Source (2022)](https://writing.kemitchell.com/2022/12/06/This-Rich-to-Open-Source)
diff --git a/content/notes/laws/raymonds_linuses_law.md b/content/notes/laws/raymonds_linuses_law.md
@@ -0,0 +1,16 @@
+---
+title: "Raymond's Linus's Law"
+date: 1999-01-01
+link: https://www.goodreads.com/book/show/134825.The_Cathedral_the_Bazaar
+---
+
+In _The Cathedral and the Bazaar_, Eric S. Raymond wrote:
+
+> Linus [Torvalds] was behaving as though he believed something like this:
+>
+> > Given a large enough beta-tester and co-developer base, almost every problem will be characterized quickly and the fix is obvious to someone.
+>
+> or, less formally, "Given enough eyeballs, all bugs are shallow."
+>
+> I dub this: "Linus's Law"
+
diff --git a/content/notes/papers/_index.md b/content/notes/papers/_index.md
@@ -0,0 +1,3 @@
+---
+title: Papers
+---
diff --git a/content/notes/papers/build_systems_a_la_carte.md b/content/notes/papers/build_systems_a_la_carte.md
@@ -0,0 +1,13 @@
+---
+link: https://www.microsoft.com/en-us/research/publication/build-systems-la-carte/
+title: "Build Systems a la Carte"
+date: 2018-09-01
+---
+
+TL;DR: All build systems vary on the following axes:
+
+- when the build system learns about dependencies (in the build specification or after doing some work)
+- what information the system stores about previous builds
+- where information about previous builds can be stored
+- how build steps are scheduled (e.g. suspending, restarting, start-to-finish)
+- whether the system does the minimum amount of work to build each artifact
diff --git a/content/notes/papers/prettier_printer.md b/content/notes/papers/prettier_printer.md
@@ -0,0 +1,14 @@
+---
+link: https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf
+title: "A prettier printer"
+date: 2003-01-01
+---
+
+TL;DR: Follow these rules for acceptable pretty printing:
+
+1. if an expression is longer than the room left within a maximum length, fold it.
+1. else, don't.
+
+<!-- more -->
+
+This paper inspired [`prettier`](https://prettier.io/docs/en/technical-details) and [`black`](https://www.youtube.com/watch?v=esZLCuWs_2Y&t=476s).
diff --git a/content/notes/techniques/_index.md b/content/notes/techniques/_index.md
@@ -0,0 +1,3 @@
+---
+title: Techniques
+---
diff --git a/content/notes/techniques/git_scraping.md b/content/notes/techniques/git_scraping.md
@@ -0,0 +1,9 @@
+---
+title: "Git scraping: track changes over time by scraping to a Git repository"
+link: https://simonwillison.net/2020/Oct/9/git-scraping/
+date: 2020-10-09
+---
+
+I've enjoyed using this technique! So far, I've used it to monitor the changes to [AWS's IAM action documentation](https://github.com/SKalt/aws_iam_actions/commits/main/data/iam_actions.tsv).
+
+<!-- more -->
diff --git a/content/notes/techniques/parse_dont_validate.md b/content/notes/techniques/parse_dont_validate.md
@@ -0,0 +1,37 @@
+---
+link: https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/
+title: Parse, don’t validate
+date: 2019-11-05
+---
+
+TL;DR:
+
+- parsers take less-structured data and try to turn it into more-structured data. They don't always succeed, so all parsers need to handle failure.
+- validating `throw`s away information as exceptions/errors, while parsing holds onto that information
+- parsing inputs as early as possible helps you trust the validity of data once it reaches your business logic.
+- Beware of "shotgun parsing": validation checks scattered throughout a codebase. "Shotgun parsing necessarily deprives the program of the ability to reject invalid input instead of processing it."
+
+Or, more succinctly,
+
+> Failure is not an `Option<T>` its a `Result<T, E>`
+>
+> -- https://github.com/penguwin, 2024
+
+<!-- more -->
+<hr/>
+
+> Parsing ... [stratifies] the program into two phases — parsing and execution — where failure due to invalid input can only happen in the first phase.
+
+This reminds me of the technique of generating a plan in one step and then executing the plan in a separate step, like Terraform does.
+I've used separate planning and execution in installer scripts, where I generate install commands that can be verified if `--dry-run` is passed.
+
+One point I was surprised this paper made is
+
+> Avoid denormalized representations of data, especially if it’s mutable.
+> Duplicating the same data in multiple places introduces a trivially representable illegal state: the places getting out of sync.
+> Strive for a single source of truth.
+
+I agree that the "single source of truth" principle avoids errors.
+However, normalizing mutable data creates a new problem: maintaining referential integrity.
+
+Still, I tend to normalize data in structs-of-arrays for reasons laid out in ["Practical Data-Oriented Design"](../practical_data_oriented_design)
diff --git a/content/notes/techniques/practical_data_oriented_design.md b/content/notes/techniques/practical_data_oriented_design.md
@@ -0,0 +1,23 @@
+---
+link: https://vimeo.com/649009599
+date: 2021-11-23
+title: Practical Data-Oriented Design
+tags:
+  - systems programming
+  - optimization
+  - techniques
+  - talk
+---
+
+TL;DR:
+
+- A CPU has several kinds of memory.
+  CPUs cache data in faster and slower memory as the data is used in computation.
+- Reading from a slower cache tends to be more expensive than doing several math operations, even multiplication.
+- Reducing memory usage can vastly speed up an application
+- When possible, 8- or 16-bit integers instead of 32- or 64-bit pointers
+- Using a struct of same-sized arrays instead of an array of structs avoids padding used to align each struct.
+- store different kinds of objects in different `Vec`s or arrays and discard the discriminating information from the struct
+- store sparse data separate from common data, e.g. in hashmaps
+
+<!-- more -->
diff --git a/content/notes/techniques/rust_simd_beginners_guide.md b/content/notes/techniques/rust_simd_beginners_guide.md
@@ -0,0 +1,16 @@
+---
+title: Portable Rust SIMD Beginner's Guide
+link: https://github.com/rust-lang/portable-simd/blob/master/beginners-guide.md
+date: 2022-04-11
+---
+
+TL;DR:
+
+- > A SIMD value is called a **vector**.
+  > [...] A SIMD vector has a fixed size, known at compile time.
+  > [ A] vector is generally aligned to its entire size.
+- > A single element position within a [SIMD] vector is called a lane
+- > The extra-wide registers that are used for SIMD operations are commonly called vector registers, [...] "SIMD registers", vendor names for specific features, or even "floating-point register"
+- > When an operation is "vertical", each lane processes individually without regard to the other lanes in the same vector.
+- Other operations can "reduce" all lanes to a single value.
+- different chips have different architecture-specific SIMD registers
diff --git a/layouts/notes/list.html b/layouts/notes/list.html
@@ -0,0 +1,32 @@
+{{ define "main" }}
+<style>
+  time, span.info {
+    color: GrayText;
+  }
+</style>
+<main>
+  {{ .Content }}
+  <!-- management, communication, and culture -->
+  <!-- deep dives -->
+  <!-- humor -->
+  {{- range .Sections -}}
+    <h2>{{ .Title }}</h2>
+    <ul>
+      {{- range .Pages.ByDate.Reverse }}
+        {{- $url := urls.Parse .Params.link }}
+          <li>
+            <a href="{{ .Permalink }}">{{ .Title | markdownify }}</a>
+            <span class="info">(
+              {{- if strings.HasPrefix $url.Host "www." }}
+                {{- strings.SliceString $url.Host 4 }}
+              {{- else -}}
+                {{- $url.Host -}}
+              {{- end }},
+              <time>{{ .Date | time.Format "2006" }})</time>
+            </span>
+          </li>
+      {{- end }}
+    </ul>
+  {{- end -}}
+</main>
+{{ end }}
diff --git a/layouts/notes/single.html b/layouts/notes/single.html
@@ -0,0 +1,20 @@
+{{ define "main" }}
+{{- $url := urls.Parse .Params.link -}}
+  <main>
+    <h1>{{.Title}}</h1>
+    <!-- TODO: tags -->
+    <div>
+      <a href="{{.Params.link}}" target="_blank">
+        {{- if strings.HasPrefix $url.Host "www." -}}
+          {{- strings.SliceString $url.Host 4 -}}
+        {{- else -}}
+          {{- $url.Host -}}
+        {{- end -}}
+      </a>,
+      <time>{{ .Date | time.Format "2006" }}</time>
+    </div>
+    <article>
+      {{- .Content -}}
+    </article>
+  </main>
+{{- end -}}

-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +---
 +draft: false
 +title: Notes
 +---
++
 +# Notes
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+---`
	`2`	`+title: Culture, communications, and management`
	`3`	`+---`