weblog.masukomi.org

The Thing About Local LLMs

Sat, 06 Jun 2026 00:00:00 -0400

Table of Contents

Overview

Someone responded to yesterday’s post about the Pi coding agent, asking if I was using it with local models. I’ve done a lot of testing with them, and I can say with great confidence that the hype about using them is mostly just that.

At the same time, Pi is a truly remarkable tool that is not only your best option for working with local LLMs, but also - in my opinion - your best option for working with any LLM.

The Reality of Local Models

Unless you’re rich and can afford a beefy PC with multiple top-of-the-line GPU cards, there are very few edge cases where running a local LLM model makes sense.

The videos claiming you can run them on a normal laptop or a Raspberry Pi are only technically correct. Practically they are all lies. They have all had the delay between prompt and response edited out, and are probably running models that aren’t even remotely comparable to what you get from cloud providers.

You can run tiny models and get… bearable response times, but they’re 💩 for coding.

My wife has a gaming PC with 1 good GPU, and in theory we can get load Qwen3-Coder-Next 30b models into its memory, and get output similar to one of Anthtropic’s Sonnet models. I believe that, but what’s unclear is how bearable the delay will be.

She and her research partner Rhyannon (👋), have some things they want to investigate that involve or are facilitated by using local models, so we’re going to be seeing what that looks like and how usable it is.

The Mathematical Reality of No

So far, my experience has been that even on a maxed out mac laptop the only use cases that are practical are background processes where you don’t actually care when it finishes. Apple’s claims about their “Neural Engine” are just hype. Yes, it’s probably better than CPUs without something like that, but good models are large - like really large - and if you want to use that model interactively you need to load the whole thing into the GPUs VRAM.

The back-of-the-napkin equation is pretty straightforward: M = Np * Bp where

Symbol	Description
M	Memory in Gb
Np	Number of parameters in Billions
Bp	Bytes per parameter

Some pre-calculated examples for models you might want to use:

model	Model VRAM Size	Activation Mem	Total Needed
qwen3:4b	8GB	~3.2GB	11.2GB
quen3:8b	16GB	~6.4GB	22.4GB
llama3.2:3b	6GB	~2.4GB	8.4GB
llama3.2:1b	2GB	~0.8Gb	2.8GB

On top of that we need to consider “Activation memory” - temp data used during inference or training. That’s generally another ~20-40%. In the table above I’ve used 40% to make sure we have “enough”. Note that Training (not something we’re discussing) requires 2-4x the parameter memory. Note that that extra 20-40% is required for each agent and subagent hitting the system at the same time because they each have their own unique blob of text that inference needs to be run on. As soon as you exceed the VRAM of your GPU you start having massive performance penalties.

Quantization of models helps lower the VRAM requirements, but the fact of the matter is that you need way more VRAM dedicated to the GPU than any laptop can provide.

Pi Changes Things

I think Pi isn’t just the right paradigm / approach for coding agents. I also think that it’s minimalism is required for doing anything interactive with a local LLM. The things it can do to accommodate restrictive hardware end up working out a lot like accommodations for people with physical disabilities. Yes, it helps them, but it also helps everyone else.

All the other coding agents are financially motivated to use more of your tokens. Anthropic doesn’t care how wasteful Claude is of tokens as it does its work. The more it wastes the more you end up paying. Pi enables a lot of important things that minimize token usage:

trivially small & modifiable “system prompt”
encourages putting code in extensions not skills
ability to override everything with custom code
the ability to treat interactions with the LLM as a tree

The System Prompt

It’s been said that the thing that truly differentiates the Agentic platforms is not the models. It’s all the infrastructure and hidden prompts the vendors have built around their models.

The system prompt is one of those. It’s included at the start of every session and sucks down thousands of tokens. Claude’s changes between releases without warning, includes content dynamically generated by the agent (presumably more token usage) and there’s no easy way to see what it is. I’ve tried overriding it with the --system-prompt-file a_file.md flag and --system-prompt "some text" but it failed to follow the instructions I put in the prompt in both cases.

Pi’s system prompt is known, tiny, and modifiable.

Extensions over Skills

Agentic Skills are ultimately just Markdown documents that have to be read in and reasoned about before the system makes some non-deterministic choices about what to do, and what tools to use to do it with. You can’t actually control it’s actions. It’s like giving instructions to a grade-schooler. It doesn’t matter how precise those instructions are, you can never be 100% sure they’ll be interpreted correctly, or consistently every time they’re read. Also, that reading uses tokens.

Pi extensions are code. You invoke them via a prompt just like skills, but once its invoked it’s just a matter of waiting for the code to finish its run and either hand something back to pi for further processing, or tell it it’s done. It doesn’t matter how complex the extension is, it doesn’t use any tokens unless you’re explicitly asking it to interact with the model.

Overriding Everything

It’s not so much that you can override everything, because most things in Claude code - for example - seem possible to be overridden with custom versions given a sufficient application of Markdown (and prayers). It’s that you can override everything with deterministic code instead of throwing a block of Markdown text at it and hoping it interprets it correctly. Additionally, you don’t have to pay the token cost of processing those markdown instructions because - with Extensions - it doesn’t exist.

Conversation Trees

Models have no memory. The ever-growing history of your conversation with an LLM in each session keeps getting sent to the LLM with each successive prompt. It has to read in the entire thing from scratch with every new prompt. In addition to just being wasteful, this can be problematic when the human or the agent have gone down side quests that either didn’t pan out, or weren’t relevant to the primary task at hand.

A good example of this is the human asking the agent to explain something it just did. It’s useful to you, but each successive prompt to the LLM will have that useless blob of text to process.

Pi’s sessions are stored as trees. This means that, in the example above, you could run /tree and jump the context back to just before you asked it to explain. More significantly, if you and the Agent had been exploring some way of solving a coding problem only to find that your thinking was bad, or that it wasn’t possible, you could jump back so that those “bad” ideas were no longer things that had to be considered on each successive prompt.

Some Plugins To Get Started With Pi

Wed, 03 Jun 2026 00:00:00 -0400

Overview

I see the Pi coding agent a lot like emacs & vim. It’s filled with possibilities, but the bare bones version is only technically usable. To really get the kind of interactions you want you need to add some useful packages.

What follows is the collection of extensions I’ve ended up with.

Agentic Functionality

⚠️ pi-subagents & pi-agent-flow are likely incompatible with each other. pi-subagents is the most popular one, and has other extensions specifically designed to work with it. I’ve been using it without any problems.

pi-subagents

pi-subagents lets Pi delegate work to focused child agents. Use it for code review, scouting, implementation, parallel audits, saved workflows, background jobs, and anything else that benefits from a second or third set of model eyes.

Install with pi install npm:pi-subagents
Package Details

pi-agent-flow

Long conversations can get messy—context bloats, tool calls get duplicated, and the real signal gets lost in the noise. Pi Agent Flow solves this by forking each task into a focused, isolated child process with only the context it actually needs.

See configuration details in README.

Install with pi install npm:pi-agent-flow
Package Details

Search

Pi can’t search the web by default, because that isn’t just a matter of scraping search results from web pages. Ultimately you need to connect to a server that has an API that you can invoke to do web search stuff.

I’ve listed two options below.

pi-web-access

Web search, content extraction, and video understanding for Pi agent. Zero-config Exa search, optional browser-cookie Gemini Web, or bring your own API keys.

⚠️ WARNING: defaults to using Exa for web search, which is free for ≤ 1,000 searches per month, and has a complex pricing system that isn’t obvious how it’ll play out. I think the Exa integration also needs the Exa MCP server. Instead of trying to figure all that out I gave it an API key for my Google Gemini account.

Zero Config — Works out of the box with Exa MCP (no API key needed). Add API keys for Exa, Perplexity, or Gemini API for more control, or opt into browser-cookie access for Gemini Web.

Video Understanding — Point it at a YouTube video or local screen recording and ask questions about what’s on screen. Full transcripts, visual descriptions, and frame extraction at exact timestamps.

Smart Fallbacks — Every capability has a fallback chain. Search tries Exa, then Perplexity, then Gemini API, then Gemini Web when browser cookies are enabled. YouTube tries Gemini Web when enabled, then API, then Perplexity. Blocked pages retry through Jina Reader and Gemini extraction. Something always works.

GitHub Cloning — GitHub URLs are cloned locally instead of scraped. The agent gets real file contents and a local path to explore, not rendered HTML.

install with pi install npm:pi-web-access
Package Details

pi-kagi-api

Already have a Kagi account? This is less functional than pi-web-access but… 🤷‍♀️

API pricing is currently $0.012/request for “search” and $0.004/request for “extract” to get clean content from any URL.

⚠️ There are multiple packages with this name. You want this one by mjakl

Install with pi install npm:@mjakl/pi-kagi-api
- Follow the instructions in the repo’s README to generate an API key and save it so that this packaeg can use it.
Package Details

Integrations

pi-mcp-adapter

Let’s you use MCP servers

Install with pi install npm:pi-mcp-adapter
Package Details

rpiv-args

Enables you to create skills that take arguments.

Pass arguments to your skills like a shell command. rpiv-args adds $1, $ARGUMENTS, $@, ${@:N}, and ${@:N:L} placeholders to Pi Agent skills - write /skill:deploy api production and your skill body sees $1 = api, $2 = production. Skills without placeholders are untouched, so installing rpiv-args is safe for any existing skill collection.

Install with pi install npm:@juicesharp/rpiv-args
Package Details

pi-chrome

Enables Pi to use your existing signed-in Chrome profile after explicit authorization.

pi-chrome is backed by a small MIT-licensed Chrome extension that runs inside the Chrome profile you already use — including every site you’re already signed into. Agents can inspect or control Chrome only after you run /chrome authorize in the current Pi session.

Note: installing the required extension in chrome is a little weird. Read the docs in the repo’s README carefully.

Install with pi install npm:pi-chrome
Package Details

Observability

pi-kanban

Click around a fully interactive dashboard with synthesized sessions, tasks, and subagents — no install.

Install with pi install npm:pi-kanban
Package Details

pi-bar

A wee status bar extension at the bottom that tells you model, effort level, % of context used, and more. Not as fancy as pi-powerline-footer but also won’t require as many resources for things you don’t really info on.

See the README for a screenshot, and instructions on how to configure the colors.

Install with pi install npm:@npm-ken/pi-bar
Package Details

Human Interaction

rpiv-ask-user-question

Let the model ask you structured clarifying questions instead of guessing. rpiv-ask-user-question adds the ask_user_question tool to Pi Agent - a tabbed dialog with single- and multi-select questions, side-by-side previews, per-option notes, and a Submit tab that reviews answers before they go back to the model.

Install with pi install npm:@juicesharp/rpiv-ask-user-question
Package Details

plannotator

(Plan + Annotator) Provides an interactive way to annotate the agent’s plans via a nice web UI instead of it just spewing uneditable text to you in chat. The results are SO much better than trying to read plan details in the terminal. This tool is available for most agentic platforms.

Check out the demo videos linked in the GitHub readme

Install With pi install npm:@plannotator/pi-extension
Package Details

rpiv-btw

Ask a side question without polluting the main conversation. rpiv-btw adds /btw <question> to Pi Agent - a lightweight side agent picks up a read-only clone of your current conversation and answers in a panel at the bottom of the terminal. The side agent remembers its own /btw thread for follow-ups, while your main chat keeps going - its transcript is never polluted.

Install with pi install npm:@juicesharp/rpiv-btw
Package Details

pi-permission-system

Hides disallowed tools before the agent starts — no wasted turns probing for blocked tools
Enforces allow / ask / deny at tool-call time with UI confirmation dialogs
Controls bash commands with wildcard pattern matching ( git *: ask, rm -rf *: deny )
Gates MCP and skill access at server, tool, and skill-name granularity
Protects sensitive file patterns — cross-cutting path rules deny .env, ~/.ssh/* , etc. across all tools and bash at once
Guards external paths — prompts before file tools or bash commands reach outside cwd
Forwards prompts from subagents — ask policies work even in non-UI execution contexts
Broadcasts UI prompt events — permissions:ui_prompt fires only when the permission system is about to invoke the active user-facing permission UI
Native @gotgenes/pi-subagents integration — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and ask \-state forwarding to the parent UI without configuration
Install with pi install npm:@gotgenes/pi-permission-system
Package Details

pi-markdown-preview

Preview assistant responses and local Markdown, LaTeX, code, diff, and other text-based files from pi in the terminal, browser, or as PDF, with math rendering, syntax highlighting, Mermaid, and theme-aware styling.

Mostly I think this is going to be useful when it gives you big complicated responses and some syntax highlighting would help.

See Usage Instructions in the repo’s README.

Install With pi install npm:pi-markdown-preview
- ⚠️ Requires pandoc to be installed
Package Details

Resource Minimizization

pi-lean-ctx

Pi Coding Agent extension that provides ctx_-prefixed tools backed by lean-ctx for 60–90% token savings.

Whenever it’s invoked it outputs how many tokens were saved. I’ve everything from no savings up to about 90%. Regardless if it meets that advertised 60+, it’s still saving tokens.

Install with pi install npm:pi-lean-ctx
- ⚠️ Requires lean-ctx to be installed. Follow the instructions for installing it as an MCP After installing lean-ctx and pi-lean-ctx run lean-ctx onboard, then follow the instructions.
  
  If lean-ctx doctor shows a conflict on the Dashboard Port you can theoretically set it with the LEAN_CTX_PROXY_PORT environment variable. However I haven’t made this work. Instead if i want to see the dashboard I run lean-ctx dashboard --port=3334 (or whatever port you want to use if the default (3333) is being used by something else.
Package Details

Code Helpers

pi-simplify

When invoked, /simplify detects changed files (via git diff ) and instructs the agent to review them with these principles:

Preserve functionality : never change what the code does
Apply project standards : follow conventions from CLAUDE.md / AGENTS.md
Enhance clarity : reduce complexity, eliminate redundancy, improve naming
Maintain balance : avoid over-simplification
Install with pi install npm:pi-simplify
Package Details

Potentially Cool things

These look cool, but I haven’t tried them.

pi-hermes

I like the idea of Hermes, but I’m not convinced it’s worth using because I haven’t seen any answers to the question of how works without bloating the context window. Only install this if you’re willing to take that risk.

Your Pi agent normally forgets everything when you close a session. This extension fixes that.

🔍 Search every conversation — “what did we discuss about auth?” finds it instantly
🧠 Persistent memory — facts, preferences, corrections survive across sessions
⚠️ Learns from failures — remembers what didn’t work so you don’t repeat mistakes
🏷️ Categorized memories — failures, corrections, insights, conventions, and tool quirks organized for fast retrieval
🛡️ Secret scanning — API keys and tokens are blocked from being saved
📚 Procedural skills — the agent saves how it solved problems, not just what
⚡ Background learning — reviews every 10 turns, saves what matters
🔄 Auto-consolidation — merges entries when full, never loses data
Install with pi install npm:pi-hermes-memory
Package Details

pi-studio

Extension for pi that opens a local two-pane browser workspace for working with prompts, responses, live working details, Markdown and LaTeX documents, interactive HTML previews, code files, REPL sessions, and other common text-based files side by side. Annotate responses and files, add local comments, write, edit, run prompts, send code to a REPL, browse prompt and response history, request critiques, and use live preview for code, Markdown, LaTeX, and interactive HTML.

There’s a video in the repo’s README.

Install with pi install npm:pi-studio
Package Details

pi-actors

pi-actors turns trusted local programs, scripts, recipes, services, pipelines, and sub-agents into addressable actors that agents can spawn, message, inspect, and compose.

It is not just a command registry. A tool is a verb. An actor is a noun with time: address, lifecycle, state, logs, mailbox, artifacts, and an interaction contract.

program / process / service
→ command template
→ actor recipe
→ spawn
→ run:<id>
→ message / inspect / artifacts

Install with pi install npm:@llblab/pi-actors
Package Details

gentle-engram

How It Works

Agent completes significant work (bugfix, architecture decision, etc.)
Agent calls mem_save → title, type, What/Why/Where/Learned
Engram persists to SQLite with FTS5 indexing
Next session: agent searches memory, gets relevant context

Full details on session lifecycle, topic keys, and memory hygiene → docs/ARCHITECTURE.md

Install With pi install npm:gentle-engram
- ⚠️ requires the go binary to be installed. See the repo’s README for instructions.
- You may also need to run engram setup pi after installing the binary. It’s not clear.
Package Details

pi-smart-fetch

Better web fetching for agents. I really want to try this, I’m just unsure how it’ll interact with pi-web-access

The “Defuddle extraction” uses defuddle which appears to be a variant on the readability algorithm to download just the contents of the web pages.

*Features

🔐 Browser-like TLS/SSL + HTTP fingerprints — better success on bot-defended pages
🧹 Defuddle extraction — clean readable content instead of noisy HTML
🧠 Useful metadata — title, author, site, language, published date when available
📦 Downloads + large file support — stream attachments and binaries to temp files
🔁 Client-side <meta> redirects — follows sane meta refresh redirects with loop limits
🔗 Alternate content fallback — when extraction produces no/thin content, follows qualified <link rel="alternate" type="..."> entries in <head> that match the requested output format
⚡ Batch fetch — fetch many URLs with bounded concurrency
📝 Multiple output formats — markdown, html, text, json, raw

Install with pi install npm:pi-smart-fetch
Package Details

pi-tldr

During a prompt, pi displays a TLDR box like:

╭ tldr ─────────────────────────────────────────────╮
│ Inspecting the extension package structure        │
╰───────────────────────────────────────────────────╯

The TLDR updates as pi works, including during tool calls and final responses.

Install with pi install npm:pi-tldr
Package Details

pi-agent-browser-native

Allows pi to drive Chrome & maybe other browsers. Not sure. There’s a lot in the docs. One thing it does do is allow you to take screenshots of the browser.

Install with pi install npm:pi-agent-browser-native
Package Details

Something Custom

One of the key features of pi is its knowledge and ability to modify itself, and invoking this is surprisingly easy to do.

For example, macOS ships with a positively ancient version of Ruby. I - like many others - use the rbenv Ruby version manager. pi was attempting to run some ruby commands to test things and they all kept failing because the version of ruby was too old. So, I started a new session, and told pi to create an extension that used whatever ruby version was specified in the .ruby-version file or the default supplied by rbenv. A little later I realized I needed to make sure it invoked bundle and gem via the current rbenv specified version of ruby too.

Now, it just uses the right versions all the time.

So, don’t be afraid to just tell it to make you what you need if someone else hasn’t already created it.

Touchability Graphic

Sun, 31 May 2026 00:00:00 -0400

Table of Contents

Overview

The “Touch Meme” has been floating around the internet for a while, and it’s difficult - if not impossible - to find its origin. Over time the graphic has become degraded with JPEG artifacts.

However, it’s proven a useful tool within the autism community for conveying where we’re comfortable being touched and by who.

In order for people to have a nice clean starting point, I’ve recreated the graphic, with a few changes, and made it available in vector and rasterized formats. I’ve also created a version of the person pre-divided into sections so that you only need to use a “Paint Bucket” tool to fill in the parts with the colors appropriate for you.

Example

We each have very specific feelings about what parts of our body we’re ok with being touched by different groups of people. For example, I don’t want strangers touching me at all but because our society demands it, I’m “Ehh” about shaking hands with acquaintances, and have learned to deal with the fact that touchy people may touch my arms. I’m fine with lovers touching my groin, but it’s a “hell no” from everyone else.

Think about how you feel about each of these groups touching various parts of your body, and fill in the various body parts to represent how you feel about it.

Here’s a quick side-by-side of the blank template, and how I chose to fill it out.

Templates

Blank template images

Download any of these to modify or fill in as you see fit. Note that the font used is “Marker Felt”

JPEG Format ← If you’re not sure, download this one.
SVG Format
Affinity Designer Format

Pre-divided little person

So that you can easily fill it the appropriate sections with the Paint Bucket tool. The colors are intended to be replaced with the ones that are appropriate for you. Fill them in then, copy-paste the colored person into the larger template so that folks can see what the colors mean and what group of people they apply to.

Versions of the person

The Memory Of Media

Sat, 30 May 2026 00:00:00 -0400

Table of Contents

Overview
All Answers Are Misleading
Favorite Media
- Movies
- Books
- Music
  - Albums
  - Songs
- Art

Overview

Someone asked me about some of my favorite media, and I started to compile a list in my head, but then I realized two things:

any answer I give will be misleading.
explaining why is an excellent opportunity to shine a light on what it’s like to have Severely Deficient Autobiographical Memory.

All Answers Are Misleading

Picking favorite media, is at some level a matter of making subjective qualitative judgements about media you’ve consumed. You might immediately think of two or three movies you really enjoyed and compare memories of them in your head. I can’t do that. Movies are one of the things I remember best, but even with movies I’ve seen again and again it’s just a collection of frozen moments and an emotion.

When describing SDAM memory recall Sassy Smith said

The visual detail might be missing, the narrative thread might be gone, and the sense of who was there, what unfolded, what someone said, all of that might be inaccessible. Yet the emotion tied to that event, or the body sensation connected to it, might be present.

…Some of that is probably my own experience shaping the lens. I have aphantasia, SDAM and alexithymia, so the idea of re-experiencing an emotion from a past memory is genuinely foreign to me. I don’t step back into the moment. I don’t re-feel what I felt then, and when I’ve spoken with others who share similar experiences, that’s largely what I’ve heard reflected back.

My experience is very similar to hers, when I try and recall media I enjoyed, it’s mostly just an emotion, and one or two blurry frozen moments. I can tell you I loved Ender’s Game (the book) and that it hit me hard. I can’t tell you why. I remember the pivotal moment just before the end. I know that it was only as impactful as it was because of what came before it, but what came before it? I’m not sure. I know there was physical and mental training. I remember that Ender’s brother is a twisted man. I remember he had a sister who wasn’t. That’s it.

When I’m making a list of favorite media I’m comparing little balls of emotion. I’m picking things that effected me strongly at whatever point in my life I encountered them. Would they effect me similarly today? Probably not, because I’m a different person now, but I can’t bring back the memory of the thing to consider through more experienced eyes. I can only say “this movie evoked strong emotion”

Before I move on, I should mention one curious twist of SDAM as it plays out in my head. Looking back, a movie may just be an emotion and a sense of like or dislike, but re-watching that movie is different. Sometimes, the act of watching it is a series of specific pointers that trigger more normal memories: obscure facts about the actors, a future event in the film, a weird thing I noticed in the background in the scene they’re about to switch to. It depends on the film, and / or how many times I’ve seen it.

Favorite Media

As mentioned above, my memory of most of these is just a small detached emotion. Because of that, it’s not possible for me to rank any of these. They’re just things I consumed that effected me meaningfully. The lists are also inherently limited by what I can recall at the moment.

The thing you need to understand about the descriptions I’ve added by each: it is - in most cases - all I have. That’s the entire memory of the thing; that plus a little sense of emotion.

Movies

You would think that watching a movie many times would cause me to recall it better, but that’s not really the case. I’ve seen Batman (the Tim Burton, and Michael Keaton one) maybe hundreds of times when I was a teen. It was literally the only movie I owned. At one point I had the entire script memorized. Now? I remember almost none of it.

The Incredibles I’ve watched it at least ten times. There’s something wholesome about this. Something about family.
Beyond Rangoon This movie hit me hard in 1995. All I remember is that it’s about a white woman stumbling into political bullshit in Burma, and how badly it effects people.
Léon: The Professional I remember flashes of the first five minutes or so, a couple moments later in the film, and that it hit me hard.
The Big Blue I remember that it was about a competitive free diver who’d been hired for something. I remember that it left me unmoving, and unable to speak for a long time afterwards.
The Fifth Element I adore this film, but the “I love you” bit at the end is cheap, and unearned, and completely undermines it. Unlike most films, I remember entire scenes from this. I have watched it many, many times.
The City of Lost Children Weird in wonderful ways. Touching. Darkly funny. “Je suis l’original!” Trained fleas. A gentle giant. A little girl seeking her brother. A scientist trying to dream. A green mist. Trained fleas with a dark secret.
Amélie Gods what a wonderful film: quirky, silly, intriguing, mischievous, kind. I can remember most of the characters, and many of the moments.
Hackers It’s… a thing. Ridiculousness, seriousness, and naivete all mashed together in all the best ways. I’m not sure how much of my love of this movie is nostalgia and how much is the movie itself. I remember many scenes of this.
The Nightmare Before Christmas In no small part because I love Danny Elfman’s music. I remember many moments from this, and have seen it many times.

Books

Ender’s Game An emotional gut punch. A twisted brother. A sister who was good, but I’m not sure why. An incredible twist. Yes, I’m aware the author is very problematic, but unlike JKR he’s not using the sales of his creations to fund a genocide.
The Harmony of Falling Snow This book is my cozy place. I’ve read it maybe four times in the past year. I remember more of it than most any other media at the moment. Partially because I keep reading it. Partially because our world sucks, and I so desperately want to escape to theirs.
The Magic And The Healing I’ve read this many times, although it may have been a decade since I last did. I remember many moments from it, but not how the moments connect to each other. Like The Harmony of Falling Snow, it’s a world I wanted to escape to. I think it would be more meaningful to the me of my 20s than the me of my 50s, but it’s still an excellent book. I remember that it’s sequel was ok, but not as good.
The Summer Tree I think I was still a teen when I read this. I remember thinking that this was so much more deserving of love and adoration than The Hobbit. This was the fantasy series people should have been making movies of. Now, I don’t remember much. I remember a man sacrificing himself on a tree in some way that went beyond the flesh. I remember a cliff. A long ride on horseback. Characters that were a thousand times more fleshed out and meaningful than anything Tolkien wrote.
Catnip This is light popcorn fare, without the emotional impact of the others on this list, but I keep coming back to it. A little bit because it’s a polyamorous trans story. A little bit because it’s just cozy and hopeful. The audiobook is really good too.

Music

Music is… difficult for me to recommend. My relationship to it is very autistic, and for a while I was working very hard to be a professional studio musician. I relate to it, and use it in different ways. I’ll take a song and put it on repeat for a month on two as I work on a project. I couldn’t play a song from memory, but the moment any of the songs / albums below start playing I know exactly where it’s going.

Albums

I’ve listened to all of these hundreds, of times.

Zap Mamma: Adventures in Afropea 1 There never was a 2, and I think the band broke up leaving only one person to continue making music under this name afterwards. The other albums aren’t terrible, but they aren’t even remotely the same, or as good.
Bad Brains: I against I Much more mainstream, and less punk than their other albums.
Pop Will Eat Itself: Cure For Sanity So many good songs on this album: “X, Y, & Zee”, “92° F (The 3rd Degree)”, “Nightmare at 20,000 Feet” Everything on this album is burned into my synapses.
Orbital: Orbital 2 I still remember “Halcyon + On + On” playing over the intro to Hackers.
Ani Difranco: Ani Difranco I like all of her stuff, but this is the album I listened to the most. Like her, I’m not as frustrated and angry as I was when this album came out. But it’s still an incredible album.
The Suitcase Junket: Dying Star Saw him doing his one-man-band thing on the side of the road during a town festival in Cambridge MA. Bought two CDs on the spot. This was one of them.
The Dave Brubek Quartet: Time Out Recorded in 1959 and still as amazing as ever. “Take Five” is - of course - my favorite.
Metallica: Master of Puppets I rarely listen to Metallica anymore, but this album has a special place in my heart. At one point I knew it so well that I could isolate the instruments in my head and listen to any one of them individually in my head.

Recent additions, not so firmly entrenched in my brain.

Sofi Tukker: Soft Animals I like a lot of their stuff, but this is the album I’ve listened to the most.

Songs

Estelle: American Boy Without exaggeration, I’ve listened to this thousands of times.
WING: Dopamine
Hiss, WING: Object
Jain: Makeba
The Dead South: In Hell I’ll Be In Good Company
Childish Gambino: This is America Not because I listen to it often, or because I particularly love it, but because I think it and its accompanying video are more relevant with every passing day.

Art

Auguste Rodin No sculpture has ever moved me like his can.
Pablo Picasso A master of the line, but also someone I have a personal connection to.
Ansel Adams How can you not love what he saw?
Robert Mapelthorpe Some of his stuff I don’t care about. Some hit me hard when I first encountered it.
Pierre-August Renoir I don’t want a picture of his hanging on my wall, but there’s something beautiful about his work.
Nancy Angell / Angell-Rickenbacker My mom. Incredibly talented. Sadly unknown, despite having a few pieces in museums.

Yes, We Cook For Our Dogs

Sat, 02 May 2026 00:00:00 -0400

Table of Contents

Overview

We cook for our dogs. Not because of any nutritional ideology, or because we think our dogs are too good for kibble. No, we cook for them because we didn’t have any other option, and once we saw the effect, we couldn’t morally stop.

Why We Do It

That’s Ben. Ben was a Springer-Spaniel Border Collie mix. He’d been through some traumatizing stuff before Wifey got him, but with enough years of love and affection, he grew into a sweet lovable semi-neurotic doofus. He also grew old. Eventually, food stopped being interesting to him. We tried everything we could get our hands on. Cheap filler laden crap. Stupidly expensive freeze-dried organic whatever. At best we’d get two days worth of interest from him, and then he’d go back to not eating.

But then Wifey found Feed Your Best Friend Better: Easy, Nutritious Meals and Treats for Dogs

Everything changed after that. He was interested in food again. Admittedly, sometimes Wifey would have to hand-feed him to convince him to keep eating, but he would keep eating. Once he started eating, his quality of life didn’t just reset to where it was before he stopped eating. It was like the clock got rolled back by years. He started running, and rolling, and playing with our other dog. He had energy and enthusiasm.

The effects on our younger dog weren’t nearly as pronounced because she was already young and spry, but we knew that under the covers it was making a huge difference in keeping her vibrant and alive, and would do so for the rest of her life. When Ben finally passed, we couldn’t - in good conscience - stop cooking for Lita, or our latest dog Maui.

What We Do

We always have a different breakfast and dinner meal in the fridge. When choosing the next ones we’ll cook we try to make sure to rotate through different proteins and starches. For example, breakfast might be a tub of “Chicken Thighs and Tabbouleh” while dinner is “Beef and Sweet Potato”.

This book, and another one we use, has a lot of recipes for treats. We ignore all of those. We make the “meals”. One of our dogs is 30lbs (13kg), and the other is 40lbs (18kg), so we typically double the recipes and end up making about 2.5 US Gallons worth of food in each batch. We divide it into two Tupperware tubs. One goes into the freezer, and the other is probably going to be their next meal.

The recipes are really simple, and many of them can be simplified even more. For example, dogs don’t really care if you chop the parsley leaves, so I’ve stopped bothering. I just rinse them to get rid of the grit, then rip off the leaves, and put half the pile into each batch.

Most of the meals involve chopping a bunch of chicken or tubers which end up in two big pots on the stove. The only notable changes we make to the recipes is never using garlic powder because garlic is toxic to dogs, and frequently replacing water with low or no sodium broth.

Slow cooker meals can’t be doubled, but are generally very easy to make and give us another option for getting different proteins and starches into their systems.

How Often?

A tub usually lasts us about four days. So, we end up cooking roughly two meals a week. Remember, each one is doubled so there’s a frozen half waiting when the first tub runs out. That being said, we try and cook ahead a little bit extra, so that when the time comes to grab something from the freezer we don’t have to just repeat what they just ate. We can rotate to a meal with a different protein and starch.

What Are They Like?

Generally, pretty bland and uninteresting to a humans. We need salt. They don’t. They’re generally 1 part meat, 1 part starch, and a handful or two of veggies. After getting familiar with what ingredients are safe for dogs, and the ratios it’s pretty easy to just make up a recipe on the fly from whatever meat you have available + random pantry things.

A couple of them are pretty tasty though. I always steal a couple bites of the “Chicken Thighs and Tabouleh” when its fresh, and when we’re feeding them “Overnight Oats” (yogurt, honey, lemon, oats, apples) I always steal a bite or four while filling their bowls.

Treats

There’s only one treat we make for our dogs, and I don’t remember where we found it. Take one large tub of plain yogurt. One jar of all natural¹ smooth peanut butter. Mix with a stiff spoon, pour into massive silicone ice-cube molds, let freeze for about 24 hours.

We have found literally no treat that is higher value than this. Well, none that’s healthy to give to them with any regularity. One dog bites off pieces and devours his in under two minutes. The other dog slowly licks hers until it gradually disappears many minutes later.

Is This Really Healthy / Safe?

We’re not vets, but what I can tell you is that we’ve been doing this with three dogs now for over a decade. They get blood-work and a checkup every year, and every year our vet pronounces them healthy, .

New vets, and new vet-techs will be skeptical because most people who cook for their dogs do some weird ass things that don’t actually correspond to what a dog needs to be healthy. For example, they’re not vegetarians, so trying to give them a meat free diet is not great. Similarly, there are problems with raw diets too.

Additionally, you have to be vigilant about constantly rotating the things their eating. No meal you make will have all the nutrients they need. It’s just like feeding humans. Dog diets aren’t that different from ours, they just have a couple more things that are toxic, and - proportionally - need a lot more meat than we do.

Side note: every year they ask us how much we feed them at each meal, and every year we have to explain to them that whatever number we give them is meaningless because it doesn’t correspond to the caloric density of kibble which they’ve been trained on, and the calories, and nutrients they get from the same volume changes with literally every meal.

Downsides

There are two pretty obvious downsides.

Cooking two or three more meals every week sucks if you don’t have a House Spouse. Most people I know are too drained at the end of the day to cook their own meals, never-mind cook for the dogs.

Meat isn’t cheap. Veggies aren’t cheap. Dog meals use a lot of meat, and a good amount of veggies. We can only afford to cook for our dogs because we have tech-money coming into our household.

Less obvious is dialing in the proportions. Guidance for kibble volume does not apply. The caloric density is not only completely different, but it varies from meal to meal. Because we’re rotating constantly I’ve found a volume that works for each dog, and I always give them that volume. For some meals this means they’re getting less calories, for some meals they get more, but the constant rotation and the fact that we have two different meals every day evens this out in the end.

The only way to know how much to give you dog is to just watch their body weight very carefully. I don’t mean weighing them. I mean just looking down and making sure their ribs are just barely visible, and that their abdomens curve in behind them. If one of our dogs wasn’t a short-hair we’d probably have to weigh them every couple weeks.

Checking the shape of our black dog as I’m putting together their bowls has just become part of my routine.

Warning

Many people into healthy dog diet things swear by garlic powder for allergies and stuff like that. There is zero research to support this, and plenty of research showing that small amounts of garlic or onion can lead to kidney failure. Do Not feed your dogs any member of the Allium family: onion, garlic, scallions, shallots, leeks, or chives. The same goes for grapes and raisins.

If your dog consumes any of these you should induce vomiting immediately. You should know how, and have the things you’ll need to do so on hand. We have 60ml Irrigation Piston Syringes in our first-aid kits, and use that to get the appropriate amount of Hydrogen Peroxide down their throats.

Unfortunately the cookbook referenced above seems to want to add garlic powder to almost every meal.

Should You Do It?

If you can afford to buy extra meat and veggies every week, then yes. You absolutely should. Even when Wifey and I were both working and really really didn’t want to cook a dog meal in addition to our own, we knew what a huge difference it made to their quality of life, and continued to do it.

All Natural Peanut Butter: There are so many random ingredients thrown into peanut butter these days that it’s not worth the effort of buying anything except all-natural peanut butter that only has 1 ingredient (peanuts). Artificial sweeteners are toxic, and salt isn’t good for them, so keep it simple and buy the healthy stuff. ↩︎

Making Useful Structured Commits That Become Changelogs

Sat, 04 Apr 2026 00:00:00 -0400

Table of Contents

Overview

git-com is a tool that makes it easy to create structured commit messages. It exists because of two roles I’ve played at work:

release manager
Leading a support engineering team tasked with putting out production fires.

Both of these jobs involved investigating what actually ended up in a release. With the support engineering role I needed to find out what got added that might have broken a thing. With the release manager role I needed to find out what actually got added as compared to what was promised, or never mentioned. Then, I needed to create a document to convey those changes.

Having a readable structured commit history would have been huge for me back then. Now that I do have one it’s proving invaluable.

This post discusses how to think about creating and utilizing structured commits in a way that will help you accomplish two goals:

finding specific changes in your history
conveying what changed to others via generated changelogs

None of this requires git-com, but using it will definitely facilitate the process, and it’s written from the perspective of someone using it.

What Should Be In Your Commit?

git-com is intentionally not opinionated about this. What is “useful” or “good” varies wildly from project to project.

The one guiding thing I can say with a lot of confidence is that you should never add structured data to your git commit messages that you don’t need. Leave off the “nice to have” items. Every “unnecessary” step you make someone take (even you) when creating a git commit is another tiny piece of built up resentment.

Titles

Getting the title “right” is the most important thing. There are many cases where the title is the only thing you’re going to see until you dig in for more info. Thus the title needs to convey the most critical information in order for you to know if you want to get more info. The title is frequently the only thing that gets written in a commit, and they’ll show up in your changelog, or become the starting point for what shows up.

There is, however a significant limitation on git titles: They should be ≤ 72 characters. Ideally they should be around 50.¹ That makes for a tricky balance.

Additionally, you need to think about what will be useful to the tooling that will take the commit messages and convert them into a changelog.

I’ve addressed these problems in two ways.

Start with structure

All my git-com generated commit messages start with [<change type>]. This serves two purposes.

The square brackets draw your visual attention. They say “hey this is most critical bit of this line”
It’s not something I’ll bother with when making a quickie “corrected spelling errors” type commit, and thus it becomes easy to distinguish “stuff worth conveying to others” from “one of the many little changes that got made but aren’t worth talking about”

Because the contents of those square brackets come from a limited set of choices defined in my .git-com.yaml file, it also serves as a way for my changelog generator to easily distinguish between a changelog worthy commit and something that just happens to start with square brackets. This also means that you can have commits in your git log that, by virtue of having no structure don’t end up in the changelog.

Personally I use git commit -m "corrected spelling errors" for things not worth conveying, but if you want to build the habit of always using git-com you have two options.

use a specific change type that will be visible in your commits but excluded later. E.g. [meh]
make the change type option “skippable”. The skip option appears first so you can just whack the enter key if you don’t care about choosing something from the list.
```
    allow-empty: true
    empty-selection-text: Skip
```

Neither of these is “better”. I like the idea of having trivial commits start with [meh] It sounds entertaining. On the other hand, I can see the argument that you’d want to draw as little attention as possible to commits that aren’t noteworthy. That way humans scanning git log output don’t have their eyes drawn to unimportant things.

I’m firmly of the belief that the type of change is the most important thing to have in a commits title in order to help anyone who needs to look through the log to find something specific.

I also believe that change type is an excellent way of breaking down changelogs of software products. I don’t want features, fixes, and tweaks to all be mixed together in a jumble of a list. Sometimes I want to know what cool features a project has added. Sometimes I just want to know if they fixed a specific bug.

Keep it concise

Not because of the character limit, but as a way of being nice to future humans. The freeform portion of the title should contain only enough information for a reader to know if it’s worth their attention.

Ex. “full-text search refinements” not “reworked our use of faceted search to prioritize items we sell”

Additional details like that can be added to the commit body. Just give me enough information to be able to determine if this commit is the one I care about or need more details on.

Different Text for Different Audiences

Git logs and changelogs are things generated for different audiences. Git logs are for geeks looking into the details of a codebase. Changelogs are for people who use your tool, or maybe for stakeholders within your company who have been involved in guiding the tool. They have different needs.

Because of this, it’s important to keep in mind that the text that appears in your git logs isn’t necessarily the text you want to show in your changelogs. With regards to the structured text this is easily handled with aliases, and leads to some interesting possibilities.

Git wants short titles, so find short ways to represent things like change type in actual commits. “feature” is a lot longer than “add” or “feat”, and you don’t really need to indicate that “feat” is an abbreviation by adding a period (“feat.”).

Personally I’ve settled on

add
fix
clean-up
refactor

You’ll note that the last two could be shorter. I want them to be shorter, but “cleanup” annoys me, and “clean” feels wrong. I also haven’t thought of a shorter way to say “refactor”. What you end up will be the result of a highly subjective balancing act.

However, as I noted before, the thing in your git commit message doesn’t have to be identical to what’s displayed in the changelog. So you can put short things in the commit message that end up as longer things in the final communication. You can also put in things that will be excluded. Like fixes to a security issue no-one noticed yet.

My changelog generation tool reads in my .git-com.yaml file and leverages the fact that it supports the concept of “meta elements”. These are elements that exist within the config but aren’t for consideration as part of your commit message.

meta_element_changelog:
    display_aliases:
        fix: "fixed"
        add: "added"
        refactor: "refactored"
        clean-up: "cleaned"

When building the changelog it finds commits with [add] and groups them under an added heading because of the mapping in display_aliases, but this could be anything. Maybe “add” commits end up under “❇️ New Features”, or the other way around. Maybe ❇️ in a commit title indicates new coolness and gets grouped under “added”. Keep in mind that users of git-com are usually choosing from a pick list, so you don’t have to know how to type special characters like ❇️ to have them added in the commit message.

Other Representations

Note: square brackets aren’t the “right” solution here. They’re just a solution. Here’s some other ways you might handle the same thing. What’s important is that you find a way to represent things that you and your team (if working with others) can agree makes sense and isn’t annoying.

# <optional breaking change> <change type> <separator> <freeform text>
⚠️ (feature) → full text search
# nonbreaking version…
(feature) → lists recently completed items

# Minimal Emojis
# <indicator structure> <change type> <separator> <freeform text>
# ℹ️                    (fix, add, etc.) :           blah blah
ℹ️ fix: now supports linked worktree directories

# FULL EMOJIFICATION 🤪
# <indicator structure> <change type> <separator> <freeform text>
# ℹ️                    (❎, ❇️, ♻️ etc.) ▶️       blah blah
ℹ️❎▶️   now supports linked worktree directories

# maybe add special emoji to indicate a breaking change
# <indicator structure> <change type><optional breaking change><separator> <freeform text>
ℹ️❇️⚠️▶️ full text search
# Breaking because it might require a db upgrade or something noted in the commit body

Body

Here’s where things get extremely subjective.

Obviously you need block of freeform text for people to (optionally) describe what the commit is about, but the question of what - if any - structured data you should include is where things get complicated.

I’ve chosen to go with a multi-select for portions of the codebase that are involved in the change. The list of options for this is very different for each project I use git-com in, but what they have in common is that each item represents a significant distinct part of the codebase, and it’s mostly sorted so that the frequent items are near the top.

This data never shows up in changelogs, and I rarely ever read it. I do this because of my time spent hunting down production bugs at work.

For example, let’s say the look of our site had become borked. I’d have a pretty good guess it was changes related to the “css” portion of our codebase or maybe something in the “ui” layer. It would have been invaluable to me to be able to run a command like this and find commits since the last release that included changes to the relevant sections of the codebase.

git log v1.2.0..HEAD --grep " (css|ui)" --extended-regexp

Here’s what I see when I run that in a codebase that uses those two keywords in its “Code Sections” (see example below)

Commits since a release in matching sections of the codebase.

If a search like that overlapped with too much of the freeform text I could limit the results to the “Code Sections” metadata line by doing this.

git log v1.2.0..HEAD --grep "Code Sections:.*(css|ui)" --extended-regexp

I experimented with Tags and “Code Sections” it ended up feeling like unnecessary paperwork that I was resenting. Again, my advice is to only add sections that you have real use for.

Example Config

The list below is from the BackupBrain webapp which is currently focused on managing, and archiving bookmarks.

code-sections:
    type: multi-select
    allow-empty: true
    modifiable: true
    record-as: joined-string
    before-string: "\nCode Sections: "
    destination: body
    instructions: Which section(s) of the codebase?
    options:
        - bookmarks
        - archives
        - ui
        - ux
        - css
        - config
        - meta
        - tests
        - migrations
        - infrastructure
        - tags
        - oauth

Changelogs

I have plans for creating a Changelog generator that can read in a project’s .git-com.yaml and extrapolate the rules it needs to read and format a changelog. Until then though, you’ll have to approach this problem on your own. The changelog tool I’m currently using is called git-com-changelog and can be found here.

The goal

Creating changelogs from commit messages has been the most useful and meaningful thing I’ve done with git-com. It doesn’t just give me good changelogs. It’s also wired into my release tooling so that:

new version tags include the changelog in their body
my CHANGELOG file gets the latest info prepended to the top with markdown or org-mode formatting depending on the file-type.
my Github Releases inherit the changelog text from the tag to populate their bodies.

For some of my tools, cutting a new release means typing release v1.2.3 and that’s it. Changelogs get updated when needed, tags get cut when needed, releases are created with changelogs in their body, artifacts get built and attached to the release, homebrew formulas get updated and pushed.

Changelog example:

v1.7.0

[fixed]
- hitting ESC at a confirmation now exits
- tweaked how lefthook's go-tester works
- commits work in linked worktrees
- maintains yaml element ordering when adding an option

[added]
- final validation now leads to edit if NO is chosen
- added some lefthook files
- now supports include-empty attribute
- stores commit message for reuse when pre-commit hooks fail
- stores & offers up commit messages from failed commits

[refactored]
- faster startup
- hook output now streams live

[cleaned]
- backporting some notes from web site
- removed instructions.org

Making it Happen

Getting from commits raw commits to useful changelogs is surprisingly easy. There are three aspects to the processing.

read .git-com.yaml to figure out what goes into a prompt
optionally read the contents of the meta_element_changelog section to get processing rules & modifiers.
gather commits, filter, group (optionally) and output.

1. Figure out what to look for

Limiting your input

You don’t want to reprocess your entire git history every time. So, I recommend that your changelog tool can take standard parameters for limiting the commits it has to work through. I’ve chosen to go with a --from and an optional --to parameter. My tool just passes those limiting bounds on to git log when asking for commits to process. This is especially useful when you start building automated changelogs into your build process.
```
# everything between the v1.5.0 tag and the v1.7.0 tag
git com-changelog -f v1.5.0 -t v1.7.0
# everything from v1.5.0
git com-changelog -f v1.5.0
```

Knowing what ’s worth considering

The first step is knowing what structured data you can always count on existing in a commit worth including. In my case it’s a commit message whose title starts with a change-type indicator [foo] where “foo” is any of the currently supported change type options.

So, for me that means reading in the project’s .git-com.yml, and asking for the contents of the change-type element’s options.
```
change-type:
    destination: title
    type: select
    modifiable: true
    instructions: What kind of change?
    before-string: '['
    after-string: ']'
    format: "%-12s"
    options:
        - fix
        - add
        - refactor
        - clean-up
```

2. Apply modifiers

Note: This is completely custom, but I think it’s an idea worth copying.

git-com supports the inclusion of custom YAML in its config file as long as the top level element begins with meta_element_ I’ve been using meta_element_changelog to store project specific configuration / behavioral instructions for my changelog generator.

None of the following is built into git-com, but my changelog generation is based on the git-com configuration at the time of invocation, so it makes sense to store it all together. You can make your own meta_element_foo with whatever information you find useful for helping generate a great changelog.

I have 4 types of assorted modifiers.

display_aliases

These provide a display alias for the heading each type of commit will be grouped under. For example you can see that any commit with a change-type of “add” will be displayed under a heading of “added”, but it could be something fancier like “❇️ New Features”
```
meta_element_changelog:
    display_aliases:
        fix: "fixed"
        add: "added"
        refactor: "refactored"
        clean-up: "cleaned"
```

retired_aliases

Because ideas and conventions change over time, clean-up may get replaced with something like clean. This happened a lot as I was getting started with git-com and figuring out what worked, and didn’t work for me.

As a result, I’ve added in support for retired_aliases. So, if clean-up changed to clean then I’d change my meta_element_changelog section like this.
```
meta_element_changelog:
    retired_aliases:
        clean-up: "clean"
    display_aliases:
        fix: "fixed"
        add: "added"
        refactor: "refactored"
        clean: "cleaned"
```
Note that under display_aliases clean-up has been replaced with the new term which would have been added to the options of change_type at the top of the config. The new retired_aliases section tells the code that if it finds a line with clean-up as the change type it should replace it with clean and then process as if it was clean all along.

“permissive” mode

My changelog tool has a “permissive” mode that can be toggled with a command line argument. It basically means “hey, if find a change type that isn’t in the list, just consider it valid.” It’s good for testing but I don’t recommend it in practice.

exclusions

While I don’t use it, I’ve added support for an optional “exclusions” list. After applying any retired_aliases it checks if the current change-type is in the exclusions list and skips it if it is.
```
meta_element_changelog:
    display_aliases:
        fix: "fixed"
        add: "added"
        refactor: "refactored"
        clean-up: "cleaned"
    exclusions:
      - security
      - meh
```
Given the list above, and commit with a change-type of “security” or “meh” would be excluded from the changelog.

3. Generate Output

Most of you will be generating markdown flavored files, but if you want to use this with git tag, you need a way to generate useful output with no markdown headings. The problem is that any line that starts with # is considered a comment by git, and is completely ignored. This means all your markdown headings will be stripped.

I’ve solved this by having it generate output without markup by default (like in the example above). It also supports --markdown and --org flags. Most of you won’t need the org one.

Because I like grouping similar changes (again, see the example) I create a “hash” / “dictionary” with keys for each encountered change-type, then build up a list of all the commit titles as its value (after stripping off the change type).

Then I just iterate over the collection. I use any display_aliases I found to change the heading text. For example changing “fix” to “fixed”, or “add” to “added”. For each line I apply the appropriate markup if the user requested it. That’s about it.

Consistency Consistency Consistency

The more projects you work on the more critical it becomes to have a consistent structure to your commit titles across projects. I can leverage my changelog generator across all of my projects because they’re always the same.

[<change_type>]<space><freeform_text>
For example:
[fix]     commits work in linked worktrees

If I start using a different structure in one of my projects I’ll have to create a new changelog generator or make modifications to the existing one specifically to accommodate the second format.

Summary

Make commit titles include a small piece of consistent structured text that’s easy for humans and code to pick out. Having this be the change-type of the commit is a great place to start.
Don’t gather data you don’t need. Ignore temptation to add steps to your git-com config that make future you and collaborators enter / choose info that isn’t really needed. You’ll just get annoyed.
The more important it is for you to fix bugs quickly, the more important it becomes to leave yourself hints in the commit body that’ll help you track down problematic changes quickly
Creating a changelog generator is relatively easy, but you need something that understands the format that you’ve come up with for your commits.

Bonus

Using git-com’s format functionality makes it much easier to quickly skim changes because everything’s aligned.

❯ git log --oneline v1.6.0..v1.7.0
3382062 (HEAD -> main, tag: v1.7.0) changelog.org → CHANGELOG.org
8ddaa76 (origin/main, origin/HEAD) added a commented out lefthook pre-commit that'll always fail
23d3f40 [add]       stores & offers up commit messages from failed commits
2324d4e [add]       stores commit message for reuse when pre-commit hooks fail
1203fdd [refactor]  hook output now streams live
0a1ad2c [fix]       maintains yaml element ordering when adding an option
7489d58 [fix]       commits work in linked worktrees
3611a23 [refactor]  faster startup
906284d [fix]       tweaked how lefthook's go-tester works
0f01ecc [add]       added tag & release handling to homebrew tap script
5010937 [add]       added changelog.org file

Martijn Hols has a really nice blog post about How to write a good commit message. ↩︎

Your Privacy And Mozilla

Mon, 12 Jan 2026 00:00:00 -0500

The other day I stumbled across a reminder that in February of 2025 Mozilla deleted the following piece of their FAQ.

Does Firefox sell your personal data?

Nope. Never have, never will. And we protect you from many of the advertisers who do. Firefox products are designed to protect your privacy. That’s a promise.

Some people have tried to defend them pointing to the current entry on their privacy FAQ (Jan 2026).

It seems like every company on the web is buying and selling my data. You’re probably no different.

We never sell your personal data. Unlike other big tech companies that collect and profit off your personal information, we’re built with privacy as the default. We don’t know your age, gender, precise location, or other information Big Tech collects and profits from.

Here’s the thing. That doesn’t mean what you think it does.

Back in 2010, I used to work in a company that did targeted advertising. We didn’t need your “personal” data, and we didn’t want it. The tech was so good that it honestly wouldn’t have helped us. We just needed to be able to drop a cookie on you like all advertisers did. We didn’t even really need to do that, it was just easier. We could reconcile two “identities” resulting from different browsers / VPN / whatever and mush them back together.

Knowing your name? Your precise location? Advertisers didn’t care about any of that. They just wanted to know if you were someone likely to buy what they were selling. If we stuck their ad in front of the right person the odds of it getting a click increased. And we were really good. Like scary good.

There was a - probably apocryphal - story that Target had hired a company to do targeted advertising for them and send out coupons to pregnant mothers. New moms spend a lot of money on baby products, and Target wanted to get them to start those years of shopping with them. According to the story, a woman was sent coupons for baby products before she even realized she was pregnant.

The thing was, it didn’t matter if it was actually a true story or not, because we knew that it was entirely possible with the tech we had in 2010. We could predict, with scary accuracy what you would buy within the next month. With larger purchases, like cars, we could predict it about a year out.

We had zero personally identifiable data. We didn’t need it, and having it would have been a liability.

So, Mozilla telling you they’re not selling your “personal” data? It’s a misleading statement to make you feel they have your best interests at heart. They don’t. If they did, they would say that they don’t sell or share “your data”.

Obviously, no-one wants their personal data being sold, but the people who want to know what you’re planning? They don’t need it, and they don’t care anyway. If they wanted to send something to your home they could just buy a mailing list targeted to your demographic. Anyone can do it.

Similarly, TikTok being Chinese owned and getting your data? That’s just more misleading political bullshit. China - along with anyone else who wanted it - already had your data. Selling your data is big business in the US. We have no meaningful laws against it, and no meaningful penalties for leaking your private data.

The only meaningful privacy statement is a claim that a company will not share your data and will not work with advertisers. Anything less is misleading bullshit. Even if you disagree, Mozilla removed their promise to never sell your personal data. That’s pretty telling.

If you’re actually concerned about this, then - hopefully obviously - switching to Chrome is not a good idea. It’s controlled by one of the world’s largest advertising companies (Google) who has taken active steps to prevent good ad-blockers like UBlock Origin from working.

There are alternatives though:

Waterfox is a downstream fork of Firefox that disables their AI bullshit, exposes some hidden settings, and sets the privacy defaults to where most people would reasonably expect them.
LibreWolf is another downstream fork of Firefox for people who want to take additional steps to protect their privacy online. It has stricter defaults for cookies, tracking, and fingerprinting, which sounds great, but is likely to have some negative impacts on your browsing experience. Obviously, they also disable Mozilla’s AI features.

Its important to the health of the internet, and to the freedom of information, for us to use a browser not controlled by one of the worlds largest advertising companies; a browser that isn’t controlled by a company that limits what people see based on the whims of local governments.

Right now, Firefox based browsers are the best option we have, but Mozilla.com (the for profit company) has been focusing all its energy on increasing profits, and Mozilla.org (the non-profit who gets all the press) very clearly does whatever Mozilla.com says. Mozilla’s users very clearly do not want AI shoved into their browsers, but they’re doing it anyway. Mozilla’s users want privacy, and Mozilla.org promotes the idea that they’ll protect yours, but they work with advertisers, and refuse to say they won’t sell or share your data.

It’s time for Mozilla to die. It has been corrupted from within. It’s time for the downstream forks to work together to create a “hard fork” of Firefox, a core codebase build on shared beliefs that users, and their privacy matter. LibreWolf, and Waterfox can still put their own spin on that. Making a version catered to the desires of their users.

New Year New Tools

Mon, 05 Jan 2026 00:00:00 -0500

Table of Contents

Wheeeeee
- Cleandiff
  - Why
- git-com
  - Why
- options_parser
  - Why
- oho (bonus)
  - Why?
Credit Where It’s Due

Wheeeeee

Ringing in the new year with new tools!

Cleandiff

CleanDiff is a graphical diffing tool that pays attention to word instead of lines.

Why

Two reasons:

I hate looking at diffs of changed lines and knowing something changed, but having to hunt for what that something is.
Too much noise. In addition to wanting to see the specific “word” or “character” that changed, I don’t want to have to scroll through the entire document to get to it, or the opposite problem where something like git diff shows you a tiny bit of context, but not enough.

git-com

git-com is a tool for creating structured commit messages that’s easy to configure for each project. A simple YAML document at the repo’s root drives an interactive UI with select lists and text fields to easily populate your commit message with structured, and repeatable elements.

[front-end] bug-fix: item listing works with large minimum font size

Text elements started overlapping each other when a user had a
minimum font size set in their browser.

Tags: accessibility, css

That commit message could have been created with the following elements

<code-section> <work-type>: <title>

<description>

<tags>

Why

This is yet another entry in a collection of tools to help answer questions about what’s changed in a codebase. Sometimes it’s that simple. Sometimes it’s trying to find where a bug introduced. Sometimes it’s to be able to have an accurate accounting for stakeholders.

Good commit messages have saved me countless hours of spelunking when I was in charge of a support-engineering team (putting out fires in production), and as a release manager trying to figure out what actually made it into the impending release.

In things like my dotfiles repo, they’ve been useful for just knowing what part of my system a commit pertains to. In my writing it lets me know which book I was making changes in, and if it was new writing, or edits.

Codebase Example

[fix] was erroring if run from a subdirectory
[fix] icon in readme on github
[fix] removed unecessary blank line from .git-com.yaml
[fix] removed flag from script to update homebrew tap
[add] added quick-start to docs
[clean-up] simplified .git-com.yaml

Writing Example:

[ji-woo] renamed 2 of the container kids
[thimble] finished telling taylor's dad about thimble
[thimble] few days worth of editing and adding
[worldbook] added info re cats barely growing
[worldbook] added / updated content warning stuff
[nicole] finished off day after meeting ji-woo

options_parser

options_parser is a new options parser for Ruby

It supports

auto-generated help docs
required & optional arguments
short and/or long variations
arguments that take values, or just act as flags
separating flag from value with space or equals
auto-conversion to integer or float as defined by the value_type
trailing arguments Ex. `command -n 4 – file_1.txt file_2.txt`

A simple example

options = {}
parser = OptionsParser::Parser.new(
            command: "myapp",
            description: "Does something useful") do |p|

  p.on(short: "-f",
       long: "--file",
       value_type: :string,
       help: "Input file path") do |value|
    options[:file] = value
  end
end
parser.parse(ARGV)

Oddly, this isn’t the first options parsing library I’ve written. I wrote one for Crystal that allowed you to create “sentence-like human interfaces to your apps”. It had a similarly creative name: sentence_options

Alas, everything pales in comparison to what Raku comes with in its standard library. 😿

Why

Because - IMNSHO - Ruby’s optparse is a clusterfuck of confusing code, bad docs, and limited functionality. And I was writing a script that took two arguments and processed commit messages created with git-com and converted them into a rough changelog for the next release of git-com. 😜

oho (bonus)

Not technically “new” but somewhere along the way oho (the world’s greatest tool for converting escape codes to HTML) developed bit rot. Two key regular expressions that definitely used to work, started either matching too much, or too little and completely hosing the output as a result.

I’ve updated it, and found - and fixed - a couple edge cases it wasn’t handling well.

Why?

oho was created because - as a release manager - I found myself maintaining a growing arsenal of CLI tools that could spelunk through our git logs and generate useful information for stakeholders.

Just copy-pasting from the terminal - and loosing all the colors - lost a lot of important context and made it hard for stakeholders to focus on what they needed to. I needed a way to capture the colors and formatted output my tools were producing.

Oho lets me go from colorful terminal output to HTML which can then be converted to PDF. People are weird about being given raw HTML files, but PDF is something they’re comfortable with.

Credit Where It’s Due

Cleandiff wouldn’t have been possible without my amazing wife bringing Fenestro back to life by porting it to Go, and without her creation of the tokendiff diffing algorithm (geeky details here) the results wouldn’t be nearly as nice.

Fenestro is a fancy web-view you can throw lots of HTML files at really quickly, and then switch between them by clicking on its sidebar. It used to be in Swift, but then it stopped compiling as the language moved forwards. Now it’s written in Go and leverages the Wails GUI framework.

To make Cleandiff I simply took her work with Fenestro, and Tokendiff, and combined it with everything I’d learned making, and refining the proof of concept for Cleandiff, and slapped it all together into one app.

Amazon To Bookwyrm Browser Extension

Sun, 28 Dec 2025 00:00:00 -0500

Table of Contents

Overview

I’ve created a Firefox extension to make it easy to populate BookWyrm’s “Create Book” form with information from Amazon.

This post describes the approach taken, and provides info for anyone who wishes to create a fork that can extract data from other web sites.

If you just want the extension, you can find it here the Firefox Addons site: https://addons.mozilla.org/amazon-to-bookwyrm

⚠️ Note: This post is being written before the extension has made its way through the approval process. If that link doesn’t work, you can either try tomorrow or - if you’re a geek - install it from the source code (see below).

Why this exists

BookWyrm is a wonderful federated book review platform, but adding a new book that doesn’t already exist in the database requires manually entering all the book’s metadata. This is tedious and time-consuming, especially when all that information already exists on Amazon.

Most of the books I read aren’t in BookWyrm’s database yet, and needing to manually look up and enter all the data for a book has prevented me from leaving a lot of reviews that I really wanted to make.

So, I created a browser extension to copy the data from Amazon.

What it does and why

It would be lovely to use Amazon’s books API to get nice structured data for books. However, that API requires AWS account credentials, and isn’t free. Running a service that used their API to populate a site like BookWyrm would probably violate their Terms of Service too. We shouldn’t expect to see this kind of functionality within BookWyrm itself, because it’s likely its creators would get in trouble with Amazon.

So, this plugin just reads the HTML of an Amazon product page you’re viewing, and checks known locations for the information you’ll need to populate the “Create Book” form on your BookWyrm instance.

It does not submit the form, because you really need to verify the data it extract. There are lots of edge cases that can lead to odd results. Series - for example - is the biggest offender. When looking at a book in a series, some authors/publishers will set up the book data such that it only shows the series name, some include which book in the series, or how many books with different formatting, some put it in the title. Using Brandon Sanderson’s “The Final Empire” as an example, here are all the ways - so far - that I’ve seen a book be recorded.

title: The Final Empire, series: Mistborn
title: The Final Empire, series: Book 1 of 7: Mistborn
title: The Final Empire, series: Part of: Mistborn (7 books)
title: The Final Empire: Mistborn Book 1, series: Book 1 of 7: Mistborn
title: The Final Empire (Mistborn Book 1), series: Book 1 of 7: Mistborn

And all sorts of other combinations of the above. Extracting the “correct” data is pretty hard when there’s no consistency in how that data appears in the source.

We don’t want to be filling your BookWyrm instance with bad data. So, please take the time to validate all of the data that’s been copied over before submitting, and obviously search for the book on your BookWyrm instance before jumping to the creation of a new one. Much better to use / improve an existing book that others have been reading / reviewing than to create a duplicate.

Why Only Amazon?

It doesn’t currently support other sites for one simple reason: tons of indie authors only publish their books on Amazon. This is largely because it’s a requirement if you want your book to be available via Kindle Unlimited. There are lots of reasons this is terrible for authors, and publishers, and readers, but that’s a separate discussion. What’s important for the purposes of this plugin is that regardless of how you feel about them, Amazon is the one place where you can consistently go and find the book you want to import to BookWyrm.

It currently only supports amazon.com and amazon.co.uk because most - or all - of the other amazon sites are in languages I can’t read and thus I can’t verify the extension will work on them.

Why only Firefox?

Because that’s what I use. Well, technically I use Waterfox because Mozilla seems determined to make Firefox awful. I might make a Chrome extension, but - for many reasons - I don’t like using Chrome, so I’m not strongly motivated to go through all the work. 😉

If you’re a motivated geek, I’ll happily accept a Pull Request that creates a “chrome” folder with a chrome extension that reuses the core code, or just fork it and change it to be just a Chrome extension. Have fun.

Geekery

The GitHub repo can be found here: https://github.com/masukomi/firefox_amazon_to_bookwyrm/

I’ve endeavored to put all the info you’ll need to get started with modifying this to work on other sites.

Please fork it, make changes, submit Pull Requests, all the good stuff.

Creating A Shorthand

Mon, 17 Nov 2025 00:00:00 -0500

Table of Contents

Overview

A look back on the experience of creating my own shorthand, and advice for those who might want to attempt the create one of their own.

Why make a shorthand or custom cursive orthography?

There are lots of reasons one might want to. Kids create secret cyphers for sharing notes with friends, or keeping their diaries private. Adults do that too, but some of us do it for the challenge, and some of us do it because the existing options just don’t work well for our brains, or bodies.

Creating your own shorthand is a fun and creative exercise. Creating a cursive shorthand brings a series of additional challenges related to how letters connect, and how words flow across the page. I’ll write more about this below.

Writing longhand is also incredibly rewarding, because it uses different parts of your brain, and forces you to interact with language differently. Doing so in a script that’s designed specifically for your needs, and desires feels great.

What I made

Korthic Shorthand is a cursive shorthand created to solve the problems I was encountering using standard printed, or cursive English lettering. It’s a 1:1 substitution for the Latin alphabet, just like longhand is a 1:1 substitution for printed letters.

As shorthands go, it’s very simple. No phonetic spellings, and only two “shortened forms” for common words.

I suspect that future versions of it will have phonetic spellings, but for reasons I’ll get into later, I chose to release it without that.

A screenshot of the Korthic alphabet.

Set Some Goals

The most important thing you can do is describe the problem you’re trying to solve, and set some goals.

I had the following goals for Korthic:

a cursive that doesn’t bother my wrists after many pages of writing
(mostly) stays on a horizontal line
works well on tablets
produces words whose meaning is unambiguous and easy to read.
no memorizing long lists of special cases
aesthetics that make me smile

Note that speed was not something I was striving for. I don’t need to transcribe written speech. I need something that’ll be “fast enough” for me to write scenes for my novels without frustrating me.

My aesthetic goals are purely subjective. More importantly, they’re not subject to what anyone else thinks. I only need to make myself happy. That being said, I have received unprompted compliments on it from people who happened to see me writing.

Understand your limitations

In my case there were two big limitations that I was trying to overcome. The first is that after only a couple pages of printing my wrist starts to hurt. Writing in standard cursive solves this, but at speed I end up with words whose letters I have trouble trying to decipher. Transcribing my scribbles became an exercise in frustration.

However, writing many pages in both forms taught me about what I could realistically expect of myself.

Precision was, very clearly, not something I could rely on.

Grafoni - for example - looks great. It’s got a printed and cursive form, and both look clear, and seem easy to read.

An example of Grafoni's two writing styles

I was excited to use it, until I looked closer.

The Grafoni Alphabet.

After writing enough pages of cursive English, it was clear to me that I’d never be able to clearly write different upwards curves of slightly different lengths and be able to tell one from another. I gave Grafoni a try, just to be sure, but I walked away confident it’d never meet my requirement of creating words with unambiguous spellings.

I can differentiated between “wide” and “small” letters though. In Korthic the “t” and the “o” are both downward curves like a “u” but the “o” is always written significantly wider. There are a couple other letter pairs like this. How wide my “o” is drawn can differ significantly from word to word, but it’s still pretty obvious that my “t” shape is trying to be a “small” letter and my “o” is trying to be a “wide” letter. In the end

Understand that everything is a tradeoff

Gregg shorthand - for example - prioritizes speed over most things. It’s a brilliant cursive shorthand, with lots to lots to learn from studying it, but it also has hundreds of “shortened forms” it expects you to memorize. For example, the word “husband” is written like a lower case “i” with a tiny bit of flourish. Its spelling is phonetic, and it has a bunch of special rules, and shapes that are similar enough that I’m reasonably confident anything I tried to write quickly with it would be very hard to read.

An example of Gregg Shorthand

Fast meant using phonetic spelling so that you don’t have to write every letter. It meant memorizing and using “shortened forms” for common words. The phonetic spelling is limited, and the result is that it’s really hard to guess the correct pronunciation when you encounter a person’s name in Gregg Shorthand. It meant big looping shapes that required almost no lifts of your pen except to start a new word.

Fonts for Shorthands

Creating a font has become surprisingly easy. Especially with apps like BirdFont, and the idea of having a font for your shorthand is probably enticing. The problem is that font systems are fundamentally all about letters fitting into a grid. Chinese characters seem like an exception to this, but they’re really not. Yes they represent words, but functionally they’re just more complicated characters on a grid.

A font could be created for something that resembles characters in a line, like Grafoni. Something that was made up of central shapes with diacritics around them - think letters or Chinese characters with marks nearby - could also be made into a font, as long as the characters proceed linearly.

However, many shorthands have a tendency to wander vertically as one letter / sound connects to the next and that’s just not compatible with how fonts work.¹

So, if you’d like to be able to type on your keyboard and have it look like your shorthand, then you’ll need to guarantee that what you design is extremely linear.

It’s hard to be simple

The more you want your writing to flow from one word to the next, the harder it is to have unique shapes. Grafoni and Gregg are good examples of this. Both systems have very few shapes

Grafoni’s creator decided that with precise control of width, or height, one could solve the problem of reusing the same shapes. And, as you can see above, has three sizes for each shape.

Gregg also reuses shapes, but - in my opinion - it’s far more clever about it. Gregg understood that speed and precision were at odds with each other. With Gregg, there are only small and large shapes, and the difference is pretty obvious in practice. Additionally, he understood that it’s hard to maintain angular joins when moving fast, and incorporated the natural curve that would result when trying to draw an obtuse angle quickly.

Gregg shorthand is a master-class of clever decisions, and practical compromises needed to enable professional stenographers accurately capture the live speech of people accurately enough for court documents.

Gregg Shorthand Alphabet.

Fast writing is inevitably going to be a lot of big and small loops, and horizontal lines. Making an abrupt change of direction, or lifting the pen to reposition it slows things down.

Because I was designing a cursive, where I wanted all the letters to connect, I encountered two big problems. The first was that it was difficult to find different shapes for letters that didn’t cause the pen to move up or down. The second was that any shape that ended up at a different level than it started causes words to spread vertically.

You can keep the number of shapes low, by introducing rules like Gregg’s that make it clear that in this situation a loop means this, but in that situation it means something else. Or, you can demand precision like Grafoni does.

Precision wasn’t an option for me. I’d learned that I can manage two sizes of a shape, and that mirroring shapes - either literally, or by drawing them in a different direction - was a practical form of reuse. Combined, these mean that any one shape can be used four times. Unfortunately it wasn’t until writing this paragraph that I actually put those facts together. This is - in no small part - because Korthic didn’t start from scratch, but is an iteratively modified descendent of Orthic.

My need for different letter shapes meant I only partially solved the problem. Here are some of the rules Korthic employs to help get around its problems.

“n” is just a bigger “i”, but when there’s just one in isolation it can be hard to tell which was intended. Context solves the problem most of the time. If you see a word that can be “one” or “oie” it’s a pretty safe bet that the author intended “one”. However, unambiguous letters was one of my primary goals. To address this, I added a rule that a dot over the “i” shape meant it was definitely an “i”. That rule also leverages a rule that English speakers will have already internalized.
“l” and “r” are both little loops on the line, but “r” is always drawn counter-clockwise and “l” is always drawn clockwise. This means that as you are writing from left to right, the “r” will always be on top of the line, and the “l” will always be on the bottom.
“c” and “s” are similar in that the direction they’re drawn in results in them being mirror images of each other.
“p”, “d”, and “k” can all be drawn upwards or downwards, and you can exit the large circle of an “h” at any point. Whenever a word is trending too far up or down, and it encounters one of these letters, it gives you an opportunity to shift the word in the opposite direction.

It’s not perfect though. Korthic’s “u” is a downward slant, and the word “succubus” provides me with no real opportunity to counteract the downward slant of its three separate “u”. I can’t allow users to optionally write “u” in an upward direction, because that’s a “y”.
“c” and “s” both allow you to continue writing along their baseline, or to angle back up to the height of where they started.

Learn from those who came before

Taking the time to learn the basics of Gregg was one of the most valuable steps in my journey to creating Korthic. I think anyone attempting to create a cursive of their own should take the time to do the same. Even though Gregg doesn’t work for my brain, and I ended up creating something that can’t possibly compete with Gregg’s speed, its lessons still informed many of my choices.

Trying to learn Grafoni was also very informative. It confirmed my belief that carefully controlling size was not something I was capable of. Gregg taught me that “obviously small” and “obviously large” don’t require precision, and are distinctions that I can make when writing. This means that, for me every shape could - in theory - be used twice.

Gregg also taught me how to mirror a shape for reuse, and that the direction you draw a shape in can be a clear signal as to which letter you intended. That’s how I ended up with “r” and “l” being identical shapes, that are still clearly distinguishable in actual practice.

My advice is to download, and skim through lots of shorthands. Find ones that look close to what you want, and try to use them. Make notes on what works, and doesn’t work in each one. It’s ok if these opinions are completely subjective, irrational, and / or emotional. You don’t have to justify your hot-takes to anyone. You’re just trying to find out what your brain likes, and learn from other people’s “mistakes” or “brilliant ideas”.

Stand on their shoulders

In your travels through existing shorthands you’ll likely find something that seems close to what you want. For your first shorthand, consider taking that almost - but not quite - shorthand, and modifying it according to the lessons you’ve picked up in your explorations.

Creating a truly usable orthography is a one of those subtly complex arts that you won’t really understand until you’ve done it a few times. Working from someone else’s foundation means starting from a point that’s already worked through many of the complications, and is known to work for at least someone. In a way it’s like having a safety net. When you try something that inevitably fails, you can have confidence that it’s just the thing you tried, and not the whole system, or its fundamental thinking that needs to be abandoned.

Prioritize your goals

Clarity was more important than speed, and - as I worked on Korthic - I learned that after ease of use, aesthetics were the key to making me smile. Because of this, my “e” ended up being extremely flexible. It went from a simple line that went down off of a horizontal line, to any near-perpendicular intersection of two lines without crossing.

It will never be perfect

The 1800’s seemed to be the Golden Age of shorthands, but it wasn’t a time of collaboration and iterative improvement. Instead each shorthand of the era starts with a small treatise on why it’s “objectively perfect” and “obviously superior” to every shorthand that came before it, or sometimes just to the one its author had a grudge against.

The truth is that different people have different minds, and different bodies. No shorthand is perfect for everyone. Korthic isn’t even perfect for me. It’s “u” being a downward slant results in words like “succubus” that go down, down, down and never get a chance to come back up. The “d” involves too much careful drawing for such a common letter.

But, it works for me, it solved my problems with readability, and wrist strain, and it makes me smile. Will I keep using it? Probably. Will I change it? Probably.

No-one cares

No-one cares about physical writing anymore. Cursive is a dying art. So much so that the US National Archives is desperate for people who can read cursive, and help them transcribe historical letters from the US Civil War.

The more technology advances the less need we people see for physically writing. Whisper can transcribe audio with great accuracy and speaker detection at many times the speed of its speakers. A good keyboard and a little practice will enable novices to type over 120 words per minute, and stenotype machines allow professional stenographers to reach upwards of 375 words per minute.

Even the people who are fascinated by shorthands won’t really care. They might say “oh neat” and wander off, but it’s unlikely anyone else will actually use what you create. Accepting this is incredibly freeing. People aren’t going to nitpick your creation, and it doesn’t have to satisfy anyone but you.

Thomas Hill’s shorthand is a great example of this. He created it for himself, and it was never shared with the world until after his death in 1860. It’s a wild shorthand as you can see by this example R4 Unit shared on Reddit. Short vowels are single dots, and long vowels are double dots, and in both cases their position relative to their “seat” (a concept Thomas seems to have come up with) and that relative position indicates which vowel sound it makes. Furthermore, there are only seven pages of documentation.

Thomas Hill's Shorthand

I love that - unlike his contemporaries - Thomas didn’t feel compelled to try and convince the world that his shorthand was “obviously” the best. He seems to have just made something for himself and left it at that. The only reason we know anything about it is that his estate published it along with some of his writings after his death.

Keep track of your changes

I did two things which really helped me.

The most useful thing I did was to shrink down the key for the Alphabet that you see at the top of this page, and put it in the top right corner of every page I wrote in my tablet. This served two purposes. First, it was a reference for learning. This was especially useful when I changed how a letter was drawn. Second it’s a key to reading things written in old versions of Korthic.

The other thing I did was to keep a change-log of my modifications.

The change-log was useful because - more than once - I considered using a shape for a letter that I’d already tried, and discarded. This saved me from trying it again. It also helped me to objectively see which letters I was struggling with.

It doesn’t even have to be useful.

The Neography subreddit is filled with people creating random writing systems they find it fun. For example, check out this Hangul inspired way of writing English that was shared by CPhiltrus.

Hangul Inspired Orthography

Or this “unnamed geometric cypher” shared by LMAONAISE

Unnamed Geometric Cypher

Lots of people create writings systems for their conlangs that no-one will ever use but them. Here’s an example of a font I created for a way of writing my conlang.

Some example sentences in Oho

Resources

Looking Back on Korthic

Creating Korthic taught me a lot. I ended up with isn’t anything like what I started out trying to create, and where my creation diverged from my goals.

In the image above, you can see that “Month” and “I’ve” are radically different looking words. “Month” has long flowing curves which is what I set out to design. “I’ve” is all straight lines and sharp angles. I was specifically trying to avoid shapes like “I’ve” has. Sharp angles cause motion to come to an abrupt stop. The horizontal line on the right was drawn after completing the “V” and repositioning my stylus. That slows things down, and introduces a little more wrist strain. “Know” is somewhere in between with a flowing curve, a sharp angle, and two crossing lines.

Despite all the functional downsides, and the fact that “I’ve” looks nothing like what I was aiming for, I love it. I love the shapes that have emerged as a result of deciding that an “E” is any line that emerges from another at a near-perpindicular angle. I love the way “I’ve” looks. I love that “w” is two crossing lines that sometimes find themselves on curves. “I’ve” absolutely not what I wanted in my orthography, but I had the self awareness to recognize that it made me smile despite going against my rules, and I allowed myself to embrace shapes like that as I designed it.

Korthic is still evolving. The shapes of letters are changing as my speed increases. I’m pretty sure that I’ll reach a tipping point with “d” that forces it into some simpler shape, and the downward motion that “u” introduces is problematic, and annoying. On top of that, I think I want to come up with a phonetic system for writing that sidesteps the insanity of English spelling.

But, I’m proud of it, and it makes my life better every time I sit down to write. I hope that putting it out there encourages someone to try their hand at creating a script for their everyday writing. If that’s you, I hope you have fun. I hope I get to see what you come up with.

If you have questions, don’t hesitate to reach out to me on the fediverse: @masukomi@connectified.com

I’m oversimplifying the capabilities of modern fonts, but not by a lot. Practically speaking, unless you’re a font expert, or willing to do something that’ll only be viewable in web browsers with a lot of JavaScript creating a font for something like Gregg Shorthand just isn’t possible. Assume that you can only create fonts for othographies that work / look like languages you’ve seen fonts for already. English, Korean, Chinese, Hindi, Tamil, Arabic, etc. ↩︎

Leaving Their Clouds

Sun, 02 Nov 2025 00:00:00 -0400

Intro

There are so many wonderful things about a “smart home” if you can afford it. There are so many tiny quality-of-life improvements that really add up. Being able to turn off the lights at night by talking to the air instead of having to walk naked from the switch to bed, and then climb under the sheets in the dark made us giddy for weeks.

The problem is that - for most people - the ownership of their smart home devices is an illusion. Google just killed the ability to control two generations of Nest thermostats from your phone. Phillips changed the terms of service such that you need to create an account, and agree to share you data with them. This change didn’t just affect new users. People who were using their lights without accounts, and without sharing data with Phillips were suddenly forced to go along with these changes if they wanted to keep using their very expensive lights.

Voice assistants were always a privacy concern, but the companies they were attached to at least pretended to not be immoral. Now, we’re seeing their true colors and there are significant reasons to be worried about always on listening devices, especially when living under authoritarian governments.

So, we set about reclaiming the control, and privacy, we should have had all along. We’ve almost entirely separated ourselves from the corporate clouds, but doing so was way more work, and learning than either of us anticipated.

This blog post exists in the hope that it can guide others through the process without so much frustration, and forced learning. It’s not a step-by-step guide to setting things up. There are plenty of those out there already. Instead, this is the collection of all the things that would have been helpful to know before embarking on this journey.

Why Bother?

Protecting Your Investment. Removes the potential for a company to make your devices unusable as a result of dropping support, changing behavior out from under you, not updating their phone app, or changing Terms of Service to something unacceptable
Controlling who can see your data. Stops companies from selling your personal data to law enforcement & random companies.
Removing yourself from the hacking targets. Unless you’re famous or politically powerful, Hackers are far more likely to go after a company server with millions of people’s records instead of hunting down one random individual’s setup. Hackers regularly break into large company’s data centers and steal potentially useful information. When you remove yourself from these systems you’re no longer a target.
No surprise updates. Companies push changes in behavior and functionality to smart devices all the time. You can update your devices still, but most of the time there’s no good reason to. You have a functional piece of hardware that’s no longer connected to servers you don’t control. Remote access and/or control from the manufacturer’s servers is no longer a thing you have to worry about, so there’s not a lot of reason to update and risk things changing or breaking.
Better control. Apple’s Home app is maddeningly dumbed down, and if you don’t like the way they present info, or allow you to interact with the devices there’s nothing you can do about it.

Home Assistant is not only much easer to interact with, it allows you to make custom dashboards of just the information you want.
Centralized control. Some apps do a great job of integrating with Apple Home. Some don’t even bother. Some, expose some controls and info but not all.
Complete control. With Home Assistant you have complete control over all of your devices in one place. If a device exposes some functionality, then Home Assistant will provide that in the UI. Each “Integration” is custom coded for the specific devices and / or protocols. It’s no longer a matter of hoping that the Home app from Apple, Google, or Amazon anticipated the needs and capabilities of whatever random device you’re connecting.
Better Automation Home Assistant provides a simple, and user friendly UI for creating scripts and automations.
Cost savings You’re going to save a ton on the devices you buy going forwards. An extreme example of this is the Air Exchanger we need to install to address CO₂ buildup in our house. An exchanger with decent efficacy and energy efficiency, runs around $3k, however the last time I checked, a smart one with decent controls was $10k. Worse, spending that money is a bet that the company would keep existing and supporting the cloud software it was talking to for the next 30 years. Most companies don’t last that long.

Instead, We’ll be buying the $3k exchanger, and installing some cheap (<$100 each) sensors around the house that will monitor the air quality and turn it on and off as needed.

Is it worth the effort?

We think so. We’re happier knowing that Phillips and other companies will no longer be selling our data. We’re happier knowing that none of our devices will randomly stop working because the company went out of business, or got bored and wandered off like Google did with the Nest thermostats.

We’re happy to be reducing our reliance on companies that have repeated proven they’ll compromise their morals, and treating their customers with basic human decency for cash, or political clout.

Apple has already removed apps from the App store that let people inform their neighbors when ICE is in the neighborhood, even though that’s completely legal in the US. Apple and Google have both broken their own encryption to give governments access to people’s messages in exchange for the ability to sell to their citizens.

On a more personal level, women and trans people are being increasingly targeted in the US, and both companies have done immoral things to help authoritarian governments. There’s nothing stopping Apple or Google from telling their listening devices to report in whenever someone mentions keywords like “Abortion”, or “Transgender”, or mentioning the name of any group the government decides in unsavory.

Home Assistant

The key to making this all work is Home Assistant. It’s a completely open-source replacement for the “Home” apps managed by Google, Apple, Amazon, or anyone else. It’ll also replace all 3rd party cloud integrations, like Phillips Hue’s.

The key thing you need to understand about a “Smart Home” is that your devices need some centralized “server” to talk to and be controlled by. Usually each brand talks to some “cloud” server owned by whoever made the device. If the company looses interest in maintaining that product, or goes out of business your devices will stop working. By redirecting those devices to a server you control, you regain a ton of control and privacy.

Because this is for your home, Home Assistant needs to run on a device that will always be on. You don’t want to loose access to your lights because someone closed the lid on their laptop.

While you can just use an old computer, most people tend to go with a Raspberry Pi comes in. For the non-geeks it’s just a teeny affordable computer that we can install Home Assistant on, stick in the basement, and forget about. Right now - November 2025 - the most expensive tricked-out version of the Pi (the Pi 5 with a whopping 16Gb of RAM) is ~$130 USD, plus a wee bit more for a power supply and a case to keep it safe.

Other options are the Home Assistant Green, and the Home Assistant Yellow. Seeed Studio has a blog post comparing the two. Ultimately, they’re not too different from the Pi. It’s just a teeny cheap, low-power computer that can act as the central hub for your smart home.

Future Proofing

Switching to Home Assistant isn’t locking you in to another ecosystem. Anyone can code up a competing piece of home automation software that you could switch to it at zero cost. If the core team of developers stops working on it, some geeks are guaranteed to fork the project and keep it going. It’s a technology agnostic central communications hub.

Required Cloud

If you want to communicate with your smart home devices when you’re away from home, you’ll need something that can bridge your internal network with the wider internet. Practically speaking this isn’t possible without involving a 3rd party.

The easiest, way is to use Nabu Casa. Nabu Casa is a company created by the people behind Home Assistant. It offers some basic cloud services - like backups, and accessing your local Home Assistant remotely, and they sell some useful hardware devices. Profits from it get funneled back into the Home Assistant project.

This is completely optional.

There is one glaring asterisks though, and it concerns Voice Assistants.

Voice Assistants

Dealing with the question of what to do about a voice assistant was the most intellectually, and emotionally draining part of this. Mostly, it’s because I was misled by the many, many videos on YouTube talking about how you can run an LLM powered voice assistant on your Raspberry Pi, and how easy it is to do.

These videos are all lies… kind-of. It is easy to do. It is possible. It’s also completely useless.

Here’s the thing. There are two types of voice assistants. The ones that are not powered by LLMs are an extremely limited set of hard-coded options that require very precise input, and have no memory. For example, unless you give every device in your home a unique name, you can’t say “turn off X” instead you have to say something like “Turn off Kay’s Stand Lamp in Kay’s office”. Everything has to be very specific and very specifically worded. If you thought Siri’s limitations were frustrating, this will drive you mad.

Then, there are ones powered by LLMs. This is what you want if you don’t want to be pulling out your hair and constantly complaining about how stupid your device is. This is what Apple promised with Siri, but never delivered. Not only can they figure out what you meant without precise wording, they retain context. For example. You could say “Are the lights on in Kay’s office?” and then, if it said “Yes” you could tell it to “turn them off” and it would know what you were talking about.

Even better, when you configure the LLM you set up a prompt that it will use to initiate all new conversations. That prompt can give it guidance on how to respond, and specific instructions to help it work around any frustrating edge cases that come up.

For example. We have a script called “Goodnight”. When I first said “Ok Nabu. Goodnight” The LLM thought I was just wishing it a good night. So, I added the following to its prompt.

Always check if there is a Script, Device, Area, or Scene that matches the user’s input and attempt to use that first. For example, if the only thing the user says is “Goodnight” and there is a script with that name, assume they want you to run the “Goodnight” script, and they’re not just wishing you a good night.

I could have just changed what words I used and said “run the goodnight script” and it would have figured it out, but we like laying in bed and just saying “goodnight” to our voice assistant and having it shut down our house.

Unfortunately there are two problems with LLM powered voice assistants. The first is that you need fast response times. Waiting twenty seconds (sometimes more) for it to turn on a light, is not practical. The second problem is that most people don’t understand just how unbelievably computationally expensive it is to process someone’s text and infer what should be done in response to that input.

Unless you’re willing to drop $7k or more on a beefy home computer with a nice GPU it’s just not a realistic option. So, you need to shuttle your info off to a cloud LLM provider. Trust me. I spent days trying to make it usable with the LLM running on a maxed-out MacBook Pro with an M1. For simple - very specific - requests the best I got was about 10 seconds between asking for something and having it done. More often it was twenty seconds or more. I didn’t even try on the Pi.

For the hardware geeks out there: No networking a bunch of computers to share the processing load is not an option. The latency induced by the machines talking to each other is so great that even adding a second device destroys response times.

The Voice Assistant Pipeline

At a high level you need four things:

a device with a microphone
something to convert speech to text
an LLM to process that text and take action
something to convert the text response from the LLM into a voice

The speech-to-text and text-to-speech can be run on the Pi. It adds roughly one to two seconds of delay to do so. These capabilities are handled by Whisper, and Piper respectively. These are both open source projects and trivial to set up on the Pi. But, I wouldn’t recommend bothering, unless you’re also going to drop a huge wad of cash on an in-home AI server.

Instead, I’d recommend doing what we’ve done and sign up to Nabu Casa’s Home Assistant cloud. In addition to giving us backups, and a way to access our Home Assistant from any device, they also handle the speech-to-text and text-to-speech. Currently this costs $6.50 a month or $65 a year.

Once Home Assistant Cloud converts our speech to text, that text gets handed of to an LLM cloud provider. We’ve gone with Open AI because it was easy, and it really doesn’t matter who you use. You don’t need the best model. You just need a relatively recent model that knows how to work with “tools” and is running on servers with enough power to respond quickly.

Instructions

Gotchas

Homophones, and words that just sound really similar to other words are the biggest source of annoyances. During the speech-to-text processing words can get transcribed incorrectly. For example my office is called “Kay’s Office”, so I say things like “Turn on Kay’s office lights”. The problem is that “Kay’s” sounds a lot like “case”, and “keys”. It’s also indistinguishable from “K’s”. If it gets transcribed as “Case office” - for example - the voice assistant will fail to find an area with that name, and won’t be able to do what I asked. I’ve also found case-sensitivity to be an issue.

Home assistant allows you to specify aliases for devices. In order to figure out what the common mistakes are going to be, I recommend using the “Assist” feature in the Home Assistant app on your phone. It’s just like talking to a device on your counter, except that it shows you the words it thought you said. Try invoking something it has problems multiple times, and catch all the ways it screws it up.

Creating aliases works if you have an LLM or not, but I’ve found a better - and easier to manage - solution is to add something like this to your prompt.

If the user ever mentions a device or area name with “K’s”, or “case”, or “keys” in it, assume they meant “Kay’s”.

To deal with the case-sensitivity I added this.

When comparing the names of Devices, Areas, Scripts, Automations, and other things, always do so in a case-insensitive manner. For example, you should consider “Kay’s Lights” and “kAy’s lIGhtS” to be the same.

Privacy Concerns

Courts have subpoenaed data from essentially - if not literally - every cloud provider out there who has data from our smart devices. Alexa recordings have been used in at least one murder case, even though no-one was trying to invoke Alexa. So, why were there any recordings to begin with? Even if the systems deemed it an accidental invocation, why were those voice recordings saved?¹

Home Assistant doesn’t have this problem. Unlike Siri, Alexa, and Google, there will never be an occasion where the device sends audio to the servers without you knowing, because you’re either pressing a button on your phone to make it listen, or you’re speaking to a puck on your counter, and that puck will always make a sound to let you know it’s been activated and is listening.

You can turn off the activation sound, but why would you? I hated that Siri sometimes tried to do something out of the blue, or all the times I thought it was listening as I tried to set a timer, but it was actually ignoring me and no timer got set.

Incidental Hilarity

Humans can carry on conversations with multiple people, and know which bits are intended for which listener. Voice assistants aren’t so smart. They just listen until there’s a long enough pause. In our house this has resulted in a number of accidental instructions to the voice assistant, when I invoke it while talking to Wifey.

Here’s the most recent example:

Me: OK Nabu, turn on Kay’s office lights. Wifey: Where’s the cat?

Voice Assistant: Ok. I’ve turned on Kay’s office lights. I’m not sure where the cat is. She might be somewhere cozy or hiding out of site. Let’s have a look around.

Something To listen

You’re going to need something similar to an Apple Home Pod, or Amazon Echo to sit around listening for commands. You can’t reprogram those to go to bypass their respective clouds and talk to your Home Assistant server instead. So, you’re going to need something new.

The Home Assistant Voice Preview

The easiest option is the Home Assistant Voice Preview. It costs about $60, and we’ve been pretty happy with ours. You’re not going to want to play music on it - although you can - but as a voice assistant device it completely out-classes the $700 Apple Home Pod, and it’s all because of that silly little ring of LEDs.

The first reason is that it makes it obvious that it’s actually working. When you invoke it the lights rotate clockwise. When it’s thinking it flashes. When it’s responding the lights rotate counterclockwise. You never have to wonder if your words have gone into a void and will never be responded to.

The second reason is that when you set a timer the ring lights up, and then gradually turns off sections. With just a glance you can easily know that there’s about ¼ of your timer left to go.

For the DIY geeks out there, it has a Grove port on the bottom so you can easily connect your home-made sensors.

The Atom Echo

Another option is the $13 Atom Echo. The speaker on this is tiny and sounds awful, and isn’t very loud, but the reviews are good, and if you just want a cheap device that’ll sit nearby, listen to you, and respond, this seems like a good choice. I’m thinking of getting one for my desk.

Unlike a microphone plugged into your computer, or Raspberry Pi, both of these devices have chips specifically dedicated to noticing when the Wake Word (“Ok Nabu” by default) is spoken.

Note about the Home Assistant Voice Preview

At the time of writing (November 2025) the setup has one really rocky step. You connect your phone to it as part of its setup, but then it gives you a poorly named text field where you need to enter the IP address of the device that it’s talking to. This means you’ll have to log into your router first to see what IP address gets assigned to the puck.

Talking To Your Phone

I can only speak to the situation on iOS, but I believe the same ideas apply to Android too.

Apple wants you to be locked into their ecosystem. As a result, there’s no way to replace Siri with any other voice assistant. There’s no way to have your phone always listening and have “Ok Nabu” work. Worse, when you tell iOS to stop listening all the time, multiple things stop working, or start being really buggy.

When I’m in the car it will no longer read text messages to me. It shows that they came in on the screen, but won’t automatically speak them. I assume this applies to headphones when I’m walking around too, but I haven’t tried that. More frustrating is that pushing the button to invoke Siri only seems to work about ¼ of the time. It’s not uncommon for me to have to press it 5 times before the little Siri listening animation appears, unless it’s connected to the car, in which case it always works.

Fortunately the Home Assistant phone app has enabled all the integrations, so there are lots of ways to create Shortcuts that can live on your main screens, or buttons that’ll live on the control panel.

Wake Words

There are multiple built-in options if you don’t like invoking the listening pucks with “Ok Nabu”, and if you’re geeky and willing to spend about ten minutes training a new one and loading it onto your device you can make anything into a custom wake words.

Radios

Most smart home devices aren’t plugged into ethernet, and don’t use WiFi, but you still need to be able to control them remotely. So, you need a radio transmitter that can speak the appropriate language on the appropriate frequencies to integrate with your devices.

The short short version is that you’ll need an antenna for whatever radio + digital protocol(s) your devices need, and you can’t reuse the same antenna for different protocols.

Protocols

Digital communication protocols are like languages. Radio protocols are more about radio frequencies and hardware.

If you prefer video over text, check out this video: Matter vs ZigBee vs WiFi vs Bluetooth vs Thread vs ZWave - Which is the BEST Smart Home Network?

WiFi

The same thing your laptop uses to talk to the internet. Wifi devices will probably talk to your existing network. The problem with WiFi is that it’s really power hungry and will drain batteries way faster than any of the alternatives. Don’t use WiFi devices unless they’re always plugged in.

Zigbee & Zigbee2MQTT

Zigbee - sometimes noted as ZHA - is a digital communication protocol, and a radio communication protocol. Zigbee2MQTT - usually just noted as Z2MQTT.

To understand the high-level difference between the two I recommend watching Zigbee2MQTT vs ZHA (Zigbee Home Automation) - Which should you use for your Smart Home? The basic summary is that Z2MQTT is slightly more powerful, but not in a way that most people will care about, and beginners should really just use ZHA.

What’s cool about Zigbee is that it’s low power, and creates a mesh network. All the devices that are constantly plugged in like light bulbs and power outlets act as relays to devices that need to be extremely conservative about their power usage, like battery powered air quality monitors.

Also, there’s a wonderful directory of Zigbee Compatible Devices that’ll help you find things you know will work.

The most important thing to know is that Zigbee (ZHA) is what most Hue light bulbs use. So, if you’ve already got a bunch of Hue bulbs, this is what you want.

Note that sometimes adding a ZHA device can take longer than you would expect. They’ve very responsive once added, but finding them on the network the first time can take up to a minute.

Matter

Matter has been getting hyped by Apple and Google, but it’s only a digital communication protocol. It can - theoretically - be run over any radio protocol. But in practice it can work over the Thread radio protocol or Wi-Fi.

If you choose to try and integrate with Matter devices you’ll need to make sure those devices have Thread radios in them, and that you have an antenna that can speak Thread.

Z-Wave

Z-Wave is another radio + communication protocol that works over a mesh network. It’s not as energy efficient as Zigbee, but it’s a decent option.

Bluetooth

Bluetooth is terrible for smart home devices. It works, but unless you live in a shoebox, you’re going to have issues with range. Bluetooth devices also have a tendency to only work with an app made by the manufacturer. As soon as they stop maintaining that app, or the servers it uses, your device becomes useless.

For example, we have Aranet CO2 sensors. They use Bluetooth. Home Assistant has an integration for them that works great, but unless it’s a few feet away from the Pi our Home Assistant is running on, they may as well not exist. Even our phones can’t see all of them at once.

Hardware

If you have Zigbee - ZHA or Z2MQTT - devices I recommend the SONOFF Zigbee 3.0 USB Dongle Plus Gateway (~$40). You’ll also want to get a USB extension cable so that you can physically separate it from what it’s plugged into, and other devices in order to minimize radio interference. My understanding is that it can only do ZHA or Z2MQTTT, but not both.

If you have Z-Wave or Thread devices I recommend the Home Assistant Connect ZWA-2 antenna (~$70). Note, it can be configured to speak Z-Wave or Thread, but not both. If you have both types of devices you can use two antennas.

Once you plug these in to your Home Assistant computer they’ll show up in the Devices and Integrations screen automatically. They’re both trivial to add in, and add devices to.

We have a Zigbee ZHA antenna because we already had a bunch of Hue lights, and a Z-Wave antenna to talk to our new thermostats.

Lights

Most of you will have smart lights. You’ll likely have Hue lights too. This makes the decision of what radio & communication protocol to use pretty easy. You want Zigbee ZHA.

The vast majority of Hue bulbs speak ZHA already. All you have to do is delete them from your Hue app, and they’ll automatically go into pairing mode. Then add them to the Zigbee integration in Home Assistant. The only Hue lights we had that weren’t findable by new Home Assistant setup were some white-only ones. Check the database if you’re wondering if yours are supported.

Once you’ve separated yourself from the Phillips Hue cloud - or any equivalent system - things suddenly get much cheaper. For example, I just bought 4 full color light bulbs from Third Reality for $30. A three-pack from Hue costs $100.

Smart Switches

You can make a room’s “dumb” lights “smart” by replacing the wall switch with a “Smart” switch. This is significantly better than something like a Hue switch, because it’s not reliant on the software. It works as a regular switch even if your Home Assistant server is down.

I love this, but there’s another way to achieve the same result. Instead of replacing the switch you can easily wire in a small smart control unit in the wall behind it.

Smart Home Device Shopping Gotchas

Now that you’re freed from needing to use a particular manufacturer’s device, you’ll have a lot more options. However, you need to be careful about the protocol. In my experience most of the manufacturers spam keywords on Amazon. For example, search for “Zigbee lights” and you’ll get a bunch of lights that don’t speak Zigbee, but instead work with Apple HomeKit, Google Home, Matter, or whatever.

Be sure that whatever you’re about to buy specifically states that it’ll work with whatever radio setup you have, and remember that Zigbee ZHA and Zigbee2MQTT are different things. Look for “Home Assistant” in the reviews too. It’s always a good sign when you find it.

The other thing to watch out for is no-name fly-by-night Chinese resellers. When buying Zigbee compatible products for example, you’ll spend a little more for a brand name like Sonoff or Innr, but these are companies that are trying to build a name for themselves and make quality products. Read people’s reviews.

Automating Things

Home assistant has a concept of “Automations” and “Scripts”. The distinction wasn’t obvious to me at first, but it’s ultimately quite simple. An “Automation” is a collection of instructions that’s triggered by some event (time, sensor reading, whatever). A “Script” is a collection of instructions that’s triggered by you (pushing a button on your phone, voice control, whatever).

Here’s our “Evening Vibes” Automation. Sunset triggers the closing of the shades in our bedroom and living room, and turns on the living room lights. Note that window shades / blinds are referred to as “Covers” in Home Assistant.

Automation Example

Here’s our “Ready For Bed” Script. When we say, “Ok Nabu. Ready for bed.” it’ll turn on the lights in our offices, and the bedroom. Both of us have reason to make a stop in our offices before going to bed, and it also helps us to see the way to the stairs.

Note that we haven’t specified which lights. We’ve just instructed it to turn on the lights in an Area. If we add or remove lights from that area the script will do the right thing.

Script Example

There are also Blueprints and Scenes. According to Home Assistant, “Blueprints are reusable automations and scripts that can be easily shared.” while “Scenes capture entities’ states, so you can re-experience the same scene later on. For example, a ‘Watching TV’ scene that dims the living room lights, sets a warm white color and turns on the TV.”

Cost

Note: We already had a Raspberry Pi with Home Assistant on it. A new top-of-the-line Pi 5 would be $130, + $15 for MicroSD cards, + another $30 or so for a case and plug.

Replaced Things

Zigbee antenna to replace need for Hue hub & our connection to Phillips servers.
- $40 Sonoff Zigbee 3.0 Antenna Dongle
- $12 Fancy USB-A Extension cables.
4 Hue lights weren’t Zigbee compatible. $30 for a four pack.
Wall plugs We had Meross plugs but one of them started acting up, and the Meross integration isn’t officially supported, and, and, and… it was just easier to replace them. $35 2 pack from Innr
Open AI less than 1¢ USD per day.
Nabu Casa Subscription $6.50 per month, or $65 per year. There’s a free trial to make sure it does what you want.

This isn’t technically required, but it was a good solution for giving us remote access, and offsite backups. Also, it supports the ongoing development of Home Assistant.
Listening Devices We had one Home Pod that we replaced with Home Assistant Voice Preview Edition for $60. However, because our phones can no longer act as always on listening devices, we added two additional “pucks”. One in the living room, and one in the bedroom, for a total of $180.
Yale WiFi adapter When we bought our Yale lock it had a Apple Home Kit module in it. That only talks to Home Kit, but we were able to swap in a $62 WiFi module. This isn’t great, because Yale is a complete shit-show when it comes to their management of smart devices, we’re still tied to their cloud, and the company has been sold twice since we bought the lock.

Grand Total for replacement hardware: $359 + subscriptions to Open AI and Nabu Casa.

New Things

Z-Wave Antenna $70 Home Assistant Connect ZWA-2
Z-Wave Thermostats 4 Honeywell T6 Pro Z-Wave Thermostats @ ~$170 each. ⚠ This is a discontinued product. I didn’t really care because it had good reviews, thermostats get discontinued all the time, and we have no need of their support and / or servers because it’s entirely locally controlled.
4 new lights for the fan in my office $41 four pack of Zigbee lights from a brand I’d never heard of.
DIY CO₂ sensors Combining an ESP32-C6 board ($6) from Seeed Studio that can speak Zigbee ZHA with an SCD-41 CO₂ sensor from Adafruit ($50) plus some wires to connect them ($15 for a spool set that’ll probably take years to use up), and a 3D printed enclosure.

~$57 per sensor

Just requires soldering 4 wires, flashing the ESP32-C6 board - just plug it in and visit a web page - and sticking it in an enclosure.

Pre-built alternatives range from $200-$300 each.

Note: we didn’t actually need the Z-Wave antenna. There are Zigbee thermostats, but life conspired such that we ended up with the antenna and decided to use it instead of returning it.

Total cost of new additions: $962, but $680 of that was the thermostats.

What that bought us: control over our thermostats + the ability to automate them & see what the temperature is in the various heating zones of our house, better lighting in one room, and addressing one of the prerequisites to getting an Air Exchanger so that we stop having to open windows in the middle of the winter.

As a developer I understand that companies store recordings of accidental and intentional activations for training purposes. Apple claimed everything was anonymous, but leaks revealed that wasn’t true. Since then Apple has been going out of its way to help the US government’s authoritarian plans. There is no reason to believe they won’t give them access to recordings of anyone the government is interested in. ↩︎

Vulvic Thoughts

Wed, 22 Oct 2025 00:00:00 -0400

Table of Contents

Thoughts, and observations I’ve had since acquiring a vagina
- Hygene
- Sex
  - Cravings
  - Motions
  - Orgasms
  - Oral Sex
  - Intercourse
- Misc

Thoughts, and observations I’ve had since acquiring a vagina

⚠ This post contains unfiltered descriptions of many things related to a vulva. These are things you do not discuss in “polite” society. If you don’t want to hear details - pleasant and not - about having a pussy then you should not keep reading. Please note. Some of this knowledge is cursed.

Most of this stuff will be well known to vagina-havers, but maybe interesting to hear the discovery of. Some of this stuff is very specific to the experience of getting a custom vagina install.

Hygene

Peeing

Urethral Opening

As anyone with even a passing familiarity with female genitals knows, the urethra is not on the outside.

I never really thought about the implications of that until I had to deal with it. It’s so clean for penis-havers. The opening’s right out there with nothing in the way. You pee. You maybe have a single drop you shake off. The end.

I suspect how this plays out is different for every vagina-haver based on body fat, and the shape and thickness of your labia minora, and majora. I dunno, I haven’t really watched videos on the subject.

In my case, the labia minora spread apart when I sit on the toilet, and pee just kinda “finds a way” out. It’s like turning a ravine upside-down, and the water that was at the bottom either drops out directly, or runs down the sides.

When tissue is engorged from arousal, or overheating, or whatever. Then the walls are pressing in, and it sounds like you’ve put your thumb over the end of a garden-hose.

Also, without metaphorically - or literally - hosing it down, there’s no way to remove all the pee. There’s gonna be a small amount left in there, clinging to the inner walls. So, that’s… a thing.

Water Flows Downhill

You know what’s lower than your vulva when sitting on a toilet? Your butt cheeks. Some of the pee goes “out”, but sometimes some of it runs “down”.

No-one warned me about this!

I was not prepared to wipe a stream that traveled a few inches down my butt cheek.

Temperature Matters

Pee is your body temperature when it leaves you, and there’s not a lot of wind in a toilet bowl. Sometimes this means it gently runs across a small bit of flesh and I don’t feel it until it reaches a hair.

Toilet paper

Toilet paper obviously something created, and promoted, by a men. It’s fine for the butt, but it’s a fucking terrible solution to the problem of cleaning or drying labia after peeing.

The stuff disintegrates and sticks to whatever it’s touching if it even sees moisture. Using it to dry a bunch of wet fleshy folds behind a bunch of hairs is a terrible idea. Any penis-havers reading this should try pouring water onto a sidewalk and then trying to dry it with toilet paper. It’s at least that bad.

I always wondered why my wife used such big wodges of it to dry herself. Now I know. It’s the only way to not get pee all over your fingers.

Also, I keep finding teeny pieces of it stuck to my labia. Not like every time, but still… If I was sexually active I’d be terrified of letting anyone play around down there without taking a shower first. I keep my upside-down peri-bottle around because we don’t have a bidet, and sometimes I feel like “fuck it. Get out the hose”

Scent

I mean this in a good way. My pussy smells like pussy. At least, like I remember cis. pussy smelling. It’s been a while.

But, it’s also a warm, dark, moist place which is party-central for bacteria that make scents. Maybe I’m being overly-sensitive. But I feel like a daily shower is a requirement now, not just a social norm.

Sex

Cravings

For context: I don’t really care what anyone has between their legs, but I’m attracted to girl-shaped-people: femme, butch, cis, trans, whatever. “Guy” things are turn-offs: facial hair, big muscles, deep voices, toxic-masculinity, patriarchy, etc.

With the exception of one guy - nearly 30 years ago - I’ve never craved cock… until acquiring a pussy. A few after surgery - when my hormones were going crazy - I wanted nothing more than to be fucking railed by a big hard cock in my pussy. Now, my hormones are back to very cis-female levels, but I keep getting an occasional craving to be fucked with a cock. Not a cock-shaped-dildo, a cock.

To be clear, the idea of being fucked by a guy is a massive turn-off. Additionally I could barely fit a thimble in my pussy, never-mind a cock, so this isn’t even possible. And yet…

It’s just very confusing, and I don’t know where it’s coming from. On top of that is the thought that even if I did have a trans girlfriend with a penis that she actually wanted to use I wouldn’t be able to satisfy the craving anyway, so what the hell am I supposed to do with any of this?!

No, don’t say anal. My butt’s afraid of anything that big. Plus it’s not what I keep craving.

Motions

I’m not sure what I expected. So much importance is placed on the clit. Especially regarding a guy’s ability to find it, and make it feel good.

What I wasn’t expecting was that some of the things that I saw in porn, but didn’t make any sense were real, and not just for show. Like, slapping your mons just above the clit, or taking all your fingers and rubbing the flesh covering the clit without directly touching it.

I wasn’t expecting my clit to be so damn sensitive that I rarely touch it directly. I was expecting that to be the focus of fun-time. Maybe that’s just a me thing though. Don’t get me wrong, things feel great, but not directly.

Orgasms

I described the sensation in my surgical post, but despite the sensation having changed quite a lot before surgery, I wasn’t prepared for how radically different things would feel after.

Personally, I think it’s so much better, but I imagine most guys wouldn’t agree. It feels so… Feminine? Soft? Glowey? Liquid? Not at all like the thrusting targeted burst of before.

I didn’t really have any expectations with regards to multiple orgasms, beyond it being a possibility, but the whole “you can just keep going, and it just keeps feeling good until you come again” is… interesting.

Oral Sex

I’ll tell you when / if I find out, but I can’t wait to find out.

Intercourse

Don’t know. Won’t know. Despite the cravings, there’s nowhere to stick a penis-shaped thing.

I still think minimal depth - that ended up as zero - was the right decision for me. Feel free to hit me up on Mastodon / The Fediverse if you are contemplating going for minimal depth and have questions around that decision.

Misc

Shaving

Why is it so difficult?! Maybe I just need to practice more.

Shaving a scrotum is hard, but it makes sense why.

Nerve Mapping

Tissue got moved around, and repurposed. This has a couple weird side effects.

I don’t actually know where the pee comes out. I’ve tried looking when I’m peeing but it’s around a curve, so I can’t see it directly. What I know is that the skin it’s exiting past was roughly 1cm up from the base of my penis, just below the left-most point. That’s a weird place to feel pee exiting.

What’s worse, is that I can’t find this place with my finger. Touching with my finger feels completely different, so I can’t do anything to tell my brain where it really is, and remap it. I could try touching while I’m peeing but that sounds like a very messy proposition.

Normally you’d remap nerves by showing your brain - usually visually - where the sensation is coming from, and doing this repeatedly until the brain “gets it”. There are multiple places where I’ve done this either through sight or touch, and it’s actually hard to think of where feelings in those places used to come from.

Then there’s the itching. Every now and then I get a little itch, and I have absolutely no idea where to scratch. Worse, running my fingers around in an attempt to chase the sensation down doesn’t really work. I don’t even know if it’s a real itch or just a phantom itch.

Visuals

The outsides look great, but after five-and-a-half months I still haven’t caught sight of my urethra or my clit. It’s really hard to hold my phone and photograph with one hand while sufficiently spreading things with the other, and - to my eyes - things look a bit weird in that area with everything pulled back. I honestly don’t know because I’ve never seen a cis woman spread things apart in this manner (nothing like you see in porn).

Things feel great, and work great, so I’m not complaining - plus someone staring at the insides like that would be weird - but I really do wonder WTF my clit looks like, and why I haven’t found my urethra yet. The latter should be easy but…

The Sex You Enjoy Is Irrelevant To Your Queerness

Tue, 26 Aug 2025 00:00:00 -0400

Table of Contents

Preface

Lesbians on the internet are mad at me for suggesting that being a lesbian is about who you’re attracted to / capable of loving and not about what sex acts you can enjoy the physical sensations of.

Apparently conversion therapy people claim that if a lesbian can find sex with a guy pleasurable they’re actually straight and/or like guys.

The conversion therapists are fucking stupid, and ignorant.

This post is all about showing that the things that pleasure you in the bedroom have no bearing on your queerness. You’re whatever flavor of queer you say you are, and the things that make your body feel good are only coincidentally relevant to the gender(s) that you’re attracted to and capable of loving.

Note: While this post is centered around lesbians, the general concept & conclusions are relevant to all queer folk.

Some Simple Facts

If you’re a queer ally you’ll agree these are all true. If you’re a homophobic or transphobic bigot, you won’t. This post is for the former group. Bigots can fuck right-the-hell off.

Furthermore for all the flavors of lesbian presented below, I’m assuming there are other lesbians who find them attractive and can fall in love with them.

Many women have spent years having sex with guys and sometimes finding that sex enjoyable prior to coming out as lesbians. We still accept their claims of being a lesbian as valid. Thus having enjoyable sex with a guy doesn’t invalidate being lesbian.
Ace lesbians exist and are valid, thus you can be a lesbian without wanting to have sex with women.
Trans-femme lesbians exist and are valid, thus enjoying sex that involves a penis doesn’t make you not a lesbian.
Trans women are women, even when they boymode, and even when they haven’t started hormones. Thus looking physically male, and still being physically male doesn’t make someone any less of a lesbian.¹ Yes, this makes a lot of people uncomfortable, but tough shit. Accepting trans people means accepting some - currently - uncomfortable ideas, and throwing out a lot of puritanical bullshit.
You can fall in love with a woman, who comes out as a trans man, and it doesn’t suddenly make you straight, even if you still love them after surgery. Continuing to enjoy sex with them doesn’t make you straight either.
Flat chested lesbians exist, thus it’s not about needing boobs for sex / attraction. Also, Gynocomastia (AMAB guys w/ natural boobs) exists and the presence of boobs isn’t an exclusive feature of women. Cis women come flat and chesty, and so do cis men.
Trans-masc lesbians exist (yes really) and are valid, and thus it’s possible to be a lesbian and be attracted to butch-ass women with beards and muscles.
Cis bearded women exist (various reasons, not just intersex) and thus - again - it’s possible to be attracted to lesbians with beards.
Non-binary lesbians exist thus invalidate all arguments about boy/girl bodies.
Intersex lesbians exist and they take the concepts of sex, gender, and queerness out back, and have their way with them until they’re begging for more, and can’t remember their names.

Putting it all together

NONE of these facts have any bearing on what a given person finds physically attractive. It doesn’t mean a femme-loving lesbian is any less of a lesbian if they’re not attracted to bearded muscle-mommies.

NONE of this has any bearing on who a person finds emotionally attractive or lovable. You do you kid. Love who you’re gonna love.

NONE of this means that lesbians aren’t only attracted to women.

ALL of this together means that what a person finds physically pleasurable has nothing to do with gender, and thus nothing to do with their queerness.

If you say the physical stuff a person enjoys matters to someone being a lesbian or not you’re invalidating the existence of 1 or more groups of lesbians who are ace / trans-femme / trans-masc / non-binary / intersex / flat-chested. Probably a bunch of other groups I haven’t thought of yet too.

If trans women are women, and butch women are women, and trans-masc men are men, and femmy men are men, and intersex people exist then you can’t argue that the physical aspects of the body that pleasures someone is relevant to that person’s sexuality.

The only thing that’s left is “who are you attracted to and/or capable of loving?” if you’re a girl who’s attracted to girls, you’re a lesbian regardless of the physical attributes or acts you find pleasing.

Lesbians, and straight men can enjoy getting pounded by cock, just like gay men, and straight women can enjoy pussy. It sounds nonsensical, but it’s the only possible conclusion of accepting that intersex and transgender bodies are valid.

Conclusion

If you want to be an ally of all queer people, you HAVE to accept that the physical aspects of attraction and pleasure are separate from gender, and the flavor of queerness someone claims to be. You have to accept that the only thing that matters is what gender(s) a person is capable of loving and / or being attracted to.

That is to say, if you say you’re a woman who’s only attracted to / capable of loving women, you’re a lesbian, regardless of what your partner’s body looks like, or what makes you feel good in bed.

If you’re a guy only attracted to / capable of loving guys you’re gay, regardless of what your partner’s body looks like, or what makes you feel good in bed.

Pan people are pan, bi people are bi, and straight people are straight, regardless of what their partners’ bodies look like, or what makes them feel good in bed. People are whatever they claim to be because everything else falls apart when faced with the reality that intersex and trans people exist, and are valid.

What about the edge cases?

What about aro-ace, intersex, and nonbinary folks? They are whatever the hell they tell you they are, regardless of what their bodies look like or what their partners’ bodies look like.

What about the people who love enbys and/or intersex folks? Again, they’re whatever the hell they tell you they are.

Conversion Therapy Bullshit

I hate that I have to add this, but it’s been made painfully clear that I do.

This is the opposite of what the conversion therapists are saying. They’re arguing that you are whatever makes you feel good in bed. I’m arguing that you are whatever you say you are regardless of what makes you feel good in bed.

I’m arguing that liking “manly” women has nothing to do with liking men, because “manly” women, are no less women than femmy women. I’m saying that enjoying your trans girlfriends cock has nothing to do with liking men, because your trans girlfriend is a valid girl. I’m saying that liking femmy women makes you no more of a lesbian than liking butch girls, because women are women.

Cis human bodies are too fucking variable to be relevant to the question of sexuality. Trans human bodies throw everything on its head. The only relevant question about someone’s body is “do you find that one attractive?” The possession of penis / vagina / testes / ovaries / womb provably doesn’t make someone man or woman or male or female. Birth defects, surgeries, and intersex people are the most obvious reasons why. Things like being tall, muscled, bearded, short, effeminate, etc. all exist in male, female, and intersex people. So liking a body with specific features is irrelevant to your sexuality. It’s just what you like in a body.

If you still think this is “conversion therapy bullshit”, I’d like to encourage you to read what I actually said without assuming I’m implying something I haven’t said. Read it with the knowledge that I’m autistic, and thus am absolutely shit at the game of saying one thing and meaning another.

A conversion therapist who tries to use my arguments will fail, because they all boil down to “you’re queer if you say you are” or “you’re a lesbian if you’re a girl who only likes girls” regardless of anything else.

You can’t argue that a pre-op, pre-hormone trans woman (i.e. physically male in all respects) who likes women isn’t a lesbian AND support the belief that trans women are women. They’re simply incompatible claims. Boymoding doesn’t make trans women male, any more than it makes cis women, or intersex women male. To argue that is to argue that gender is the product of clothes and/or makeup and thus we are whatever we wear. ↩︎

Looking For Beta Readers

Sun, 17 Aug 2025 00:00:00 -0400

Table of Contents

Overview

I need beta readers for my books!

If you’re interested in spicy, sapphic, polyamorous, slice-of-life stories set in a world where catgirls exist, and not everyone’s kind to them, then keep reading!

This page will explain what I’m looking for, and what to expect.

The only credentials you need are to be open minded about queer and poly stuff, and interested in reading a book like the one described below.

If you’re a professional proofreader, editor, sensitivity reader, etc. who would be interested in working on stories like that, I absolutely want you to send me your info & rates, but I’m not quite ready for you yet. See “How To Contact Me” below.

Why I Need Readers

I’ve had some of my technical writing published before, but this is the first novel I’m putting out into the world, and frankly I’m scared. I think it’s pretty decent, but I don’t know if the story, or the writing style, will work for others. I want to find out if this is worth paying a real editor $$$ to go through a whole bunch of words with a fine-toothed comb, or if there are glaring problems that need some real revision.

No worries if you’re not interested in reading something that hasn’t made it through a professional editor. I’ll still need people to read it after editing.

What I Need & Don’t Need

Right now I’m looking for high level feedback about what works and what doesn’t. I need readers who are willing to set politeness aside and give me honest, and constructive feedback. I mean this literally. I’m autistic. If you try to not hurt my feelings I won’t understand what you’re hinting at. Kindness, is - of course - always appreciated.

I’m specifically not looking for feedback on basic grammar and punctuation. I’ll be hiring someone to tackle that problem. Hopefully my grammar’s good enough that you won’t want to huck your e-reader into the wall.

This book (tentatively “Alex’s Story”) is ~147k words, or about 1.5 average novels in length. If you don’t finish it, that’s fine. Just give me feedback on what you read, and why you ended up not finishing.

What You’d Be Reading

Description

In a world that can’t decide if catgirls should be treated as demons, slaves, or people, Alex is an autistic catgirl who can’t always speak. She finds herself falling for Lex, a coworker with a loving partner and an amazing kid. It’s a relationship Alex wouldn’t dream of harming, but the universe forces her to admit her feelings, and discover that Lex is polyamorous, and willing to take a chance on her, if she’s willing to take a chance on loving someone who already has a partner, and kid she loves.

It’s a cozy, sapphic, mildly-spicy, polyamorous, slice-of-life story about finding the place where you belong, and the people who’ll love you for who you are.

Content Warning

Much like the rising tide of fascism and transphobia in the real world, this story is set against the backdrop of bigotry the characters must exist within, but have no hope of changing.

The main characters live with the consequences and/or challenges of autism, mutism, selective mutism, limb-loss, severe scarring, and anxiety. This isn’t “disability porn”, or a cheap attempt to pull at your heart-strings. They’re simply the things these people live with, and - in a couple cases - the things that help bring them together.

It involves characters who are lesbian, asexual, demisexual, nonbinary, Latina, East Asian, Caucasian, catgirls, humans, and even some straight white married couples.

While this is - overall - a cozy tale of finding love, it touches briefly on memories of childhood bullying, suicide, suicidal ideation, and a house fire that results in death and severe injury. In the “present day” there is a scene that deals with the immediate consequences of a nearby bombing of innocent people.

None of these are core elements of the story, and none of them are explored in detail, but they are notable moments that effect, or have effected, the character’s lives.

A Quick Note About The Catgirls

While the books I’m working on do involve catgirls, this is not what I’d consider “furry” fiction. It’s just a world where some people happen to have some catlike physical attributes.

It’s simply following in the grand tradition of sci-fi stories that follow people who are almost - but not quite - like us as a means to hold up a mirror to the world around us.

How To Contact Me

The best way to contact me is on the Fediverse at @masukomi@connectified.com .

Email works too, but I’m effing terrible with email. Please send info to masukomi@masukomi.org and put “About your book” in the subject line. I’ll try and have my mail app notify me when anything like that comes in.

If you’re interested in reading, let me know if you’d prefer an ePub or PDF file.

Bottom Surgery With Dr. Purohit

Mon, 11 Aug 2025 00:00:00 -0400

Table of Contents

Overview

For trans-femme bottom surgery, it’s expected that - for the most part - you’ll be able to return to your normal life approximately three months after surgery.

This post strives to document what that actually looks like, what you can expect, and also what to expect if you choose to work with Dr. Purohit and his team for your bottom surgery.

If you know me in real life, and haven’t already been following the details of this journey you probably shouldn’t read this. If you’re a coworker or potential employer of mine you definitely shouldn’t read this.

⚠ WARNING This post contains post-surgical photos of a neovagina. They’re all hidden behind spoilers and I’ve tried to describe what you’ll see before clicking so you’re not suddenly faced with a bunch of vulva pics at various stages of healing.

Which Surgery

I went for minimal-depth Vaginoplasty for a variety of reasons. This is sometimes conflated with Vulvoplasty, or Zero-Depth Vaginoplasty. These are not the same thing.

With minimal depth you will end up with a short vaginal canal. How short is primarily dependent upon how much material your surgeon has to work with, and what kind of labia minora you ask for. Frequently it’s somewhere around 2½ inches (6.35cm).

This surgery does not require dilation to maintain whatever depth you end up with.

Summary & Thoughts After Five Months

For those of you who aren’t interested in reading my daily commentary, or seeing the progress photos here’s my basic take-away.

High Level

I’m thrilled with the aesthetics. I think Dr. Purohit, and his support team are excellent, and I would highly recommend them.

They did a good job, and were very responsive when I ran into problems. See day’s 13-15 below for details on problems & how they handled them.

My body doesn’t seem to be particularly good at dissolving stitches in between my labia minora. The expectation was that after roughly six weeks all the stitches would be dissolved. Twelve weeks in and the stitches in the touchable areas inside me have only barely begun to dissolve. Some research said it can take up to twelve months. They were mostly gone after 16 weeks.

Description of Stich unpleasantness

[written at the 3 month mark] Sticking a finger inside me feels like sticking it into a bristle brush. I find it emotionally disturbing, and only do so during my daily cleaning.

Most of the time I can’t feel the stitches unless I stick a finger in me. However, sometimes I wake up in the middle of the night feeling one of them poking me and have to reach in and move things around.

I believe the stitches near the clit are keeping the nearby tissue hypersensitive.

Edit: ~4 months in the stitches were dissolved but could still be felt under the surface. ~5 months in they were completely undetectable.

It should be noted that I do have non-trivial scaring below my vagina. This was entirely my fault. I slipped and ripped those stitches (day’s 13-15 below).

For observations about masturbation and orgasm, see Week 22.

Photos

Note: In many of these photos you will see a shiny white patch at the bottom of the V shaped surgical scar. The white is just an artifact of the light reflecting off the shiny surface of the scar tissue. Again, that large area of scar tissue was entirely my fault. The vertical line you see to either side of my vulva is more typical of the expected scaring.

The scar is as wide as it is near the bottom of the V because I ripped a number of stitches at the end of week one. This is the result of my own stupidity and should not reflect on Dr. Purohit’s work.

This picture’s a little misleading. The labia minora happen to be in V shape today, but that’s not standard. (see next pic)

Week 12

The arrangement of my Labia Minora seems to change on a day-to-day basis. Sometimes they look more like Week 12 above, and sometimes they’re more like Week 15 below.

Week 22

Here’s what things look like with my legs mostly closed.

Week 12 Vulva Legs Closed

And what they look like when I’m standing.

Week 12 Standing

And a demonstration of how little depth I have.

Finger inserted into vagina

This photo shows my finger fully inserted. I couldn’t press it in any farther if I wanted to.

⚠️ odd looking internals

Clitoral detail view

I thought maybe my clit would settle into a more normal shape as the swelling went down, but after five months I’m reasonably confident that this is just what things look like. That horseshoe looking thing up at the top? That’s my clit. It looks weird, but it feels amazing.

Things I’d wish I’d known

In no particular order…

There is a very long period when you’ll look fine, and feel ok, but you really aren’t. Even ten weeks in a trivial amount of standing or moving can leave you sore and needing to lay down. Stairs are evil, because they don’t hurt to go up or down, and they’ll make you far more sore than a little walking around.

I’ve spent a lot of time frustrated and wishing I could help out more around the house but really not being able to.

The feeling of the catheter moving when you shift or walk is worse than the soreness from the surgery.

They can’t repair ripped stitches. There are good reasons for this, but I didn’t know them when I ripped some, and I really wish they could have. Don’t take any chances with how you sit or move.

Three months isn’t the point when “You’ll be able to do all your normal things.” Three months is where you can reasonably expect to survive going to a standard desk job, as long as you don’t have to walk there. You’ll still need to sit on a donut.

A data point I wish I’d had was that cyclists find that they can’t comfortably ride a bicycle until after six to eight months. Most folks who responded to that reddit thread needed to wait until eight months.

At months I was able to spend a few hours a day at my desk as long as I had my donut.

Questions / Comments

If you have any questions feel free to ping me on Mastodon / The Fediverse at @masukomi@connectified.com If you’re not on the fediverse, then… sorry 🤷‍♀️.

Notes from the Healing

What follows is a mostly an edited version of the diary-style entires I posted to Mastodon during my recovery. However, I’ve also added photos from the relevant weeks.

It should be noted that we later learned that what I describe as “discomfort” from soreness and/or aching is what most people would describe as a 3-4 on the pain scale. A single Extra Strength Tylenol was sufficient to address it.

⚠ WARNING: what follows is extremely TMI. It goes into detail about things most people are uncomfortable discussing, including wounds, bodily functions, physical arousal, and more. The photos from the first few weeks are not easy to look at. This is intended for other trans-femme people considering bottom surgery.

Note for folks who followed this as it happened on Mastodon Feel free to skim the text and just look for photo buttons or headings that say “(w/pic)”. I’ve made sure there’s at least one photo from every week.

If you’re just looking for progress pics the first few weeks have “(w/pic)” added to the daily posts. After I stopped posting daily each of the weekly updates has a picture.

Week 1

May 19th, Pre-surgery

Had to go in at 5:30 AM, and wait in a tiny lobby downstairs until everything actually opened upstairs.

I was called a few minutes after going upstairs and registering, but my wife wasn’t allowed to join me initially. They took me into a bay, and a series of people came in and ask questions, had me sign things, and gave me a gown and socks to wear.

They were being very reasonable, but as an autistic person this was an incredibly stressful experience. To many things being thrown at me too quickly with no preparation or knowledge of what to expect. I really wish I could have had my wife with me for support. If I’d known she was going to be allowed to come in later I would have advocated for her being there from the start because of my autism.

Eventually the let her in and things got a lot better because she acted as my support human.

When Dr. Purohit came in I showed him the photos I’d collected since we’d last talked, including a surgical result from one of the other surgeons at Mt. Sinai that I really wanted him to try and come close to.

He said that what I wanted shouldn’t be a problem.

What he didn’t say was that by asking for more prominent labia minora I’d be sacrificing depth. It would be a while before I discovered this.

I was then led into the surgical room which had about a dozen people in it, and looked nothing like what you see on TV.

They lead me to a table that looked like a stick-figure with separate adjustable areas for your arms and legs.

The anesthesiologist said something, they put a mask on me, and I was unconscious within seconds.

May 19th, Post-surgery (w/pic)

Surgery took about 4½ hours.

I woke up in what I assume was some post-surgical ward. I could see a blue curtain in the direction of my feet, and hear a nurse moving around to my left, but I couldn’t move my head. My throat was sore from the breathing tube and I really wanted some water, but I couldn’t talk.

I found I could lift my right hand though, and I finger-spelled “w.a.t.e.r” to the nurse. Unfortunately, she didn’t know sign, but she guessed, and I gave her a thumbs up. She gave me some water, and then I passed out again.

I woke up in a private room.

Posts from May 19th

Surgery went well. I’m not on anything more powerful than Advil and I feel zero pain. Literally. A feels like I overworked some muscles. That may change tomorrow as things start to swell.

All the anxious stress hurting my belly and jaw clenching is gone.

Nurses are practically giddy about the quantity and quality of the “textbook pee” I’m producing.

Actually I lied, I am in pain. My throat is really sore from the breathing tube.

I’ve also learned that there are no lights in this room that can be controlled from the bed, and I’m not allowed to leave the bed.

It’s getting quite dim but my eReader has backlight so I’m good. Also I think I’ll probably fall asleep soon anyway.

In more entertaining news. They have me wrapped up in gauze and tape such that I look like an actress in a low budget 80’s sci-fi movie.

compression bandages

Posts from May 20th

I asked if I should expect more pain in coming days. She said probably not to expect change from surgical site. Normally what’s most noticed to catheter (yup) and intestinal gas (yup).

She did say I may still be working through remnants of anesthesia so it’s possible pain will increase when that’s fully gone, but also that it should be manageable with drugs.

Also I’m not allowed to lay on my side. 😔

I should note that engaging muscles at site does hurt, so my first time out of bed may be miserable. 🤷‍♀️

Had a visit from a urologist I hadn’t met before. (3rd female doc I’ve seen so far). My job for today is to lay in bed.

She seemed surprised I’m already passing gas. Personally I’m thrilled because gas has been the most uncomfortable thing so far.

Mentioned it hurts when I engage groin muscles. She said “yeah we don’t want you doing that.”😉

Humorous note: had a spark of pain after shifting which brain told me was at the base of my 🍆. No idea where it actually was as everything is still hidden by inches of gauze.

Also doc just leaned over and looked at and felt felt my groin (gauze really) without preamble which was … “oh um. Ok. That’s a first😄” in my head.

Good news. Surgeon just stopped by and said I can walk around later today. Very happy about this because my lower back needs to move.

I got a visit from a lovely service dog named Jemma, but I think she’d had enough for the day.

I walked! I was rudiculously light-headed after laying down for ~30 hrs. but… I walked and it didn’t hurt

Will repeat in ~1 hr. Still might get discharged today but won’t know until evening

Been having trouble getting a nurse to come this afternoon. Not sure what’s going on. IV machine ran out like an hour ago and beeped at me incessantly (we hates it precious) finally got someone to come and walk me again 1hr later than planned.

I’m officially sick of this place and want to go home. Seems like I will be discharged this evening 🤞

Walking gives me a minor headache and makes me soooooo tried

[Note] I didn’t get discharged. I wish I had, because there was an elderly woman across the hall who listened to her television at full volume for the next 30 hours.

Posts from May 21st (w/pic)

Last night was miserable. Pressure bandages are stuck to my belly. Every time I breathe in it expands and pulls on them. Eventually this lead to me only breathing very shallowly when half asleep.

Eventually replaced the lidocaine patch nurse and I couldn’t figure use foot but that took hours.

Neighbor still listening to TV at full volume until a bossy nurse went and turned it down on my behalf at 11pm.

Woke up with sore jaws as of clenching all night.

Groin finally hurting. I desperately want this pressure bandage off. Convinced I’ll feel better when it’s gone. Hopefully not wrong. At least I’ll be able to breathe without it pressing on my belly.

Also NEED to get the fuck away from the sound of stupid laugh tracks - even at lower volume. It’s maddening.

Oh and I felt like I was going to barf last night, which would have been terrible time I move so slowly so they gave me a bucket and some anti-nausea meds.

I think the pressure dressing was part of that problem too, with every breath pulling down on my belly.

Drugs were given. Pain wandered off. Now just bored. Waiting for doctors to come and finally remove pressure dressing.

New nurse was talking about how I should be walking and was like “let us know if you’re light headed when you’re walking” to which I asked “am I supposed to be walking without you?” And he was like “…no”

I replied that I’d walk whenever he came to walk me.

I am a lean mean farting machine.

I magically convert food into farts…and boredom, so much boredom.

I got bored and asked to be taken for a walk. Went well, although got accidentally misgendered by assistant.

Breakfast came finally. I asked for fruit plate because I figured they couldn’t fuck it up. [Note: I’ve been editing out most of the complaints about the food.]

Eating is still uncomfortable with pressure bandage pulling against tummy.

In ~1hr pressure dressing will be removed. They are just waiting for some labs to come back. Then I get to walk and hopefully not bleed. Then - dear gods, I hope - I will get to be discharged.

I have never hated broadcast television more than I do right now.

It’s melting my brain and I’m not even watching it. Had to listen to three episodes of Andy Griffith show already. I don’t understand how it’s even on TV still.

They have removed the pressure dressing. I have a picture of my new bits! They are very bruised but otherwise doing well.

there is no more pressure on my tummy from the tape. I am so happy.

Unfortunately, they have given me MiraLAX which I now need to drink. I hate that stuff.

Drinking lots of it for my colonoscopy (unrelated), traumatized me.

⚠ The following photo includes fresh stitches, minor bleeding, and a catheter tube

First Photo After Removing Pressure Bandages

They said I’d be discharged today. I’m still waiting on I don’t know what for that to happen. Maybe we’re still waiting on the surgeon to say the photo looks good. Maybe you’re waiting on some other stuff. I thought the other stuff had already been taken care of.

They said someone would come to check if I was bleeding after walking. No-one did. Of course, no one asked me to go walking either.

And more positive news the old lady who listened to TV at maximum volume appears to have left.

Also, I have been instructed on how to empty my catheter. The very helpful nurse was trying to encourage me to get up and walk whenever I felt like it. Wanted me to work towards being more independent. Didn’t seem to really understand that that is not medically advised for me right now. Too much walking Will increase swelling.

They only want me to walk 150 to 200 steps a day.

I feel like the ultimate whiny kid but I just want to get out of here. I am so sick of listening to the beeping machines and other people’s televisions and laying here.

I want to go home and be with my wife and dogs because it feels like there is no point in me being here any longer. I’m just waiting for permission to go and being subjected to terrible food.

😭

Whine.

Kept having occasional little twinges of sharp pain, like a teeny poke with a needle. 🪡 couldn’t figure out why, so went hunting. Found the culprit.

It’s just the nerves doing their healing thing, but I think I just didn’t realize where the end of the stitches were.

Peeking Past Bandages

I’ve been officially discharged!

Of course, this means my wife is driving into the city during rush-hour and then back out shortly there after while it will still be going, but I don’t care that I will have to spend more time in the car.

Soon… soon I will be free! Soon I will have these IV things removed from my hands! So I will not have to listen to other people‘s televisions!

Side note: doctor from urology came and checked, and I have not been bleeding despite walking. So yay for that.

We made it to the Air BnB, and I pooped, which was unexpected, and huge, and lead to bleeding. Finally in bed and warm and blissfully quiet.

Tummy’s unhappy, but I’ll eat some bread soon and see how that goes.

Posts from May 22nd

Wifey piled blankets on me & gave me fuzzy socks because I was freezing, and black dog has been glued to me all night, with black and white dog splitting time between wifey and i.

My biggest problem is digestive. Intestines and tummy unhappy. Pain is completely managed with single Tylenol every 4 hrs which is 🤯 completely mind-blowing. Although the packing is an uncomfortable pressure.

(We’re in different bedrooms while I recover)

Black dog keeps wanting to hang out between my legs. I’m ok with this.

Turns out the only sensitive areas are pretty well protected, except for the catheter tube.

Was telling wifey that it doesn’t feel like anything’s changed. There is discomfort from the packing and from the catheter, but I never really felt much from that region anyways, and I don’t feel much from it right now.

when I do feel something from the nerves, they are still informing me that it is in the old configuration that is being touched. That’s not going to change until I start touching it and knowing what I’m touching.

I have seen the photo. Other people have seen the real thing and commented on it.

When I sat on the toilet and looked down there was no limp noodle. There were two swollen labia majora, which was cool but also doesn’t really tell me much.

From my angle it was just two bumps. Also I was very preoccupied with what was going on with my butt and how weird the stupid catheter tube feels.

I know things have changed, and yet it doesn’t feel like it.

I have every confidence that this will change once it is safe and healthy for me to start feeling around down there.

Until then, it’s just weird.

Side note: I can’t really look at it because my underwear is holding gauze rolls in place and those are holding the catheter in place, so everything of interest is completely obscured.

I don’t intend to remove the gauze until I have to poo or shower. I am not really bleeding and I don’t have an infinite supply of gauze logs.🪵

I have showered. It was exhausting, but I’m glad I did.

Still not touching my bits because everything is fragile and I don’t want to make anything less clean.

BUT I caught a glimpse of myself in the mirror and that was nice. Also, boobs, 😜

I thought I had to poo. I was wrong, but finding out involved removing things and accidentally wiggling the catheter, and now I have a very unhappy urethra.

Not having to get up to pee is pretty cool, but not cool enough to keep wearing one of these fuckers. I can’t wait until I get it removed Wednesday.

The packing is constantly uncomfortable and the catheter is usually not noticeable, but when it is it’s VERY noticeable and very unpleasant.

In other news: I read through the surgeons notes about the procedure they performed. I have no idea what 50% of the words mean, but as far as I can tell, they encountered no problems.

Also, I theoretically have a clit, clitoral hood, vagina, labia minora, and labia majora. I can only personally confirm the latter, and the fact that I am no longer the owner of a wet noodle… despite what some of my nerve endings might think.

Pretty happy about the no wet noodle part. That thing was annoying.

Posts from May 23rd

I am not cut out for bed rest. This is maddening. I need to move. Is 3:30 pm and every hour of sleep has been a struggle.

Also my lower back really hurts but I’m not allowed to lay on my side.

Somehow, I didn’t expect laying in bed to be the hardest part of recovery.

Posts from May 24th (w/pic)

Got some disposable post-partum underwear from Target. Large elastic things. Tried it out last night to see how it compares to the ones the hospital sent me home with.

Woke up with serious sensory issues from how snug they are. Too tight on my skin, and they pulled the gauze logs 🪵 too tight against me.

Probably fine for allistic people.

I brought a bunch of normal panties I can wear after Wednesday morning, when I get rid of the catheter and can switch to pads for the tiny bit of blood.

catheters still suck, but repeated tests have shown that I can poop all by myself, just like the big kids. 👧

I dunno why, but anything that results in significant catheter wiggling just exhausts me.

Decided I’m taking daily showers anyway just because it’s something I can do that involves standing up for a while, doesn’t use up my limited step budget, and feels good.

Got some good photos today. Thought I’d update status for anyone planning on getting a surgery like this.

~5.5 days since surgery

Bleeding: ~1/2 teaspoon a day
Bruising: lots
Swelling: plenty but well within expectations
Pain: none at site w/ minimal tylenol
Bowels: happy. Pooping daily
Mobility: great (all things considered)

Other: Random pain in outer right thigh. Nurse says it’s not clot but also 🤷‍♀️ I have significant numbness in inner right thigh, as well as catheter discomfort, and internal discomfort from swelling.

[Future edit: The bruises in this picture look miserable. You’d expect this to feel absolutely miserable. It didn’t. A single Tylenol really was enough to address the soreness.]

Heavy bruising and Catheter Tube

Commentary: Pain levels feel too good to be true. Had “oh shit“ moment wondering if no pain was related to numbness. It’s not. Just thigh & a little area on upper right pubic mound. Clearly nerve damage but nerves heal on unpredictable timescales so who knows when / if this will improve. Labia majoria have good sensitivity but I’ve been careful to only touch during my freak out.

Looks: 🤷‍♀️ too swollen to guess.

New neovaginas are NOT pretty things. Like really. There’s something in there that looks like a chrysalis & I have no idea if it’s clit or labia minora. Not willing to touch yet to find out. That means no spreading to see either.

[Future Edit: It’s the labia minora.]

Random: 150 steps a day is a ridiculously low number and mentally hard to deal with. My lower back is also regularly pissed. And my sleep is effed.

Long showers are the bestest physical and mental health thing I’ve found.

The head of my 🍆 itches. I started to reach out and scratch it. 🤦‍♀️

Fortunately I stopped myself before I touched anything (especially the damn catheter) but then I realized I have no idea where the eff to address that itch anyway.🤔

Posts from Day 25th

I pooped and then took a shower. It did not end well.

TIL that there’s an implicit connection between catheter wiggles and executive dysfunction. Wiggle it enough times in a short enough period and you can no longer make decisions… or I can’t at least.

Week 2

Posts from May 26th

Woke up this morning having an erotic dream and feeling my bits responding.

Hasn’t happened in ages.

Also seems unlikely my testosterone levels have gone up, although my blood pressure isn’t being pushed down by Spiro anymore.

Was also odd in that - having not touched anything (stitches still there and still bleeding ) - I don’t really know what’s going on down there when this happens. There’s a feeling of pressure - which is probably being effected by the packing - from some erectile tissue somewhere, but I don’t know where & the nerves will keep sending confusing signals until I get the go ahead to start fondling things & retraining my brain.

I’m like “well something’s happening & it feels interesting but…” 🤷‍♀️

In other news: 📰

Discovered some discharge this morning (puss?). Called home health care nurse agency for advice and they’re sending someone today instead of tomorrow, so yay for having resources to help.

No symptoms of infection elsewhere in body. So I’m not worried, but I’m unwilling to brush off infection stuff and hope it’ll fix itself

Woohoo! 🎉 nurse says is reasonable discharge given location and doesn’t look like an infection.

Also noted that my swelling and bruising have gone down greatly and that that means things will be more sensitive which would explain increased discomfort with catheter wiggles.

Related: the saline water she used for some cleaning was very cold. 🥶

Also nurse suggested that my leg pain was likely due to placement of straps on leg during surgery and may take a few weeks to stop.

[Future edit: It went away eventually. I think it took about 2 weeks.]

Took another shower. It was a learning experience.

Lesson 1

Needed to shave above cooch because the intersection of autistic skin sensitivities and constant pressure and shifting from gauze log 🪵 on hairs is 😭.

Used electric razor but there’s swelling, the top of the stitches is right there at the edge of what I’m shaving, & I can’t see anything clearly that far away. Hands were shaking as a result.

Don’t think I will need to redo soon but will ask wifey to do it if I do.

Lesson 2

Tylenol was scheduled for 30 mins later. I should have waited until after that was taken and kicked in.

At end of 4hrs I can feel throbbing and more discomfort even when laying around. Showering plus increased sensitivity from less swelling + increased sensitivity from basically no pain meds + shower = groin that feels like I did kegel exercises with 20lb dumbbells attached.

It occurs to me that they gave me a dilator and I have yet to look at it.

Honestly I wasn’t expecting one. Most minimal depth girlies don’t need to dilate, and he sacrificed depth for labia so I’m really shallow (theoretically).

I think the swelling was hiding more pain than I realized. Currently have Tylenol and Advil coursing through my veins and still feel uncomfortable throbbing. And when I move the catheter is more likely to make me make bad sounds. I think the swelling may have been helping hold it in a specific position.

I forsee a THC+CBD gummy being added to bedtime regiment tonight.

Posts from May 27th Catheter Removal Day

Took the THC+CBD gummy. Sleep came fast and easy but dang… I was not a fan of those brief moments of semi-consciousness between REM cycles.

I do NOT enjoy altered mental states. At least not the recreational drug induced kind.

Nurse suggested I update doc with photo re discharge yesterday.

He just responded:

There is a little bit of breakdown on the backwall. We’ll take a look tomorrow. Minimize movement. Overall looks amazing!

We have no idea what “breakdown” or “backwall” mean here but. 🤷‍♀️ we’ll find out tomorrow and “looks amazing” is good.

[Future edit: Breakdown meant ripped stitches. Backwall was just what they call the area at the bottom of the V. I don’t know why.]

For two days now by body has been convinced that my 🍆 is laying vertically up my abdomen and it’s driving me buggy.

I am honestly, a little afraid that my 🧠 will be stuck, thinking this until I am allowed to touch my bits freely and that might be a week or two for all I know. 😨

I guess I will find out tomorrow.

It’s a weird, icky, and somewhat dysphoria inducing sensation, and I don’t like it.

Posts from Day 28th

I am back at the AirB&B doing something I’ve been dreaming of for days now: laying here with nothing on my lower half save socks.

My autistic skin sensory issues have been so SO upset about having underwear and gauze rolls pressed against my crotch and hips for 9 days with only brief breaks for showering.

IT IS FUCKING GLORIOUS

I’m allowed to touch myself!

Was also instructed to gently clean the various folds and such out with q-tips.

Going to wait until after I shower later, but I am thrilled to begin The Great Nerve Remapping Project.

[Future edit: I did actually draw a little diagram noting which bits of penile tissue ended up where, but it turned out to be far less interesting than I’d hoped.]

She said clit may be hypersensitive for a while and not so enjoyable to touch. Also I should expect~6 weeks until all the stitches are healed and no more bleeding.

So the quest for the Next Great Orgasm will have to wait. 😢

This was expected, but…

9 days out, there’s enough swelling in the labia majora still that my urethra has no hope of sending a stream straight out. Instead it’s like someone’s pointing a garden sprayer at my anus and everything in between gets wet.

This would be vaguely humorous, except that the only open wound I have is at the bottom of the my vagina. I.e. directly in that path.

I left my upside down peri bottle at home. 🤦‍♀️ Should have another tomorrow.

Cleaned with Q-tips. Can confirm there will be no Happy Fun Times involving Ms. Clit for quite some time.

Mostly “hypersensitive” but there’s one spot right by a stitch that’s “FAAAAAAAAAAAK!!!!!!!!!!!” When you barely brush it. It’s been maybe ten minutes and I can still feel the ghost of that touch.

But hey. On the upside: nerves seem to be working there. 👍😄

Posts from Day 29th

Bladder control seems to be 👍. Almost had an accident last night though because after ~9 days with the catheter I’d learned to just relax when I felt the need to pee.

Felt the need to pee as I was about to lie in bed. Started to relax. Then brain was shouting “NOOOOO!” and I managed to clamp down and not wet myself.

Physician’s Assistant said stitches will probably take about 6 weeks to heal. Also said that things will likely be hypersensitive until a little before then. So, masturbation should poorly wait until then.

UNFORTUNATELY my adrenal gland appears to be freaking out about the sudden decrease in testosterone from testes and is overcompensating and making me horny AF. Especially when I wake up (nap or night).

😭SO HORNY, but touching would hurt terribly and probably damage something.😭😭😭

Unexpected Notes From Horniness (extra TMI)

I identify as a lesbian. The idea of being fucked by a guy is a massive turn-off.

However, for the next couple days I wanted nothing more than to be fucking railed by a big hard cock. I desperately wanted to masturbate too. Looking back on this from 12 weeks out, I’m very glad I resisted the temptation. If this happens to you, trust me, you definitely should not try at this point. Just deal with being horny.

Today I got to experience the “wonderful” bit of puberty (2nd) where a young woman learns the hard way how to place a pad so that it’s far enough forwards to get all the stuff at the top and far enough back to get all the stuff at the bottom.

There’s a reason I’m wearing disposable underwear. 🩲

I wouldn’t say this experience is necessarily “euphoria giving“ but it is making me smile. This is helped by the fact that I know I won’t have to deal with the quantities of 🩸 that a teen girl does.

Status update: labia majora swelling has gone down enough that:

I can see most of the labia minora when spreading my legs
I’m only peeing in the right side of myself
I wasn’t afraid to spread things enough during special cleaning to access my vaginal canal and clean it with a q-tip

We have applied Manuka Honey 🍯 (as per physician suggestion) to where the stitches pulled apart at the bottom.

I am non-jokingly afraid of ants 🐜 in my current location.

Still can’t play around with my bits, so still getting weird signals. 🧠 keeps telling me that my 🍆 is laying weird and I need to adjust it.

🤦‍♀️

I can’t wait for day 42 when I can (hopefully) fondle things, if for no other reason than to get my brain to stop giving me stupid misinformation about my genitalia.

Thought while I got ready for bed:

Despite the cost and discomfort, I have a vagina, and that’s incredible, and amazing, and wonderful.

And it would have never been possible without the years of incredible support my wife has given me. She is incredible, and amazing and wonderful too.

I’m a very VERY lucky girl in so many ways. I’ll try to not lose sight of that.

Posts from May 30th (w/ pic)

Interesting observation re waking up horny.

Pre-hormones: morning wood was frustrating and dysphoria inducing

On HRT: it just didn’t happen, and that made me very happy.

Post-op (w/ adrenal gland overcompensating): I just feel horny with no negative anything. Well, none beyond my inability to do anything about it.

Nurse came by. Then I applied honey 🍯 (so weird) and took updated pics. Things are healing SO fast. It’s a little hard to believe.

I’ve decided I’m not going to share pics (at least not here) but I want to because I just can’t convey how fucking impressive this is, and I want to be like “holy shit! Look at how amazing this is!”

Pretty sure most folks would be grossed out by the early day pics with all the swelling and bruising and bulgy Frankenstein stitches.

[Future Edit: this post is all about the pics, so here you go.]

⚠ While not bloody this does show a small open wound where the stitches have ripped.

Week 1 Healing Progress

The orange goo near the bottom of the V is just honey. I forgot to take the picture before applying it. The labia minora are pretty swolen still.

Deep cleaning status update:

swelling continues to decrease visibly every day.
was able to spread labia minora enough to see into where my urethra is hiding. Still haven’t found it, but lighting wasn’t great.
vaginal canal / “dimple” continues to be the source of most blood (i think) And is VERY sensitive in a way can’t explain yet.
anything made with the corona continues to be uncomfortably hypersensitive

Posts from May 31st

Status update: nothing particularly notable today. Just continued gradual improvement.

Full night’s sleep with stress dreams related to inability to position my bottom half as I want, and real desire to go home.

Been low energy and grumpy 😾 all day. Had a video call with friends we haven’t spoken with in months. It exhausted me.

I had a minor accident trying to sit on the bathtub edge. Ripped open multiple stitches at the bottom of the V. Left a disturbing blood splatter on the tile.

Bleeding hasn’t continued notably.

🤞Hoping they’ll have me come in to fix it Monday as it looks significantly worse like this.

[Future Edit: It gets worse, and I later learned that it’s not safe to re-stitch a wound that has ripped open if the rip is just superficial like mine was.]

⚠ Warning: this photo contains minor blood in the open wound where the bottom of the V has ripped farther open.

Ripped Stitches - The beginning

Posts from June 1st

Massive relief.

Messaged surgeon a pic and explanation, then messaged his Physicians Assistant when I couldn’t find a working number for the office.

He asked me to call scheduling woman (wonderful lady) and ask her to get me in first thing Monday. 🎉

Left her a voicemail. Hasn’t happened yet, but 🤞

Was afraid it was going to get blown off since it will heal fine, it just won’t heal pretty. I’ve read too many horror stories of uncaring surgeons.

Week 3

Posts from June 2nd (heading home + doctor’s visit)

Have avoided looking at my cooch today. I know it’s not THAT bad but I’m afraid anyway.

Misread Dr.’s note. He wasn’t asking for me to have her schedule something first thing in the morning. He was asking me to talk to her first thing in the morning to schedule something. 🤦‍♀️ needless to say she hasn’t called back yet, but I suspect a call early morning.

…

Physician’s assistant took one look at it. Said “it’s already healing up” advised me to keep putting Manuka honey on it and sent me on my way.

Not entirely thrilled with this outcome, but on the other hand, no new stitches.

OK so, this is a little silly, but before surgery I bought a bunch of underwear, the kinds I couldn’t really wear with dangly bits.

The plan was to ride home wearing my “celebratory underwear”. Well I’m basically not bleeding today and we’re heading home shortly so …

Side note: feeling annoyingly useless as wifey packs the entire car by herself since I’m not allowed to lift anything > 10lbs (4.5Kg) and I’m pretty sure I’m already way over my step limit for the day.

On top of that, I can’t even drive us home. :/

Posts from June 3rd (w/pic)

I don’t know what things looked like when I went into the doctor today. I hadn’t taken a photo yesterday or this morning.

But, for reasons, I just took one now, and I have ripped so many stitches open.

There is a ripped open area under my vagina that looks like the fucking Joker’s smile (without exaggeration).

Things are mostly healed , as stitches heal from the inside out, but I fear I may have really fucked things up aesthetically…

⚠ Warning wide wound where stitches unraveled. No blood, but very unpleasant to look at. I recommend not looking.

The rip got wider

I first I thought it was the extra physical exertion today in helping as I could too leave the AirBnB BUT I realized that I basically haven’t bled at all today. Just a tiny bit of spotting.

I think things may have just unraveled between the initial rip and this morning.

That is an incredibly disturbing thought. I don’t like it.

In the morning, I will email the person who looked at me today, and ask her what she saw. Not that it changes anything, but…

As an aside, it has been explained to me that getting stitches to pull things back together the way they were was never really a thing they could do. There is too high of a risk of stitching bad microscopic things into / under your skin in this scenario.

Good news, bad news.

Good news: despite the fact that I have completely forgotten to medicate myself all day today, my cooch does not hurt.

Bad news: I’ve also forgotten to hydrate myself all day, and my head really hurts. 🤦‍♀️

Bonus, annoyed news: I’m really sick of having to lay down and re-apply honey every time I pee because I’m still peeing all over myself and washing away the honey with either the pee, or the peri bottle as a wash myself afterwards.

Also, I lost my underwear. I know where new underwear is, but that’s not the point. I had a pair of underwear to put on after I applied honey and then life happened and now I don’t know where that pair of underwear has gone.

At my dog suggestion, I got my ass out of bed again. I went to hang out in our plant room, which doesn’t have many plans these days.

The cat came and found me. In the process of getting into this position, she made sure to shove at least three of her feet directly onto my healing cooch.

It was not pleasant. I did not make happy sounds. That’s I don’t know if it was all 4 feet.

I was squeezing my legs together, unconsciously & was putting pressure on my groin, which caused my brain to inform me that my left testicle is being uncomfortably compressed.

🤦‍♀️

I understand the confusing nerve input about penis bits because some of them still exist and are wired up and I am unable to retrain my 🧠 yet, but this is just weird. Even more so because when I spread my legs in response, the sensation went away. 🤔

When swelling is really bad the difference between yesterday and today can be pretty obvious, but after two weeks I have passed that point.

Now my barometer for how much the swelling has gone down is how much I pee on myself when I go to the bathroom.

I’ve gone from garden hose spray of all things below, to strong trickle down one side. So… progress. 🎉

Today I kept getting seconds of nothing on me and getting excited. Someday soon I shall pee without having to wash myself afterwards. 🤞

Posts from June 4th

sexy dream things

Took a nap. Woke up horny again. Why when I wake up?!

First waking was good and bad because I was dreaming I was masturbating and SO close to coming 😸 but then I woke up and couldn’t touch myself to finish the job 😾

So my 🧠 doubled down on taunting me.

Second time a recurring dream visitor tried to seduce me (very successfully) and it almost hurt to push her away and tell her no because I hadn’t discussed it with wifey.

2 thoughts

I appreciate that my subconscious won’t cheat either, but gods damn it I’m so ducking horny & can’t do anything! When is this going back to normal?!
why do I have a recurring visitor in my dreams who keeps trying to seduce me? I don’t think she ever talks, but I am confident we know each other pretty well. Which makes sense given that I’m demisexual. A stranger trying to seduce me wouldn’t get anywhere even in my dreams.

And since i’m already deep in TMI territory…

The most physically uncomfortable part of this whole fucking thing has been my autistic skin hypersensitivity going absolutely insane about having underwear on me almost 24/7. My pubic mound is so very, VERY uncomfortable I keep having to just take off my underwear and sit here with nothing touching it.

So I’ve spent a lot of time laying with everything covered except my crotch. Soooo frustrating and uncomfortable

lying around without underwear

I can’t sleep without underwear though because I can’t guarantee my butt will stay on the pee pad and i’d mess up a pillow between my legs.

Today I tried shaving extra extra well so there would be no little hairs for the underwear to brush against, and wearing normal underwear instead of the temporary underwear and wearing a thinner pad. I was just throwing everything at it, hoping it would work, but now I am laying here with my cooch exposed to the world again.

Posts from June 5th

Status Update: My labia minora no longer look like overinflated worms practicing Shibari! Instead they look like… labia minora 🎉

Ok, technically the bottom bits are still a bit “inflated” looking but overall, it’s amazing and I’m so effing happy.

Ripped stitches are healing well.

[Future edit: See the picture on June 7th]

I’m no longer bleeding on anything. Instead I’m “honeying”. I’m not applying it after peeing in the middle of the night, but other than that I’m being a good girl and always applying afterwards.

I’m still upset about not being aware of how much depth I would be sacrificing in order to have pretty labia, BUT I think he may have done a tremendous job on the aesthetics. Although, there’s something weird going on with my right labia minora in that it seems to just blend into my clit. That seems unlikely to be what’s really going on because why would he/they do that? Hard to be sure because pushing my clit around for a better look-see is guarantee to not feel good because of that one stitch.

Posts from June 6th

Another day, another chance to be completely blown away by the human body’s ability to heal.

I’m ~50. I don’t heal even remotely as quickly as I did in my 20s and yet every morning, I can see visible improvements at the surgical site.

Wifey had not seen for a couple days and happened to bring me something as I was applying honey last night. The “wow” and look of surprise on her face when she saw the recent changes was humorous, and also helped confirm that I wasn’t just being overly hopeful.

Deep Cleaning Discovery: Things seemed healed enough to try spreading more and getting a better look. Turns out, that really sensitive bit that I thought was my clit, but oddly seemed to flow into my right labia minora? Turns out, that’s not my clit. That’s just a puffy side of my clitoral hood. I found the real deal hidden up inside. Haven’t seen it, but i definitely felt it. So, woo hoo! Can’t wait to have fun with that.

Honestly I was trying to find my urethra, to better understand why I’m still peeing on myself. Still haven’t found that. I suspect that my eyesight’s just too poor to see it with a mirror (too far away) and I’m gonna have to ask wifey to get all up in there and investigate after the stitches are gone.

Side note: I know this is ridiculous given the circumstances, but I feel so stupid being ~50 years old and suddenly discovering my own clit, or mistaking labia for it.

Posts from June 7th (w/pic)

still waking up horny as a teen-ager. Still incapable of doing anything about it.

~23 days left until stitches are all dissolved. 😭

[Future Edit: that date passed a while ago, so many stitches left in me. 😭😭😭]

In other news: wifey gave me a thick pillow to shove between my legs so that i can sleep on my side.

I seem to be spending the whole night with it there as i rotate between my back and other side.

Feels a little silly waking up with a giant pillow sticking up between your legs.

I’ve decided to go without a pad or honey today. I think i’m getting a rash down by my 🍑🕳 from too much moisture. 🤔 Maybe i need to blow-dry the area after rinsing myself (peri bottle) after every pee. ugh. I’ve just been using a towell for drying since getting home, but maybe not thoroughly enough. 🙁

Note: If you looked at the last one, I promise this one is a lot better. The wound is almost entirely sealed up.

Swelling be going down

Posts from June 8th

I forgot to put on a glove while applying honey.

The results were entirely predictable . 😾

Week 4

Honestly, this looks worse than the last one. Don’t click.

Week Four Status Photo

The black spot at the bottom of the V is a stitch. The small rip near the top of the left arm of the V hides a stitch. The swelling is just pushing the flesh out around it.

Posts from June 9th

I didn’t wake up horny AF this morning!

Progress! Or… or just a one-off. Only time will tell. 🤷‍♀️

🤔 just realized that that’s a kinda weird thing to be excited about.

“Hooray. I wasn’t horny!” - me

Doubly so in a world where most folks seem pretty obsessed with sex. I mean, I’m a fan too but like… under the right circumstances. When the vibe is right. Not like “hey stranger. you’ve got a hot bod. let’s fuck.” My demi ass can’t fathom that anymore.

I’d been working towards hair free bits, but hadn’t completed the long process before surgery.

This morning I was thinking how much I was looking forward to being able to get my cooch hairs lazered because there are some now that I’m really not thrilled about attempting to shave.

This evening I remembered I’d have to shave them to get them lasered. 🤦‍♀️

Posts from June 11th

just had a realization that I should have had a while ago

base facts: I’m having to keep things as dry as possible to deal with this rash. I’m putting honey on my ripped stitches to aid in healing. When I have honey on me I have to wear underwear and a pad to keep from accidentally honeying things. Underwear and pad help trap in moisture.

realization: The rash is a massive pain in the ass. Literally and figuratively. The only downside to pausing honey, is longer healing time on the stitches. There are a LOT of downsides to anything that increases the time it takes getting rid of this rash, and most of them are REALLY uncomfortable.

If i stop putting on honey (temporarily) I can run around with no underwear (I have pee pads on the sitting places just in case of whatever) and get maximal exposure and drying time.

I’m going commando baby!

Going Commando

I seem to have accidentally deleted the original unpixelated version of this.

my crotch has been pixelated.

In the distance you can see a flower bouquet.

[Future edit: Going commando felt nice, but it didn’t help with the rash. The only thing that helped was when I finally got some baby powder.]

Posts from June 12th

rashes suck.
rashes between your ass cheeks suck more.
babies with diaper rash deserve more empathy
still peeing on myself. Still getting gradually better but it’s a slow improvement now. Spraying myself down with a peri-bottle afterwards & the resulting moisture is probably half of the problem with the rash.

Posts from June 14th

having trouble focusing
baby powder seems to be helping rash but it’s slow going
got exhausted after taking shower and doing minor tasks afterwards that mostly involved standing up
sat vertically while getting into a recliner and it didn’t feel terrible.
tired of not participating in life.

Posts from June 15th

I woke up feeling like I’d crossed another healing threshold. Things just feel more “normal” today. The rash is finally uner control, and my vulva looks so good.

I think the swelling is completely gone in my labia minora, and mostly gone in the labia majora. I finally have a good sense of what his work will look like in the end. I asked for pretty, visible labia, and he’s done a spectacular job.

I’m still healing where I ripped stitches, but it looks healthy, and now that the rash is under control I’m willing to take a chance and start applying honey again even though that means wearing underwear and pads again.

I want to share pics and be like “OMG Look Look! Isn’t this amazing!” but also, I don’t want to be sharing pussy pics on social media. Doubly so when there is still unpleasant looking section where the stitches have ripped.

Week 5

Things are technically healing, but in some ways it also looks worse. I recommend not clicking.

Week 5 Status Photo

Swelling has gone down, but that’s revealed the stitch at the top left of the V and the black spot at the bottom of the V has revealed more of the actual stitch. I’m happy with the progress, but it doesn’t look good.

Posts from Day June 16th

I’m so weak. I think i’ve lost muscle mass everywhere it’s possible to loose muscle mass.

I hate exercise, but I think that once I can, I’m going to have to start actually committing time to it. Otherwise I’ll continue to have the stamina of a… thing with very little stamina.

blerg. I was told that even at the 2 month mark I still shouldn’t use even the elyptical, and that’s about as low impact as you can get and still involve the legs.

😮‍💨

Posts from June 17th:

rash is under control. Hard to tell if completely gone because skin color between butt cheeks has always been darker than surrounding skin. Continuing to be vigilant with drying and use baby powder.
really REALLY sick of process of keeping everything dry after using the bathroom
healing around un-ripped stitches looks amazing. ripped area still making slow progress.
no-one tells you that keeping a pad against your vulva 24hrs a day will make it all gross and sweaty. 😝

In other news, I think I finally caught sight of my urethra. 🎉 Except, it seems to be pointed forwards, not out. If I’m right… well I’m pretty much guaranteed to always have messy bathroom visits which… I’m just going to hope I’m wrong on that. My surgeon IS a urologist, so 🤞 he didn’t eff that up.

I’ll revisit this issue after the stiches are all gone. Right now i’m being extra cautious about not spreading things wide and accidentally ripping stitches, so the view is a bit compromised.

[Future edit: I wasn’t right. It’s pointed the way it should be.]

Week 6

Finally not disturbing to look at, although there is still a little healing to be done at the bottom of the V.

Week 6 Status Photo

The labia minora look pretty normal at this point except for the odd stitching weirdness on one of the. When I took this I thought the swelling was mostly gone. I was wrong. There’s still a fair amount of swelling that will go down.

Posts from June 23rd

waking up horny stopped after roughly 3.5 weeks. Libido has returned to normal (hardly any).
have been dealing with a weird discomfort for about a week but it hasn’t shown up today, so 🤞
there are lots of stiff suture ends poking out inside of me. occasionally uncomfortable. incredibly off-putting when I feel like exploring. ~1wk left until they’re all disolved.
sitting is getting gradually less uncomfortable.

I wouldn’t say this is giving me “trans joy” per-se. More trans relief, trans contentment, trans finally-ness.

Deep sigh of relief.

Posts from June 26th

One of the most surprising things about my surgery is how “normal” everything feels. Sure, there are details that are different and things I’m still learning, but you’d thinking that suddenly not dangly bits would take some getting used to. But, I’ve never felt like “wow it’s weird not having that there anymore”. It’s just weirdly… normal feeling. That idea seems so implausible to me, and yet…

body has closed up / sealed off all the ripped stitches except for a bit the width of my index finger at the bottom of the V
still disturbing to slide a finger in and feel all the sutures that are tied off in there. Stiff little fibers poking out. Sometimes I’ll shift and they’ll poke me from in there.
sitting up’s still uncomfortable without donut, or very squishy chair.
keep feeling like i’ve recently slammed a hard bicycle seat into my perineum

Posts from June 27th

The problem with taking a picture of your vulva every day is that you go to open the photos app on your phone later that day and get a jump-scare like “HOSHIT VULVA!!” because I don’t reallly expect to see amateur porn looking images in my photos album.

Then I have to remind myself to “Hide” the image.

side note: why Apple? Why can’t I have private albums? PLURAL Without some weird gyrations to get things in there?

Posts from June 28th

I think maybe, maaaaybe I’ll be able to stop applying honey in a couple days. Everything’s so close to being healed across the top. 🤞

Still feeling discomfort when I walk / do too much. Stairs seem to be especially prone to making things uncomfortable. Every now and then I’ll take a Tylenol to address that, but it’s not really bad. it’s more, why be in discomfort if you don’t need to be, and NOT being in discomfort will help healing.

Week 7

Week 7 Status Photo

The white you see at the bottom of the V here is almost entirely reflected light. In fact there’s very little white there.

June 30th (Dr’s Checkup)

A friend took the day off of work to drive me the ~4hrs into Manhattan, and ~4hrs back. We haven’t spent a lot of time together since Covid so it was nice to catch up.

Riding in the car was fine as long as I stayed extremely reclined.

Met with the Physicians Assitant

She seemed quite pleased with the healing. Despite how good the labia minora look there’s still a fair amount of expected swelling going on behind the scenes.

My urethra’s pointed the right way, & peeing will continue to get less messy as swelling goes down.

Things are going well enough that there’s no need to make the trip to NYC again in 2-3 months

There are still a LOT of stiches poking out inside, but she didn’t hesitate to reach in spread things wide when investigating. So, I don’t need to be as delicate with everything as I have been.

Posts from July 1st

Very TMI neovagina surprises

Happy Surprises

My pussy smells like pussy.
Stick a finger inside, and it feels all slick and moist like a normal pussy.
When aroused, the output of the cowpers gland (makes ‘pre-cum’) is plenty sufficent to play with yourself.
How ridiculously “normal” the new configuration of bits feels.
How effing good it looks even just 6 weeks out.

Posts from July 4th

I’ve found blow-drying my crotch and butt-crack after a shower to be very effective in the fight against rash from sweaty bits squished against me pre-surgery, and extra-cautious maintenance post-surgery.

After six weeks, I find my 🧠 is still throwing out confused ⚠️warnings because my subsconscious can’t understand why it’s not feeling anything on the dangly bits as the warm air blows over me.

🤦‍♀️

Week 8

Finally everything’s healed over!

Week 8 Status Photo

Labia minora doing funky curvy things.

Posts from July 8th

Mildly Disturbing Mental imagery re stitches

Stitches are supposed to take ~6 weeks to dissolve. Sometimes less, sometimes more. It’s been 7.

Problem is that sticking my finger inside myself becomes more disturbing every time I wash. So many stitches tied off in there - especially in the “dimple” - that it feels like pressing my finger into a slippery coarse-hair brush that muscles are pressing into my finger. I have to psyche myself up to wash in there, and it feels wildly Wrong™

I know this will pass. I know they will dissolve, but in the meantime I’ve been developing serious mental hurdles about interacting with anything below the surface. Fortunately the hurdles are tied to the sensation of the “bristles” but I have no doubt there’ll be some spillover that lingers after they’re gone.

Even writing this makes me want to shudder.

Things will get better. This will pass… eventually. I just have to persevere.

Posts from July 9th

Today was… difficult. Things hurt, and I was exhausted, but as i awkwardly struggled to get out of my chair right now, and accidentally pointed my bare ass at the window I thought “but I’ve got a great vagina”

So. Yeah.

Worth it.

Posts from July 12th

My groin has been sore for days. I don’t really understand why. I’ve been taking extra care to not push things since it started but… 🤷‍♀️

New phase of healing i guess. I remember the dr. saying something about swelling interfering with the ability to feel certain discomforts. I wonder if this is more of the same. Like the swelling has reduced enough on some internal stuff that I can now feel things I couldn’t before.

Week 9

More gradual healing.

Week 9 Status Photo

The scar looks shiny because I’d just applied scar gel.

Posts from July 17th

Two (+ a bit) month update:

My default state seems to be “somewhat sore” lately.
orgasm is achievable but really difficult because of the soreness, and the fact that reaching inside is a major turn-off with all those stitches still undissolved.
found a site that claims some of the more robust stitches can take up to 6 months to dissolve. I’m not expecting that since my doc’s assistant predicted more like 6 weeks, but we’re closing in on 9 weeks now…

Theoretically folks can go back to their desk jobs around the 2 month mark, so I’ve been putting that to the test in the mornings by going downstairs to my office. It’s been great to finally get back there, but I haven’t lasted beyond lunch.

I can’t sit in a normal chair without a donut and sitting straight is doable but time limited. So, I’m leaning back, but that doesn’t work great with a donut.

I feel bad for anyone who has to go back after 2 months. It’s doable, but not comfortable.

Today I pushed how far I can walk when someone came to talk about helping clean up our flower beds. I didn’t even go far, but I bailed early and let Wifey finish off the conversation without me.

Now I’m back upstairs after lunch feeling regret.

Posts from July 20th

Body: Hey. How about a sharp stabby pain to the cooch? Me: Um. No thank you. Body: tough shit. 🔪🔪🔪

Apparently I have attempted to do too much yesterday & today. I have retired upstairs, to lay on my back, and taken a Tylenol.

Week 10

Week 10 Status Plus Inside Look

Things are healing nicely. If you look closely at the top of the labia minora you can see a tiny white stitch getting ready to come loose.

I don’t really know what to call this bit of flesh behind the clitoral hood. If it’s my clit it’s a very long clit. If not, then I don’t know what it is. Unfortunately even two weeks after this I can’t really tell because of the stitches and swelling in there.

[Future edit: Not my clit. Just swollen labia minora.]

It was somewhere during week 10 that the sensation when I pee no longer felt notable. It’s just become “normal”.

Posts from July 21st

9 week update:

inside still filled with stitches 😢
felt like yesterday was first real setback after pushing self too hard day before
Managed a whole day in office chair without it feeling notable
still can’t sit in chair comfortable without donut
still sleeping in different bed because sleep schedule still completely effed
daily soreness decreasing overall

Posts from July 23rd

We were just having one of our morning, breakfast discussions and came to the realization that despite being over 50 years old, I am only today learning that I don’t actually I have an understanding of the concept of pain that matches up with anyone else else’s.

While, I think I was in essentially no pain after surgery I may have actually been at a three or four? For like a month?

Why did no-one ever give me a pain scale with descriptive words?

Apparently most everything i call “discomfort” other people consider mild(ish) forms of “pain”

I still don’t understand, and I don’t actually know what to do about it, but apparently that’s a thing.

In related news: Yesterday evening I was laying on the couch, experiencing a pretty decent amount of “discomfort” in my ingual canals, and unconsciously attempted to adjust my (tucked) testicles… that don’t exist. 🤦‍♀️

All this came about because wifey said “People who haven’t had major surgery don’t generally have a concept of real pain”‡ And I responded that I had had major surgery, but hadn’t actually experienced any notable pain so I guess I still didn’t.

There’s so much shit that everyone assumes “everybody knows” but never actually gets discussed.

– ‡ paraphrased, & chronic pain had already been discussed

Posts from July 24th

I wanted to be helpful, so I tried to make waffles today. I gathered all the ingredients, then made sure to sit down while mixing everything I could.

By the time I was done melting butter and warming milk my groin was very unhappy.

It’s so frustrating. I feel mostly fine when I’m just siting around and it’s driving me buggy not helping.

Then, both batches of waffles came out all dark and terrible smelling. We haven’t figured out why.

Week 11

Week 11 Status Photo

Posts from July 28th

Week 10 update: Week 9… was not good. Doing too much walking and stairs 2 Saturdays ago set me back, and I keep thinking I’m ok again, but i’m not, and i try to do things and the end result is that after feeding dogs, and cleaning catbox, I couldn’t sit in my office chair for 2hrs today.

Gave up. went upstairs to take drugs, and flop on my back

Posts from August 7th

In 4 days it will have been 3 months since the surgery. That’s when you’re theoretically ready to start doing regular activities again. I’m not there, but it’s frustrating because I generally feel fine. I want to help run around doing things, but I can’t.

I made waffles this weekend and all the little back and forth this weekend made me ache & by the end I had no fucks left to give.

I circumnavigated the house yesterday & went to the end of the driveway & back. I felt the results for a while afterwards.

But, I can sit at my desk all day now as long as I have my donut. Normal walking around the house in short bursts doesn’t really bother me unless I’ve pushed myself too far doing something specific. So that’s good.

Stairs still have way more of an effect afterwards than I expect. I don’t notice anything when using them.

More Stitches TMI and negative mental health stuff

The region is very sensitive once you gain access, but as soon as I do I’m touching the Upper Bristle Forest (UBF) which is situated directly against incredibly sensitive flesh.

Stitches do seem to finally be starting to dissolve in there, but the UBF is like a patch of really stiff 2 day beard stubble, except it’s pressed against the most sensitive part of your anatomy.

Sticking a finger in there is the most disturbing un-erotic thing I’ve ever felt.

Between it and the Lower Bristle Forest (LBF) in the front of my dimple (dorsal side of anterior wall) I don’t really know what I feel like inside.

Again, stitches were supposed to be dissolved in 6 weeks. At the current rate I expect at least 1mo more before they’re gone. Prolly 2.

Cleaning is an unpleasant “get in. get out” operation.

TMI Masturbation

Orgasm is achievable but physically hampered because I can’t touch anything inside without rubbing bristles. So, I just have to rub my vulva which means wiggling the nearby scar tissue back and forth which, makes me feel sore, which isn’t really a turn-on.

The clitoral tissue is definitely doing its job, but if I don’t reach inside it’s separated by nearly 1cm of tissue that gets compressed when rubbing so it’s anything but “direct” stimulation.

Week 12 Three Months

All the week 12 photos were shown in the summary at the top, but here’s the status photo since you’re so far away from the top of the page now.

Week 12 status photo

What’s notable here is how the labia minora are no longer doing the curvy thing so much as a mirrored V shape. It seems to vary from day to day what they’ll be doing when I take a picture.

And here’s a somewhat silly picture showing how I do maintenance with a mirror held between my feet.

How I do maintenance

So, how are things going after three months of healing?

Pretty well. Most days I wake up feeling fine, or feeling mildly sore. Walking fast causes soreness, walking too much causes soreness, sitting on any firm seat or surface without a donut is uncomfortable. Lots of walking in a short amount of time causes soreness, as does too many stairs.

I can ride in the car without a donut but I still have to be pretty reclined if I do. I can drive with a donut, but not for very long. I suspect my max is somewhere around thirty or forty minutes right now.

I’m able to help out around the house a little. I can chop veggies at the kitchen island without worry. I can take the dogs around the house once without soreness. I’ll see if I can do twice tomorrow.

Peeing isn’t nearly as messy as it was. ⅔ of the time it just runs out the bottom of my slit. ⅓ of the time it runs in a stream down one butt cheek. I’m informed that this isn’t abnormal for cis girls, although I haven’t surveyed many.

Masturbation still isn’t worth the effort most of the time. Things are too sore. The clitoral region is still hypersensitive, and reaching inside is still disturbing to be because of all the stitches.

My “dimple” (a.k.a. vaginal canal) is only about 1cm deep, and this makes me sad. While I have no desire to use dildos or have sex with guys I did want to be able to feel what it was like to have something “inside” me.

I still think it was the right choice to go with minimal depth, but if I could go back in time and talk to old me, I’d tell her to masturbate regularly so that I wouldn’t loose any “material”.

When Dr. Purohit measured me five weeks before surgery he measured approximately 9cm (3.5 inches). I assume that was from base to the corona (bottom of the head). Before restarting HRT 2 years ago I was probably about 15cm (5.9 inches) over the same section.

The more I didn’t masturbate the more uncomfortable erections became, and the less I masturbated. The surgeons would have had a lot more to work with if I’d kept things up regularly.

When I first got aroused after surgery the erectile tissue hurt just like it had before. Now, I’m happy to report that things just feel good when I’m aroused, and there’s plenty of natural lube to have fun. It wouldn’t be enough to lube up a full vagina, but for what I’m working with it works just fine. And yes, my panties get wet just like any cis girl’s.

Unfortunately the stitches put a damper on reaching in and having any direct fun. It’s such a disturbing sensation to feel those stitches.

Speaking of, I don’t really know what things feel like down in my “dimple”. I’m pretty sure there’s nothing particularly arousing down there, but holy shit are there a lot of stitches hiding just out of sight. I’ll revisit when they finally dissolve but I don’t have high hopes at the moment. I think it’ll just be an interesting area to play with that will feel good, but nothing that’d make me come.

I don’t regret getting the surgery for a moment. I don’t regret not getting full depth.

My advice to ladies getting bottom surgery is to go easy on yourself, both in terms of how you push yourself, and in terms of how much time you give yourself to heal when things are sore. You’re going to spend a frustrating amount of time on your back, but it’ll be worth it.

Disturbing description of Masturbation and Orgasm after 3 months

Masturbation gets better by Week 22…

Week 22 ~Five Months

Things are looking, and feeling better. The exposed portion of the stitches around my clit and my vaginal canal - a.k.a. my “dimple” - finally dissolved a little way into month four, which I’m incredibly thankful for. I think they’re still there under the surface, but I can’t detect them anymore so I’m thrilled.

Week 22 status photo

Soreness & Limitations

Up until roughly four months after surgery I was always sore. Now, I only notice the soreness when I press against my vulva (wiping, and masturbation).

When I do something that taxes my groin too much - like carrying a 50lb (~22.5kg) bag - it does make me want to lay down for a while and not move, but the discomfort doesn’t linger into the next day. At three months something like that could make me useless for a week.

Sitting is improved, but I still use my donut when in my office chair or if I’m in the car for more than an hour. Squishy seats like the couch are fine, but harder surfaces are a problem. When I sit on something hard and flat it feels as if my vulva is a sphere that’s being pressed against. It’s as if he made the whole area bulge out farther. He didn’t, but it feels like that. I can only assume this is the result of internal swelling that hasn’t gone down.

Masturbation & Orgasm

Masturbation becomes more enjoyable as the soreness decreases. Earlier on, reaching orgasm involved pushing through the soreness. Now, I still feel the soreness while masturbating but it’s not enough to really hamper the experience. Also, my bulbourethral glands continue to produce enough “lube” that - unless I’m using a toy - I don’t need to add any.

Orgasms are fucking amazing. Here’s how I described it to my wife:

First, I want you to imagine a fluid with the viscosity of lube. Suspended in that fluid are glittery sparkles, each one of those sparkles represents a tingly sensation.

Orgasms are a warm pressure that builds, until you can’t hold it any more and that warm glittery fluid spreads out through your body bringing warmth and pleasant tingles.

I had hints of that sensation before surgery, but now it’s so much more, and so much better.

That being said, orgasms take a lot more work to achieve, and really require you to be in the right headspace. I haven’t been able to orgasm with a toy either, but maybe I just need to buy a “Magic Wand”.

The soreness isn’t really a problem during masturbation, but after the last one I was sore in a way that I imagine a straight girl might be after being railed by a linebacker for two hours.

On a related note, I discovered that slapping the labia over and around your clit isn’t just a weird thing porn stars do to turn on straight guys. It actually feels good. Who knew. I didn’t.

Internal Structures

While the outside looks great, things look non-standard inside. Mostly with regards to the clitoris. First off, there’s no “bean”. There’s a bit that’s extra sensitive, and is where you’d expect to find said “bean” but there’s nothing external there. Meanwhile the “bulbs” of the clitoris seem extra… bulbous. They look like an inflatable horseshoe going around a non-existent bean.

I really have to reach in and spread to see these. Like, not in the way you’d see in straight porn, where the woman puts a finger on each side of the labia and pulls. Doing that looks relatively normal.

To see the things I’m talking about requires going caving with a headlamp and safety gear, so maybe it’s normal looking and I’m just ignorant.

Regardless of what things look like inside. Everything feels good. The “bulbs” feel good. The non-bean feels good although it’s wicked sensitive and touching it directly is too much.

Depth

I spoke earlier about depth. Before the surgery Dr. Purohit suggested that I’d probably end up with enough depth to get my middle finger in roughly to the middle knuckle, or about 2.5" (~6cm).

As you can see, I ended up with essentially no depth. Pressure in my “dimple” doesn’t feel good.

Demonstration of depth of my dimple

This photo shows my finger fully inserted. I couldn’t press it in any farther if I wanted to.

In theory I could do the same kind of dilation therapy an intersex person with a shallow vagina might, but I don’t really feel like pressing a hard rod into myself for twenty minutes a day, every day for however long it takes in order to have a cavity with no particular sensitivity.

Nerve Damage

No change from before, but it is more detectable because the rest of me isn’t constantly sore. There’s a roughly circular area about 6" (~15cm) in diameter to the right of my vulva where I can’t feel anything at all. At this point I think it’s going to be permanent.

The End?

I’ll probably update this in a few months, but for now, this is the end.

If anyone on Dr. Purohit’s team is reading this, THANK YOU. You were wonderful.

And, if you made it this far 🙇‍♀️ Thank you for your time. If you’re on Mastodon / The Fediverse, please drop me a line at @masukomi@connectified.com and let me know what you thought.

The Interesting Problems With Hall Passes

Mon, 07 Jul 2025 00:00:00 -0400

Table of Contents

Overview

A “Hall Pass” - for those not familiar with the term - is an agreement between partners in a monogamous relationship that a given partner would be allowed to have sex with one or more specific celebrities if the opportunity arose.

I was pondering this concept in the shower, and the more I considered it, the more interestingly problematic it became.

The Interesting Problems With Hall Passes

A Hall Pass is an acknowledgement that

you or your partner find someone outside of your relationship sexually attractive.
you or your partner would like to have sex with someone outside of your relationship.
one partner craves something sexually that the other can’t provide.
one partner is - theoretically - ok with the other partner having sex with someone outside their relationship.

Additionally Hall Passes are frequently discussed, and compared, publicly.

But, here’s where it gets interesting. Hall Passes are an exclusively monogamous concept¹. Monogamy is an agreement between two people to not have sex or romantic relationships with other people.

It’s a cultural expectation that a monagamous person would get jealous if their partner made romantic or sexual advances towards another person.
Sleeping with someone outside the relationship is not only a very common reason to dissolve the relationship, but if the couple is married it’s commonly a reason for a judge to defer to the person “cheated on” in matters of children and finances.
Even if someone executed their Hall Pass with full consent, I suspect it would cause significant emotional problems within the relationship afterwards.

If you have granted your partner a Hall Pass, you are explicitly stating that you are a practitioner of Ethical Non-Monogamy. That means you are explicitly not monogamous. Furthermore, it means that your relationship with your partner is also explicitly non-monogamous.

Consequences

The consequences are socially interesting.

Anyone who professes to be monogamous but has also granted a Hall Pass is either lying about being monogamous OR lying about granting their partner that freedom. I’d encourage anyone who has granted their partner a Hall Pass to spend some time introspecting, and trying to honestly answer which case is true.

If you’re lying about the Hall Pass to your partner: Does your partner know you didn’t really mean it? Why did you think that was an acceptable thing to lie to them about knowing that it would seriously harm your relationship if they believed you and/or acted on it.

If you’re lying about being monogamous it opens up lot more questions.

Have you publicly stated that (ethical) non-monogamy is bad / evil despite the fact that you’re non-monogamous?
Why are you preventing yourself from receiving additional comfort, or love, or sexual enjoyment?
Does your partner know? If not, will you tell them?
Do you, or will you, publicly speak out in support of Ethical Non-monogamy so that other people like you can live their lives openly and proudly?

Anyone who has talked about their or their partner’s Hall Pass is publicly acknowledging their support of Ethical Non-monogamy. The concept of a “Hall Pass” is very popular in western culture, but western culture is also dominated by Christianity, which - despite the bible condoning it² - is very against non-monogamous relationships. So, if you’re a Christian who has received or granted a Hall Pass, what does that mean regarding your relationship to your church and/or religion?

Technically “closed” polyamorous relationships exist, where the multiple partners agree there won’t be any romantic and/or sexual additions to the group. A Hall Pass could theoretically exist in this form of ethical non-monogamy, but closed poly relationships seem to be pretty atypical. ↩︎
There are over 40 instances of non-monogamous relationships which the bible not only condones but lays out rules for. Admittedly, those were polygamous and the women didn’t generally have a choice, but the point here is that the Bible is very supportive of non-monogamous relationships. ↩︎

2025 Reading List

Sun, 22 Jun 2025 00:00:00 -0400

Table of Contents

Overview

The following is a list of books I’ve read in 2025 along with some quick thoughts. It’s almost entirely comprised of sapphic romance. Book"s tagged with 🌟 are ones I think you should definitely consider reading.

Most of the links are Amazon affiliate links, just because they’re shorter and easier to deal with. Amazon refuses to give me any money anyway so I don’t really care if you use them. 😉

The books

Jan-June

🌟[poly][sapphic] The Homecoming (Constellation Book 4) by Sabrina Blaum Loved it. Read it again months later and loved it just as much. Told through a series of flashbacks this is the story of a mixed race, age-gap, throuple and what happens when one of them gets in a terrible car accident that leaves her in a medically induced coma. Through the flashbacks we learn how they came together. The present-day story-line is about the complexities of them all dealing with families who don’t know, and or don’t accept what they are to each other, or that they’re even gay. I love absolutely everything about this book.
[sapphic] The Deal (Constellation Book 2) Good. Don’t remember much of it.
[non-binary] Graceless (Grace Notes Book 2) by Ruby Landers While the author is great, and this series is great, I disliked this book because one of the characters in the relationship (Lane) is a non-binary person who’s written male as fuck. Straight girls, and bi girls may enjoy this, but their male behavior / personality was a total turn-off for me. That being said, I’d still recommend reading it if you plan on reading Book 3. Because Cassidy’s character development is huge in this and it makes Book 3 all the better.
[sapphic] Saving Graces (Grace Notes Book 3) Good, follows the story of the female protagonist in Graceless. Unfortunately you’ll get a lot more out of it if you read book 2 first.
🌟[sapphic] Wolf Shirt & High Heels (Kissing At Work Book 1) by Evie Marque Loved it. Way better than the blurb suggests. I loved the depth of characters, and complexity of the relationships between the protagonist and her love interest as well as her ex and her friends.
🌟[poly][sapphic] Rhymes with Couple: A Carlsbad Village Lesbian Romance by Sabrina Kane Loved it. There are a lot of books where “polyamory” is just a “permission to have sex with other people”. This book doesn’t. Despite feeling like it’s 90% steamy sex scenes (🥵), it is undeniably built on a foundation of love and respect between all three characters.
🌟[poly][sapphic] Nanny in the Middle: a sapphic why choose romance (Love in Massachusetts) by Adrian J. Smith Three women with kids roughly the same age love each other dearly, but aren’t romantically involved. One of them has a toxic ex who keeps causing nannys to leave. New nanny comes in, stands up to the ex, and brings everyone together. It’s complicated and a little messy in all the best ways.
[sapphic] Not in the Plan: A totally addictive and consuming lesbian romance by Dana Hawkins Had to abandon this. Great writing. Great characters who I really wanted to watch the relationship about. However, there comes a point where Mack - a writer - believes its wrong to continue using inspiration from Charlie’s stories in her book, but continues doing so, and continues not admitting it. Mack has a good reason, but I just can’t handle spending so much time in the head of someone who feels they’re doing something hurtful and continues doing it and hiding it. I’m sure it all works out but…
[sapphic] The Princess Match by Clare Lydon Really liked it. Good believable characters. Will probably read again someday. It’s the story of an in-the-closet British princess who falls for the captain of a popular women’s football (soccer) team.
[sapphic] The Librarian’s Gargoyle: A Cozy Sapphic Monster Romantasy by Evelyn Shine Really enjoyed this. Can’t wait for the next book in the series. The protagonist just wants to be left alone to work in the local library and tutor kids while searching for magic she knows exists. Her parents mostly ignore her until marrying her off would make for a lucrative trade alliance. She grows up spending countless hours in the arms of a stone gargoyle she doesn’t know is alive. The plot unfolds as her parents get her fired and announce she is to be wed, while shades start attacking her for reasons unknown.

Set in 1912 Paris, this does not feel like a period piece. The time period feels more like a tool to enable the protagonist to plausibly be married off and have no real choice in the matter. Definitely deals with the idea of women being only valued for the offspring they can produce, and alliances they can buy.

There’s a tiny bit too much action for me to call it “cozy”, but it’s almost cozy.
[poly][sapphic][manga][yuri] There’s Weird Voices Coming From The Room Next Door! A erotic lesbian polyamorous story about falling in love with your neighbors. Fun, not too serious. My full review on Bookwyrm
[sapphic] Conflict of Interest (Portland Police Bureau Series Book 1) by Jae I actually re-read this this year but I haven’t written about it before, so here you go.

A psychologist is raped, and slowly learns to trust and love the female detective investigating her case. The detective’s a child of rape, and afraid of relationships as a result of childhood trauma.

It’s a very enjoyable slow burn, with no sex until the very end. The story is all about learning to trust, support, and accept, and it’s wonderfully done.
[sapphic] Next of Kin: A Romantic Suspense Novel (Portland Police Bureau Series Book 2) Kade’s focused on her career as an Assistant District Attorney who’s tired of dating men who don’t respect her career and see her as a beautiful trophy to win, and a way to access her family’s wealth. Lieutenant Del Vasquez is an older, down-to-earth butch Lesbian, who lets Kade know she’d love to date her, despite Kade’s claims of being straight.

Meanwhile, Aiden - one of the main characters from Conflict of Interest - discovers she has a rebellious half-sister named Evan from the same rapist father, and her partner is the sister’s psychologist (until they find out). The sister coincidentally begins a relationship with Kade’s niece, and complications ensure when the neice’s homophobic parents catch them in the bedroom.

The main story of Kade & Del is driven by an unknown stalker obsessed with Kade, who becomes increasingly upset with Del’s presence. The sub-plot is driven by the complicated fallout of Evan being caught, and Aiden learning to be a supportive big sister to a troubled girl.

I love that this isn’t an “oh I was a lesbian all along” story for Kade. Once she admits to herself that she has feelings for Del she identifies herself as bisexual. Better, it’s not because of an unwillingness or fear of admitting she’s a lesbian. She’s actually, confidently bi.

There’s lots to love about this book.
[sapphic] Change of Pace (Portland Police Bureau Series Book 3) A ~50 page novella exploring the question of what happens when Kade’s stuck-up rich mother visits unexpectedly and has to spend a day with Kade and Del help their very normal - although mostly lesbian - friends as they help Aiden and Dawn (from Conflict of Interest and Next of Kin) move to a new place.

Don’t bother reading this if you haven’t read the first two books in the series. If you’ve read them you’ll enjoy this.
An Election - John Scalzi I don’t remember much of this novella beyond it being comedic and entertaining.
[sapphic] The Song in My Heart by Tracey Richardson I don’t remember any of this, but I gave it 4 stars.
[hetero] How I Proposed to my Wife: An Alien Sex Story ebook by John Scalzi Normally I’m a fan of Scalzi, but I didn’t really like this at all.
[sapphic] Wrong Number, Right Woman (Unexpected Love Book 3) Shy butch lacking self-confidence is accidentally texted by an outgoing straight girl looking for her friends opinion on an outfit for a date. They end up chatting, and straight girl discovers she’s not so straight after all.

This book is so sweet, and you’re absolutely rooting for both of the characters the whole way.

Bonus points for trans representation in the form of a well written best friend who just happens to be trans.
[sapphic] Lucky Yellow Shoes (Unexpected Love Book 4) by Jae A ~30 page novella follow-up to Wrong Number, Right Woman.
[sapphic] Chemistry Lessons (Unexpected Love Book 5) by Jae Two best friends go on a date to prove to their friend group that they’re not a good match romantically. Surprise, they are.

I enjoyed this, like I enjoy everything Jae writes. Good. Not extraordinary.
[sapphic] The Principal’s Office (Unexpected Love Book 6) by Jae A ~20 page novella follow-up to Chemistry Lessons
[sapphic] Bachelorette Number Twelve (Heart-to-Heart Medical Romance Series Book 1) An enjoyable, and believable enemies-to-lovers story between an ice queen doctor and one of the nurses in the same ER.

I don’t remember a ton from this book.
[sapphic] Impulse Buy (Heart-to-Heart Medical Romance Series Book 2) by Jae A ~40 page novella followup to Bachelorette Number Twelve that I don’t remember anything about.
[sapphic][asexual] Perfect Rhythm (Fair Oaks Book 1) by Jae I really liked this. Famous pop star (Leo) is tired of people wanting her for her fame, and re-unites with childhood friend (Holly) when she returns to her hometown after her father has a stroke. Things are complicated by the fact that Holly’s ace, and has a hard time believing Leo could ever be happy in a relationship with someone who couldn’t fulfill her sexual needs.
[sapphic] Not the Marrying Kind (Fair Oaks Book 2) by Jae A complicated relationship between a butch baker and a neighborhood florist who is terrified to come out of the closet and disappoint her family.

Doesn’t need to be read after Perfect Rhythm, but is better if you do.
[sapphic] Dreamer by Kris Byrant I abandoned this half way through. The characters are interesting, and the plot twist (happens early on) is fine but I don’t like the way the resulting complications are handled. The more elements from before the twist overlap with post-twist things the less believable I found the character responses to them.
[gay][aliens] Earth Fathers Are Weird by Lyn Gala I loved this, and I generally can’t relate to male-male romance stories at all. Human Air-Force pilot gets saved by alien “cops” during an accidental invasion. He gets a job as a “nanny” to pay for a trip back, and starts caring for his tentacled employer, and eventually the kids they raise.

The universal translators are crap when it comes to translating to and from English. This is a key plot point, and the resulting conversations where both sides are dealing with a limited and problematic vocabulary to communicate are very well handled.

It’s sweet, and warm, with lots of heart, and love. And yes, there is tentacle sex. Not much, but surprisingly hot. Well, surprising for me because I’m not into tentacle sex or sex with guys.
[sapphic] Release the Stars by Harper Bliss Good, but not particularly memorable for me. Charlie moves to Hollywood to write for a TV show after ex dumps her for a man. She vows to never date someone who isn’t “100% lesbian”, then proceeds to get seduced by a bi actress (Ava) she’s been crushing on for years. A lot of this is about Charlie’s fear of being dumped for a man again, and her hangup about only dating lesbians while being incredibly attracted to Ava who would love to have a real relationship with her.
[sapphic] And Then She Kissed Me by Harper Bliss A sweet friend-to-lovers story with lots of moments of accepting supportive family.
[sapphic] The Duet: A Lesbian Age-Gap Rock Star Romance by Harper Bliss Falling in love while singing a bad-ass duet on stage every night. An enjoyable age-gap romance.
[sapphic] Still The One by Harper Bliss A friends-to-enemies-to-lovers story. I don’t remember much but I’m pretty sure it was relatively enjoyable, and on par with Harper Bliss’s other writing.
[sapphic] Something In The Wine by Jae Annie’s brother Jake is an annoying practical joker. When he sets Annie up on a date with his friend Drew, they’re both pissed at him because Annie’s straight, and Drew’s a butch lesbian. They decide to pretend the date worked out, friendship, and then love ensue.

This book had a lot of heart, and I really enjoyed it.
[sapphic] Departure from the Script (The Hollywood Series Book 2) by Jae Photographer meets aspiring actress. Thank you becomes friendship, becomes love.

A nice story.
[sapphic] Damage Control (The Hollywood Series Book 3) by Jae Famous actress (Grace) hires PR agent (Lauren) for “damage control” when papparazi share pictures of her and another woman.

The basic plot is that Grace’s Mom has been her agent since she was a child actress, but Grace is a closeted lesbian as a result of her Mom being a controlling homophobe who’s instilled Grace with the fear that her career and everything else in her life will fall apart if anyone thought she was gay.

It’s a good story of Grace overcoming that fear, and breaking out of the toxic relationship with her mother.
[sapphic] Just Physical (The Hollywood Series Book 5) by Jae Jill’s an actress with Multiple Sclerosis refuses to let anyone in her heart because she doesn’t want to doom them to a life of supporting her physically if her MS progresses. She meets a stunt woman named Crash who’s willing to love her despite everything, but can Jill accept that it’s ok to let herself be loved despite her MS?

Duh, of course she can. But, it’s a good story.
[sappic][autistic] The Woman Next Door by Harper Bliss Olivia is an autistic book translator happily living in the woods with her cats and routines. Marie’s a surgeon who’s not into relationships, just good sex, but her world falls apart when a patient dies on her table. She goes to her family’s summer home and meets Olivia who has no interest in one-night-stands, or anything that would change her routines. Definitely not moving back to the city with Marie.

Overall I liked this book, but I hated that the author refused to acknowledge, or even hint at the fact that Olivia was autistic. This isn’t a character that “could be read as autistic”. This is a character who can’t be read any other way.
[sapphic] Good Bones (A Renovation Romance Book 2) Abandoned. I couldn’t deal with the older woman’s on-again off-again feelings about dating a younger woman, or anyone. I didn’t find it believable.
[sapphic] Twisted Lives by Ali Spooner Abandoned. The characters were good, but everything happened implausibly fast. Bet runs away from an abusive husband with her kid, and breaks down on the side of the road by Alex’s driveway. Alex finds her stranded, and offers her a place to stay for the night. 24 hours later Bet’s kid has accepted Alex as her new 2nd mom, and Bet is throughly in love with her. The characters are decent, the story is even decent, but the speed at which everything happens is completely unbelievable and made it impossible for me to stay in the story.
[sapphic] Nothing to Loose by Clare Lydon Scarlet’s life finishes falling apart when a flood destroys her home and the mayor (Joy) takes her in. Joy’s optimism meets Scarlet’s spiraling doom, and they find they really enjoy spending time with each other.

I really enjoyed this one.
🌟[sapphic] Broken Beyond Repair: A Sapphic Celebrity Ice Queen Romance (A South Downs Romance Book 1) by Emily Banting

This one won a pile of awards and deserved every one. Beatrice is an actress who has closed off her heart and acted like a bitch to everyone around her. It’s eventually revealed that she’s had good reason, but there’s more going on than she knows.

Sydney is her latest personal assistant, and Beatrice’s polar opposite, but she’s damn good at her job, and eventually cracks Beatrice’s protective shell.

This is probably the best “Ice Queen” story I’ve read so far, because your heart goes out to Beatrice as the story gradually reveals why she acts the way she does.
[sapphic] Teacher’s Pet (A Sweet Lesbian Romance) Katie’s dates keep bailing the moment they find out she has a young kid. Lana is her daughter’s teacher, who helps her out of a jam. It really is a “sweet lesbian romance”. My only complaint was that it was too short.
[sappic][trans] The Hatchling by Vyria Durav You can buy all of Vyria’s stuff directly via itch.io.

A fantasy story of man teased for being effeminate. He’s forced to act as the healer for an obnoxious group of hunters who go after a dragon, despite the fact he thinks dragon’s shouldn’t be hunted. Long story short, he meets the dragon, is taken in and turned into a female dragon, and takes his revenge when they won’t leave them alone.

Like all of Vyria’s stories, my only complaint is that I wish it was twice as long as it is, with more time for everything to build in the reader’s head.
[genderfluid] Only Mostly Dead by Allie Temple Paused reading, but intend to come back. I stopped because there was “we need to save the world” stuff happening than I was in the mood for, but it’s a well written tale of a ghost and a very genderfluid reaper. In this story reapers aren’t from our dimension and can take on any shape they want.

Honestly it was pretty good, just not what I wanted at the moment.
[sapphic] Thankful (A Sweet Thanksgiving Romance) by Edie Bryant Lesbian doesn’t tell straight best friend she’s into her because doesn’t want to ruin friendship. Straight best friend later discovers she’s bi after best friend moves away,but doesn’t tell her.

Events happen, they learn they’re both into each other. And then the story falls apart for me because bi girl is like “OMG Yes my life’s dreams!” and suddenly “OMG we can’t be together because I think mom doesn’t approve of us as a couple.” Which… there was more going on but still it’s SO hot & cold for someone you’ve loved all your life that it’s hard to believe, and made her feel like a cruel jerk.
[sapphic] Fluid Bonding: a sapphic paranormal romance by Sienna Eggler Secret telepath meets secret half-vampire. When their feelings grow they eventually admit what they are. I really enjoyed this.
[sapphic][transgender] Gone Was the Glow: prequel (St. Acton) by Sienna Eggler This was good.

Evangeline (Evan) is witch / half-vampire is mourning the loss of an incredible relationship with a butch werewolf who - after years together - went out one day and never came back. Svenja is the werewolf PI - born not made thank you very much - who Evan hired to figure out what happened.

Years later the half-vampire from fluid bonding helps kick off the story, by tracking down her half-sister (Evan) and kicking off a quest to find and eliminate their evil full-vampire father. Evan calls in Svenja, who moonlights as a monster hunter, while she’s falling in love with a woman who works at Evan’s school.

The only problem I had was with the description of Svenja’s gender. At one point I thought they were female. Then I thought they were a trans man. In the end they’re a trans-masc person who dresses like a butch female? I think? I don’t really care what they are, but the confusion around their gender wasn’t a plot point. It was just confusing writing and I wished it had been better established how I should be thinking about them early on in the story.
[agender][asexual] The Thread That Binds: (The Eternal Library Book 1) by Cedar McCloud Abandoned 40% through. Good characters. Good writing. The problem? One of the main characters is scrying day after day through the history of a book trying to find what happened to it. When ey - the story uses e/ey/eir for most characters - finally do she discovers that it contains some dangerous power that could be terrible in the wrong hands. Instead of going and talking to the people who hid it, or asking any questions at all ey rush to tell their narcisistic boss who the story has established e doesn’t like, and doesn’t fully trust.

The entire remaining story would be based on something that is completely unreasonable for the main character to have done.

My full review here on Bookwyrm also discusses my problems with the author’s handling of the characters in an agender society.
[sapphic] Heart’s Claim: A Sapphic Shifter Romance (Where Our Paths May Cross Book 1) by Issy Waldrom Our dimension collides with one of magic, fae, and dragons. Some people see the overlap, and remember. Some never saw. Our protagonist is protected from an evil character by a dragon, whom she later meets again in our world and rescues in another. Interesting things happen from there.

It’s hard to describe, but it’s good. After reading it I have some problems related to the villain, but nothing that would make me say don’t read it.
[sapphic][transgender] Esper And The Witch by Issy Waldrom. The cover and many of the scenes make you think this is an isekai, but I assure you it isn’t. It just happens that magic users in this world get visual status alerts when they “level” as if they were in a video game, but they’re not.

Alex is slowly turning into a girl and doesn’t know why, but it’s also what he’s always wanted. He doesn’t know that magic exists. His coworker Selena does, and she tries to help support their transition without telling them. This story gradually intersects with the story of a kitsune named Esper who has snuck into the city and keeps waking up in someone’s bed.

I really enjoyed this story. I loved the feel of Alex and Sabrina’s relationship. It’s sweet, and I’ll probably read it again. I’d love to see more stories in this world.

However, at the end of the book we learn about the incident that kicked everything into motion, and it just confused me and left me wondering how Alex ended up at his job, why the kitsune went into the city, and so many more things. Also, the “Mother” of Selena’s magical family feels like an over-the-top Disney villain and I still don’t understand what her motivations are.
[sapphic][bisexual][transgender][poly] What Lies Within by Issy Waldrom I really enjoyed this book, but the books blurb is a problem. It makes you think you’re going to be following the story of some guy who’s really unhappy with his life as a magical guardian. That’s not what the story is about at all.

In the setup we learn that the main character Frasier is in love with his roommate and male best Uriah, who loves him back. Frasier’s teased for being effeminate and was abused by his parents at a young age when they caught him running around in a dress.

Things rapidly escalate after Frasier’s parents try to force him into an arranged marriage with Julia. Julia’s family is in dire straits and needs this arranged marriage. After meeting him, Julia likes Frasier and thinks he and Uriah are a great couple, and hints at the fact that the three of them might all be able to be together. Uria knows Frasier is trans even if Frasier hasn’t admitted it, and is doing their best to support them accepting this.

Magic happens. Frasier’s trans ghost friend Felicia gets bound to him. Frasier starts transforming into a woman and calls herself Callie. They get trapped in a dying world, become a happy polycule, magic things happen. A new character is added to the group. Powers are gained. Secrets are revealed.

I’ll probably reread this one. My only complaint is that characters are way to accepting of things they shouldn’t be. For example (very minor spoiler) after knowing the Julia for like two days, a Vampire (don’t ask) offers to make Julia into a Vampire in order to give her powers (why?) but notes that she’ll only be able to feed off of Callie. Callie has no problem with being tied to someone she barely knows for the rest of her life. Julia doesn’t either once she confirms being out in the daylight isn’t a problem. Uriah doesn’t have an issue with this either. That was the biggest one but there were other “why are you just going ahead with this?” moments that you’ll just have to roll with.

The vaguely annoying part is that all of those moments could have been given more pages between something being presented and acting on it, and it could have been believable.
[sapphic][transgender] Dawn Weaver: A tale of Dragon Riders (Soul Flames Book 1) I abandoned this one 60% of the way through because it was becoming a story of a fantasy party who gradually gain incredible powers in order to save the world against impossible odds and it was just too much for me. I prefer things that aren’t completely over-the-top heroic fiction.

The characters are good. It’s one of the few stories with a magical gender change that doesn’t feel like deus ex machina. If you want a D&D type story about saving the world against an evil villain give this a go. The gender transformation is honestly a minor side issue to the whole story.
🌟[sapphic][transgender][poly] Catnip by Vyria Durav You can buy all of Vyria’s stuff directly via itch.io.

This is a short comfort-read for me, which I reread recently. It’s not very thinky. It’s just cute.

The earth has been decimated by capitalism. The rich evacuate. One rich egotistical character with a cult of personality following sets up a new colony on Venus. You need to just ignore the science and go with this.

Hundreds of years later Sol is the first person sent there in advance of the rest of his polycule to prepare for everyone else’s arrival.

Sol meets an AI named Alexis, falls into a vat of goo, and starts turning into a catgirl. As this proceeds Sol falls in love with the AI, realizes he’s been trans the whole time and just too thick to get any of the hints the folks in his polycule have been giving him. The more Sol changes, the happier he is, until he starts accepting himself as a girl and calling herself Callie.

Meanwhile they’re trying to reclaim Alexis’ missing memories, and unravel the mystery of what happened to the people in the colony.

The relationship between Callie and Alexis is adorable. The story is fun. The rest of the polycule is only tangentially involved in the story via occasional video calls as they travel, and then at the very end.
[sapphic][transgender][poly] The Dragon and Her princess by Vyria Durav You can buy all of Vyria’s stuff directly via itch.io.

Prince Darius is miserable as a prince, and disliked by his father, until he’s kidnapped by a dragon, agrees to marry her for story reasons, and wakes up transformed into a female dragon.

Love and joy are found. Bad men are overthrown. The poly aspect of this is only in the epilogue.

This is a fun, enjoyable read, but like much of Vyria’s stuff it would be much better if it was at least twice as long. Everything just happens too quickly. It’s plausible, but I want more build-up, and time to enjoy.
[sapphic] Taming of a Rebel by Eada Friesian “Ice Queen” Miranda suddenly finds herself taking care of her sister’s kid. Taking care of the kid leads to meeting Tori a mother at the child’s daycare. Tori’s determined to meet her soulmate by the time she’s 30. Miranda’s determined to not accept anyone’s help despite how desperately she needs it.

The relationship is complicated, and nothing goes smoothly, and I love this for that. I love how the two kids get along so well, and how much Tori comes to love Miranda’s niece.

I really recommend this.
[hetero][transgender] Chef’s Choice by T.J. Alexander. Rich trans guy Jean-Pierre needs to have a girlfriend to be good enough to get a bigoted grandfather’s estate. In a desperate “because she was there” moment he ends up hiring Luna (a trans woman) to be his girlfriend for the duration of a phone call. This leads to hiring her to help him in some cooking challenge, which leads to them falling in love.

They’re not at all alike, and a lot of the story’s complications center around the fact that Jean-Pierre has had zero support in his transition and has no community or found family. Luna is out and proud.

Overall good, not great.
[poly][sapphic][agender] Triple Sec by T.J. Alexander Mel’s a jaded butch lesbian bartender. She’s seduced by a hot femme named Bebe, who turns out to have very non-binary / agender spouse named Kade. Mel decides to give Bebe a chance despite her spouse, and their very different worlds.

The relationship between the three of them is complex and real feeling, and I love how Mel comes to respect and stand up for Kade despite how wildly different they are.

It’s not my favorite poly story, but there’s a lot of good things in this book.
[sapphic] Storm In Her Heart by KC Luck Athena finds herself trapped in a winter storm with Kate, an ex-cop turned beer delivery driver who she’s been becoming close friends with. With them are Athena’s niece Lacey and her roommate love interest Max.

The characters feel real, and I loved how different each one felt. The relationships felt nuanced and real, and the love felt earned.
🌟[sapphic] Not for a Moment By: Cheyenne Blue Andi doesn’t want to get involved with a woman with kids. She’s got too much trauma from her own childhood that she doesn’t want to pass on. Sarah’s Mom’s a bitch, and Andi ends up pretending to be her live-in partner to get her off her back one evening when they’re hanging out. Unfortunately she ends up needing to keep the ruse up to prevent Sara’s Mom from taking custody of her daughter Noa.

Messy adult relationships with believable baggage, and Andi trapped in a situation she doesn’t want to be in, but also can’t walk away from because of how cruel it would be to let Noa be taken from Sarah.
When the Moon Hits Your Eye by John Scalzi Explores the question of “What would happen if the moon inexplicably turns to cheese?” Written in a series of little vignettes, this was a fun read.
[sapphic] A Breathless Place by Harper Bliss Izzy Addler lost her voice ten years ago and no longer feels the need the need to keep living. She hasn’t let anyone know her plan. As one of her last acts she allows a writer named Leila come and help her finish her biography.

This is the story of them falling in love, but is that enough when the only thing that ever gave Izzy life is gone?

I’m upset that the fact that Izzy’s suicidal isn’t mentioned. That’s a hell of a trigger warning to skip, and I was not prepared for it when I started reading. That being said, it’s a really well done book that handles the subject with grace. Recommended if you can deal with the subject matter.
[sapphic] A Family Affair by Harper Bliss Kate’s marriage is falling apart. After too many rounds of failed In Vitro Fertilization they’ve given up on their dream of ever having a baby. Kevin throws himself into the remodeling of their house, but can’t bring himself to spend any time with Kate. Kate is left alone in her stepmother’s home, spending time with her sister-in-law Stella.

They bond, and then with the help of too much alcohol cross a line they immediately regret. Stella loves her brother. Kate loves her husband, even if their marriage is functionally dead. Neither of them wants to hurt him or their family, and yet…

This isn’t about the taboo of an affair. This is about finding love when you’re hurting and alone.

I’ve read this twice now and definitely recommend it.
[sapphic] The Love We Make by Harper Bliss An interesting and complicated romance between a very autistic coded actress (Nora Levine), and the new CEO of the production company that makes the TV show she works on (Mimi St James).

Nora is a complicated character with strict routines, hard boundaries, and family trauma. Mimi loves her family more than anything, even though all her kids are grown.

It’s an interesting story that’s refreshingly different. Not for everyone, but I liked it.
[sapphic] I Hope I Don’t Fall In Love With You by Harper Bliss I don’t remember any of this.
[sapphic] Nothing Heals Me Like You Do by Harper Bliss After being kicked out of her home Justine got herself off the streets and started a homeless shelter for queer youth. Now they want to make a movie about her life story, and she’s happy to sell the rights to it if it means more funding for the shelter.

This is an age-gap romance between Justine, and the actress playing the part of her ex at a critical point in her life. Will Justine take a chance on someone so much younger, who grew up with family acceptance, and a privileged life?

I liked this. Complicated emotions and lives make for good stories.
[sapphic] The entire Pink Bean series by Harper Bliss Overall Good, but not great.

The only one I recommend against is Love Without Limits. In prior books Caitlin has been set up as a polyamorous woman who has spent years educating people about ethical non-monogamy. Unfortunately the author seems to believe that polyamory and “lets sleep with other people” are the same thing. There’s no polyamory in this book. It’s just an open relationship. Which is fine, but it feels really out of character for her partner Josephine, especially the opening sex scene, and everything about this book sits wrong with me. It feels disrespectful to poly people, and dismissive of the idea of loving multiple partners.

I believe I also skipped Beneath the Surface because it deals with an alcoholic main character, and how that effects her relationship. Unfortunately this isn’t noted in the blurb.
🌟Sex at Dawn by Christopher Ryan, and Cacilda Jetha A look at the sex and the people and events that have changed our perception of it from pre-history until now.

This is an excellent book, and I think everyone should read it, but every time I try and push a little farther through it I find myself pissed off by yet another moment in history where capitalism, male ego, and / or misogyny has fucked over women and society.
[heterosexual][bisexual][poly] The Harmony of Falling Snow A Polyamorous Romantasy (Songs of Niaretya Book 1) by Andora Brokaw You can get this directly from the author on itch.io.

I didn’t have high expectations of this going in for two reasons: 1. It’s a story about two guys and a girl, and I’m not into guys. 2. Stories like this tend to do a poor job of deploying magic.

I was happily surprised with what I found. Even better, there were over 500 pages of mostly “cozy” entertaining content.

This is the story of Maggie, a woman deported from earth back to a magical world she’s never known. Her only contact is Yuri, an ex who left her and broke her heart, and he happens to help recently deported people settle into their new lives.

In the intervening years Yuri fell in love with Vil, who he asks to host Maggie, but it too chicken-shit to admit that she’s his ex before she’s already there.

Maggie grew up on earth believing that monogamy was the only “right” way. Here in the new world polyamory is the default. Unsurprisingly Maggie develops feelings for both men, and struggles with accepting that maybe it’s ok to love two people at once.

Along the way we find out about Yuri’s mental health issues, the family secret he’s magically prevented from talking about, a group fighting for democracy in their land, and much more.

It’s a really sweet tale, where magic is never used as a crutch. It’s mostly just an element of the world until the climax when their individual powers - especially Maggie’s - become a very big deal.

Loved the characters. Loved the writing. Can’t wait to read whatever the author puts out next.
[sapphic][transgender] Princess Fox and Iron Wolf by Liliana Chaos You can get this directly from the author on itch.io.

A fun tale about someone whose dumb luck finds them stumbling into their transness, accidentally becoming a villian’s minion, and totally crushing on the hot villainess who kidnapped her.

Like many superhero books, things come a little too easily to the protagonist, but that’s kind-of the point of this book. It’s not about dark struggles, or questions of morality. It’s just some fun escapism.
[sapphic][transgender] That Night I Got Dragged Home By A Werewolf by Autumn Wolff You can get this directly from the author on itch.io.

I thought this was going to be a fairly normal transbian romance with a girlfriend that just happens to be a werewolf. That wasn’t even remotely true. This is way more in line with a typical urban fantasy. Magic powers, evil forces trying to kill the lovers, breaking curses, etc. It’s not bad. Some things are accepted and jumped into too quickly without any pause to think, which I wasn’t a huge fan of. Other than that, if you like typical urban fantasy stuff, you’ll like this.

Loved the handling of the main character being a transgender woman with bottom dysphoria who still wants to have sexy-time with her lover.
🌟[sapphic][transgender] The Postman Becomes A Bunny Goddess In Another World by Autumn Wolff

You can get this directly from the author on itch.io.

The coziest of cozy novels. It’s sweet, low stakes, with characters you just want to snuggle up to. Here’s my full review.

July Update

🌟[hetero][furry] My Minotaur Husband by Lyonne Riley

You can get this directly from the author in eBook or signed paperback.

Surprisingly sweet. In this world, Humans are highly desirable, but also almost extinct. A sweet shy minotaur named Theo puts in an application to date Celeste. It’s a short, adorable tale of dating “the shy guy” and finding he’s kind and caring and everything you wanted. It’s also filled with spicy scenes as Celeste and Theo gradually work up to the point where she can be filled with Theo who is, quite literally, hung like a bull.

I’m not generally into “boy kissing” books, but Theo is just such a sweet guy that I didn’t have a problem with it. Also, as one reviewer said “consent is sexy”.

October Update

The Kick-Ass Writer by Chuck Wendig Meh. Didn’t really learn anything. Extremely male-centric viewpoint and filled with abelist language. Also his humor is basically to insert obviously over-the-top remarks in a way that’s funny once or twice but after the 40th time you just want him to shut the fuck up.
[sapphic] Upheaval - As we know it by Rita Potter Pretty good, I liked the characters, but annoyed it was split into two books because absolutely nothing is resolved by the end of the first one. I have the second one but I haven’t read it.

A bunch of lesbians are having a party in an underground bunker when something happens to cause everyone above-ground to die. They emerge, find dead bodies, try to work out what’s happening, and the book ends.
[heterosexual][poly] Seduced by the Werewolves by Lyonne Riley I think I unknowingly stumbled into some omegaverse adjacent stuff. It’s kinda sweet but the sexual relationships are extremely hierarchical.

I don’t remember a lot from this. A woman ends up dating four male werewolves who are already in a relationship, her boss is an ass, lots of sex, knotting. Sweet vibe overall, but hierarchy in the bedroom was a turn off.
[heterosexual] My Ogre Husband by Lyonne Riley Abandoned it 90% through. Just lost interest. Another in her series of series about humans being endangered, and coveted by “monsters”. Egorr is a sweet guy but I was just struggling to care much about this story.
[heterosexual?] Programmed for Love by Lyonne Riley Woman falls in love with Android despite it being taboo. Android falls in love with woman despite thinking he’s not capable of such a thing.

They work on a long haul space-ship, starting, and maintaining a taboo relationship. Meanwhile, someone’s trying to sabotage the ship and kill them all.

Only complaint was that it was too short.
[heterosexual][poly] Hour of the Lion by Cherise Sinclair I have a seriously hard time believing this was written by a woman. The premise was good, but it was so much about what toxic male’s idea of relationships is that I just couldn’t keep reading.
[bisexual][poly] Keeping the Human’s Heart by Lyonne Riley Humans and trolls are at war. A human woman is forced to fight, gets injured, runs far away, and eventually hides in a farm building belonging to a couple of troll guys. One of them sees her as a pet (initially), the other sees her more as a person, they both find their hearts - and bodies - drawn to her. They keep her around even though doing so is a risk. Complications arise.

I liked this one a lot.
[heterosexual] Bred by the Dragon by Lyonne Riley Human woman works at surrogate agency because humans are compatible with all “monsters”. He falls in love with her. They run away together despite it breaking all the rules.

Ok, not great.
[heterosexual] Winning the Orc’s Heart by Lyonne Riley Action, adventure, fantasy, magic, true love. A fun romp. Human woman gets captured and taken prisoner. Orc guy feels drawn to her, and frees her when she’s being given to someone and he can’t stand the idea of what’s going to happen to her.

The book is basically a series of chase sequences while the two characters fall in love despite the fact they “can’t possibly be together”, but it’s well done.
[heterosexual] So I Married an Alien by Lyonne Riley Mail order alien husband. Alien guy applies to program just to get away from his horrible life. Human woman applies because she’s tired of being lonely. They fall in love, complications ensue when she discovers why he left his home and has trouble believing he really cared.

Good, not great.
[heterosexual] Healing the Orc’s Heart by Lyonne Riley

Healing the Orc’s Heart is a super steamy, hurt/comfort monster romance novella that takes place during a war between humans and trollkin, so it contains wartime themes. It features size difference, language barrier, a soft, big-hearted healer FMC, and a grumpy orc MMC.

Pretty good.
[sapphic] Fire and Ice by Jess Mahler

A PI looking for a missing kid in a city of monsters is met with a fae challenge. If she wishes to find the boy, she must endure the touch of fire and ice…

An F/f short story featuring temperature play and a prejudiced woman learning to do better.

It’s well done, and I’d love to see more about the world but it’s basically just setup, one BDSM scene, the end.
A Magical Girl Retires by Park Seolyeon & translated by Anton Hur My first thought was “this sounds like it’s translated”. Then I found out it was translated. The translation feels accurate, but a little… off. Not enough to hurt the reading, but it doesn’t flow as well as the translations of Banana Yoshimoto’s books.

That being said, I don’t understand why this book exists. Girl’s about to commit suicide, is stopped by a Magical Girl, and told she’s a magical girl too. Gets her Magical Girl powers, discovers they’re interesting but come with a huge cost. Almost immediately a villain is introduced, they try and kill all the magical girls, her powers save the day, and because of the presence of many other magical girls the cost is spread. She retires. The end.

It’s like one of those stories a small child tells you that kind-of rambles and you’re not sure what the point is, but fortunately it ends quickly.
[enbian][nonbinary] Emerald Moon: Nonbinary Werewolf Romance by Mel E Lemon

Jo is struggling — struggling to control their wolf, deal with their family, manage their bipolar disorder, and make macarons perfect enough to sell at their pack’s bakery. So when it’s time to go to their sister’s wedding, who better to bring to help them get through it than their new friend Cass that they may have almost kissed? But fake dating isn’t as simple as it is in the stories Jo reads. Will family tensions and confusing feelings about Cass be a recipe for disaster? Or will Jo figure out a recipe for a new romance?

I was looking forward to this, and reread Violet Moon in advance to refresh my memory of Jo and some of the other characters. Jo deals with a lot of self-confidence issues, but I feel that it’s handled realistically and well.
[sapphic?] Off The Beaten Path by Sienna Eggler

Fresh out of college, Meike boarded a train for their new destination: volunteering on a small farm. Aside from dorming, it was the first time they’ve been miles away from home, and were looking forward to expanding their horizons and padding out their resume. Unfortunately for Meike, their train took a drastic detour, leaving them and a fellow passenger stranded in the world of Glasend.

With nowhere to go but forward, Meike is determined to utilize their knowledge of botany, and eke out a living as an herbalist. Along the way, they encounter a colorful cast of characters, study magic, and tame wild beasts and monsters.

Off The Beaten Path is a queer portal fantasy, and part of an ongoing web serial.

It’s well written. The world they end up in is interested, but I lost interest in the story itself after a little while. I’m not sure what form the “queer” part of this takes. There was no romance even hinted at in the parts I got through.

I’m sure this book will work for some people, but not for me.
🌟 [nonbinary][aromantic] Early Adopter by Sienna Eggler

Aided by their cybernetic eyes, private investigator Ryn Casler makes a living busting cheating spouses. While they’ll occasionally dabble in fraud and other typical cases, they don’t deal with the missing.

Until the persistent Shae Winters, a police detective, approaches them about the disappearance of a young Black woman.

Friction flies between detective and PI, as Shae insists on tagging along during the investigation. But as their search deepens and spills into the world of furry body mods, it becomes clear there’s more to this case than meets the eye.

Set in a near future where body-mods are common and black market surgeons can make you into the anthropomorphic animal of your dreams, Ryn is a non-binary, aromantic PI.

Sienna is a master at writing compelling characters who are - I suspect - difficult for most people to relate to. As a person who loves being in love I found it difficult to relate to the fact that Ryn is aromantic. My brain kept expecting it to be revealed that they just have a tough emotional exterior, and that they’d eventually open up to Shae romantically, but no Ryn’s just aromantic.

I don’t think that it’s ever mentioned that Ryn is aromantic, much like we don’t mention that we’re breathing mostly nitrogen. It’s just a thing that’s part of Ryn’s existing. I loved Ryn’s casual acceptance of sex work and sex workers. I loved the way they respects the wishes of the person they’re hired to find, and won’t reveal how to find her unless she says it’s ok.

I love the setting. I love the obvious trans allegory that furry people exist, and are fetishized, but also shunned and not accepted by much of society because of their choice to live as the person they see themselves as. I love that they have to go through black market surgery to have the body they feel is right for them.

I love all the characters, even the gross ones.

I can’t wait to read the sequel.
🌟 [lesbian] Enemies by Nature, Shifting Nature, and Nature of Trust by Jae

Faith is the daughter of the vocal leader of a major anti-shifter hate group. The shifter council proposes a fake relationship between her and a fox shifter named Tala because they have good reason to believe it will help them in the end. Faith’s dad encourages her to go along with it in order to spy on the shifters and reveal their evil plan.

This is a story of overcoming internalized bigotry and learning to see an individual, and a people for who they really are. Faith learns to trust, and love Tala as well as their family, even though some members of that extended family hate Faith - and humans - just as badly as Faith’s father hates shifters.

There are a lot of ways Jae could have fucked this up, but I was really pleased with how well they introduced, and navigated the complications of the world and the character’s relationships.
🌟 [sapphic][transgender] Pack of Her Own by Elena Abbott

Natalie Donovan jumps at a friend’s offer to stay in the family cabin for a month—she desperately needs the chance to get away from, and get over, her messy breakup. She doesn’t count on the owner of the local diner making her heart pound and her body desperate to be touched.

Wren Carne is a lone wolf. As an Alpha shifter, she has no pack and maintains her territory without causing drama, just the way she likes it. When she checks on the girl staying in a local cabin, she’s not expecting her wolf to identify the human as her One True Mate.

As fallout from their pasts encroaches upon the sleepy town of Terabend, Wren must decide if she wants a pack of her own, while Natalie worries that her secret—she’s transgender—might be too much for Wren.

While I’m not a huge fan of the “fated mate” trope, I really liked this story. It’s atypically well written and edited. The fact that Natalie is trans is only notable in that she’s scared that Wren won’t accept her when she finds out.

I only have two complaints. The first is that there’s a major complication introduced that hurts both of them and could have been avoided entirely by simply fucking talking to the person. I have difficulty putting up with that bullshit.

Second complaint is minor spoiler

When Natalie’s transness is inevitably revealed to Wren, Wren comments that she knew all along because she could smell the difference. I have two problems with this. First, your smell is based on hormones - trust me on this - and she wouldn’t be able to smell the difference if the person had been on hormones for years. Second, introducing this concept unnecessarily invalidates the idea that trans women are women by sticking a fucking asterisk on it. The author is trans, and I don’t think either of these slights was intentional, or that she even thought much about the implications, so I’m willing to give her a pass on it, but both things still bothered me.
🌟 [sapphic][nonbinary] Mate of her Own by Elana Abbot

Heather McKenna has no idea how to be a werewolf. Her wolf might be free from its cursed cage but has shut the door between the two of them, leaving Heather still reeling from the emptiness. When Heather discovers her mother is in the hospital, she is certain that closure from the person who cursed her in the first place will settle her wolf’s grudge and is quick to pack a bag.

V Raines sees the problems with werewolf society all around them. Despite being a nonbinary outcast in their own pack, they still have the responsibilities of being the Alpha’s only child. When their father attempts to pair them off with a dominant male pack member, V is all but ready to abandon their pack.

When V is called to the hospital to take care of a possible rogue shifter, they aren’t ready for the consequences of finding their true mate in Heather. V’s all in as Heather worries she’s not wolf enough to stand between V’s intense pack and her true mate. Fate just made their lives a lot more difficult.

A good sequel to Pack of her Own, and just as well written. Heather has no self-confidence (for good reason) and is constantly self-sabotaging. Normally this is hard to read, but Elena confronted it up front by having Wren - from the prior book - explicitly state that Heather tended to do that, and that it was a problem. That, plus the way the author handled everything else made me keep reading despite Heather’s constantly pushing away anything good in her life because she can’t believe it’s real or that she deserves it.

V’s a great character, and the fact that their non-binary is a well handled plot point.

The “fated mate” aspect of it is what sets things in motion between V and Heather but I’m still not a fan of the trope. It makes things feel less earned - at least early on - and like the people involved don’t really have say in the matter.

Content warning: threats of rape, and refusal to accept that V’s non-binary.
[sapphic] Her [adjective] Dragon Mate - Crescent Lake Shifters series by Arizona Tape A 10 book series of “fated mate” novellas. The core premise is that most dragons will never feel fulfilled in their relationship unless it’s with their fated mate. Dragonkin - humans who are the progeny of dragons ? I think ? - can be happy with or without their fated mate. If a dragon and their mate jump into a specific lake at a specific time of the month, the dragon’s unique mark will appear on the mate’s skin by the next morning.

Overall they’re a quick enjoyable read, although they really need a copy editor. Each one starting with two people who - for a different reason each time - aren’t together start to fall for each other, and eventually discover they’re fated mates. After that you get two quick chapters of “happily ever after” and it ends.

I wasn’t a fan of how everything seemed to just cut off and end the moment the characters discover they are fated mates.

Title adjectives are: rival, festive, fake, summer, sporty…

She has another series about bear shifters who have the same fated mate + magic lake ritual theme.
Hallow’s Cove series A six book series, each by a different author. They all take place in the same quiet little town mostly populated by “monsters”. All of the stories involve a human woman finding their fated mate with a monster - or two in the case of Wolves & Whipped Cream. All well written and edited,
- [heterosexual] Vacationing with the Vampire in Hallow’s Cove by Lyonne Riley City programmer / gamer girl escapes work for a month and starts to fall for her closed off vampire who happens to own the AirBnB she’s staying in, and the bookstore downstairs.
- [heterosexual][furry] Going Au Naturale at Hallow’s Cove by L.E. Elridge City girl falls for farmer boy who happens to be a fawn.
- [heterosexual] Love is Trash in Hallow’s Cove Two extremely neurodivergent people find each other and realize that the other person is just as “weird” as they are and willing to accept them with all their strangeness. One of them happens to be a racoon shifter.
- [heterosexual] Gaming with the Gargoyle in Hallow’s Cove He doesn’t tell her he loves her until it’s too late, then he gets a chance, but things are complicated.
- [polyamorous][bisexual][furry] Wolves and Whipped Cream at Hallow’s Cove A good story but too much hierarchical Omegaverse stuff for me when it comes to the sex scenes.
- [heterosexual][furry] Screwed by the Minotaur in Hallow’s Cove Average sized human woman meets giant minotaur. They proceed to have lots of sex and fall in love, but mostly they have sex.

The Reason I Didnt Sleep Last Night

Thu, 08 May 2025 00:00:00 -0400

Table of Contents

Overview

I didn’t sleep last night. Not really. Not for any meaningful definition of “sleep”.

I’d like to talk about why. I want to give Cisgender people a glimpse into what it’s like to be trans right now, and I’d like my transgender siblings to know they’re not alone.

Before I do though, I need to make sure we all understand the current context.

The Current Context

The word “genocide” was first coined by Polish lawyer Raphäel Lemkin in 1944 in his book Axis Rule in Occupied Europe… Lemkin developed the term partly in response to the Nazi policies of systematic murder of Jewish people during the Holocaust, but also in response to previous instances in history of targeted actions aimed at the destruction of particular groups of people. Later on, Raphäel Lemkin led the campaign to have genocide recognised and codified as an international crime. - The United Nations

The United Nations - of which the USA is a member - has recognized genocide as a crime since 1946. When you say “genocide” to most people, I think they get images of war, or concentration camps: what the Nazis, and the Khmer Rouge did, and what Israel is doing. But genocide isn’t just about bullets and gas chambers. It’s about eliminating a people.

The Convention on the Prevention and Punishment of the Crime of Genocide defines it as follows:

Article II

In the present Convention, genocide means any of the following acts committed with intent to destroy, in whole or in part, a national, ethnical, racial or religious group¹, as such:

Killing members of the group;

Causing serious bodily or mental harm to members of the group;

Deliberately inflicting on the group conditions of life calculated to bring about its physical destruction in whole or in part;

Imposing measures intended to prevent births within the group;

Forcibly transferring children of the group to another group.

The United States is actively perpetrating genocide against transgender people. The government is removing our rights, our freedoms, our health care, and our safety. People are being rallied with hate-speech and lies that target us. Violence against us is on the rise. Trans kids were already at high risk of suicide, but now… I don’t want to know what the numbers are.

Last year a city in Texas began offering a $10,000 bounty on trans people who dare to use a bathroom that conforms to their gender identity. In some states people can’t get driver’s licenses that reflect their gender even if they’ve gone through Gender Reassignment Surgery. In the US, your driver’s license is the primary form of ID that you have to show for even simple things like buying alcohol, or entering a nightclub.

Every time a trans person is forced to reveal their birth gender, or name, they expose themselves to violence, rape, and murder.

The shadow over everything

In eleven days I’ll be getting Gender Conforming Surgery (GCS)². It’s something I’ve been dreaming of for over thirty years. My thoughts should be filled with concerns about the surgery, the severe recovery, or how much I’m looking forward to the results. But the reality is, I’m not thinking about that. Every now and then I think about how I’ll finally feel “complete”, and about the huge weight that will be lifted. But those are just small thoughts that peek through the shadow of genocide, and my country’s descent into fascism.

This has manifested two ways for me. The first is fear, and anxiety that something will happen between now and my surgical date to prevent it from happening. It feels like I’ve been holding my breath underwater for too long. The surface is in sight, but my lungs are burning and I’m afraid I won’t make it.

The other is fear about everything else and the fact that I can’t deal with that right now. Right now all my energy is going towards holding myself together and trying to make it to the surface. But… I can see the world crumbling around me as I rise, and I know that I will be physically fucked when I emerge.

If all goes well, I’ll be cleared to resume a normal - low-impact - life in three months. For two weeks I’ll be exhausted, wracked with pain, unable to care for myself, and unable to move much. It is, in many ways, a real, physical rebirth, with all the attendant vulnerability. I should be concerned about this, and I am on some level, but more than that is the fear I’ll need to run, but not be able to. The fear that even after I’m recovered I’ll be forced to leave the wife, and home I love.

My father was a British Jew. He hid in basements while Nazi’s rained bombs down on London. I don’t know how many family I lost in Nazi camps. I don’t want to know, but I will place a stone, and shed my tears in their memory. I will remember that my queer ancestors were placed in cattle-cars just like my Jewish ones. I will remember that when the US rallied its people against the forces of fascism in World War II, we erected concentration camps of our own, and filled them with innocent citizens whose only crime was having Japanese ancestors. More recently we’ve thrown people who cross our borders into cages, stolen their babies, and sold them to white people³.

We created our concentration camps was when we were fighting fascism. Now, the US is racing headlong towards a fascist state, and trying replace our fragile democracy with demagogue dictator. The Jews aren’t the primary scapegoat this time. It’s my siblings and me.

So that, my friends, is why I didn’t sleep last night.

It’s true that transgender people are not “…a national, ethnical, racial or religious group…” It’s also true that anyone who believes that a group being left out of a list makes it morally acceptable to commit genocide against them is a fucking ass-hole with no empathy, who deserves to burn in the worst available hell. ↩︎
GCS is also called Gender Reassignment Surgery (GRS), and is sometimes still referred to as Sex Reassignment Surgery (SRS) although that term is outdated. ↩︎
Some might argue that the babies were “put up for adoption”. And this is true, but that process involves giving people babies after the prospective parents hand over money. That’s a sale, and that ignores the fact that the babies were kidnapped from their parents in the first place. ↩︎

Protests And Facial Recognition

Tue, 08 Apr 2025 00:00:00 -0400

Table of Contents

Overview

Protesting isn’t the same as it was in the 90’s, or before. Going out with 90,000 to complain about government actions was relatively safe, and very few people actually got arrested. You’d go. You’d show them how many people cared. You’d go home. End of story. Maybe the riot cops would come and things would end with people running away.

Now, showing up literally means adding your name to a public list of people who are opposed to what the government is doing. That’s not so bad if you’re an ally sticking up for other people. It’s not great if you’re one of the people being targeted by the government. Showing your face at a protest means telling them that you’re not just someone they don’t like, but someone who deserves extra attention because you’ll make trouble for them.

The Reality of Facial Recognition

Let me tell you a story about the intersection of facial recognition and public protest. A few years after the Boston Marathon Bombing I helped a local emergency management group (volunteer police) keep folks safe. I manned a radio tower and acted as the communication hub for our people. We were positioned by the start line next to the thousands of runners waiting for the start. One of the officers - let’s call him Ted - was a photographer, and took pictures of interesting things, including some of the various federal agents that were there.

You see, the FBI, the Secret Service, and others use the Boston Marathon as real world practice. Even if nothing goes wrong, it’s a chance to go into the field, deploy their gadgets, and practice doing their job. Local police and CERT people come from all across Massachusetts and are dispatched to points along the route. Mostly they just keep cars from trying to drive through the marathon, and make themselves available to radio in anything notable that comes up, like a medical emergency.

There is a list of volunteer officers & CERT folks participating, and we did all have special lanyards we had to wear, but there’s no way to look at one of us and know who the person was, and none of us needed to register our phone numbers with them or anything. That day, Ted wasn’t in uniform. Our stuff was set up, and he was just wandering around, taking pictures in public areas wearing street-clothes while we waited for the start.

His cell phone rings. He answers it. The person on the other end says “Stop that.” It was the Secret Service. They weren’t thrilled with him taking pictures of them - and the other feds - in a situation where there was a real possibility of terrorist acts. The only identifying thing Ted was wearing was a Lanyard with a color that identified him as police. They’d done what they were there to do. They’d spotted someone acting a little suspiciously. They’d used their gadgets, and in essentially no time flat they not only knew who he was, but had his phone number.

That was about ten years ago. Facial recognition has only gotten better. Computers have only gotten faster, and social media companies like Facebook have made good money selling people’s name’s and faces to government agencies, and anyone else who wants them.

Facial recognition of protesters is NOT a sci-fi movie threat. It is a reality that has been with us for over a decade. The only difference is that ten years ago the government wasn’t literally trying to re-imagine itself as Nazi Party v2.0

Fighting Facial Recognition

Facial recognition is good, but at the moment it’s also terrible at handling weird makeup. The most recent paper I’ve found on this is from Dec. 2024 titled Novel AI Camera Camouflage: Face Cloaking Without Full Disguise. You can download the paper on arxiv.org. The older methods of “CV Dazzle” ( Computer Vision Dazzle ) makeup patters don’t work anymore. The software has moved beyond that.

The short version is that masks and goggles keep you safe, but you can’t take them off. Some creative face paint can completely disable the software’s ability to recognize you as even having a face. I recommend you check out "‘Dazzle’ makeup won’t trick facial recognition. Here’s what experts say will" on Digital Trends for its overview of the situation and suggestions on strategies.

The other thing to keep in mind is that every time you post photos of protesters online without hiding their faces, you’re helping the government build a list of people they don’t like.

What You're Doing Now

Tue, 08 Apr 2025 00:00:00 -0400

Yesterday I saw a TikTok by a trans woman speaking up for herself, for all of us. In the face of fascist bigotry, she was proud, and strong, and defiant in all the best ways. She demonstrated that she’s exactly the kind of person everyone should strive to be.

Yesterday I saw someone on Mastodon positing that “If you’re wondering what you would have done during the holocaust, it’s whatever you’re doing right now.”

They’re right, but also… things aren’t the same. I’ve already written about the danger of showing your face at a protest. Right now, queer people need allies to stand up for us more than ever. It’s not just about having equal rights. It’s about not being thrown in concentration camps like we did to Japanese citizens when a US that was actively and publicly fighting fascism. Now the US is running head-first towards Nazi Party v2.0.

So, what am I doing right now?

I’m not doing what that amazing trans woman is doing. I’m staying home. I’m desperately trying to get bottom surgery before it stops being an option. I’m worrying about a repeat of Kristallnacht and past pogroms. I’m trying to get a foreign passport in case I have to flee this country. I’m checking lists of anti-trans laws before crossing state borders to see how dangerous Driving While Trans is. I’m not stepping beyond our borders, because coming back means federal agents looking at my passport, and possibly throwing me in the wrong prison for having a gender marker that matches the real me.

I’m hiding because I’m terrified of publicly standing up for myself. I’m afraid of even posting this, but I can’t say nothing. I need my trans cousins to know they need to take precautions if they’re going to protest. They need to be prepared to run. Those of us in places like Texas need to run. We have a tiny window where some states are still allowed to stand up and say “You’re welcome here”. Where we can be “safe” for a little while. Where we can find people who’ll help. Where we can not just be willing to run, but be prepared to run. Where we can pick a direction to head. Where we can pack a Go Bag.

I want to be left alone in my cozy house where my anxiety isn’t trying to give me panic attacks¹, where the daily rituals allow me to live comfortably with my autism. I want to be able to pee in rest stops and stores without fearing some self-entitled TERF is going to call the cops on me. I want to be able to walk in public without worrying about Nazi wannabes beating me to death. I want to know that if I get in a car accident the paramedics won’t watch me bleed to death on the side of the road instead of helping. I want to be able to get the hormones that keep me feeling “right” with myself.

I don’t want to be sent to mens prison where I’ll be raped while guards look the other way. I don’t want to be put in a concentration camp. I don’t want to have to run from my home, or hide from bombs like my Jewish ancestors did.

Right now, I’m speaking publicly on social media, which may be a terrible idea, but I know how much representation matters. I know what it means to know there are people like me out there. I know what it meant for an 18 year old me to see someone like me on TV and be able to give a name to the things I was feeling.

It’s not much, but it’s what I can do.

What are you doing? Is it enough? If not, can you do more, or get someone to help where you can’t?

If you’re trans, are you somewhere safe, with people who have your back? If not, run. Run now. They are coming.

It’s hard to read the news, but not reading it means not seeing what’s coming. It’s hard to think of how much I have to do, and how quickly things are going to shit. It’s hard to write this post. It’s hard to go to NYC to see my surgeon. All of it makes me anxious. The worst of it makes me freeze. ↩︎

Remarkable Tablet Wedge

Wed, 05 Mar 2025 00:00:00 -0500

Table of Contents

Overview

After writing a few hundred pages on my reMarkable Paper Pro I decided to stop using my stuffed monkey, trivets, and other found objects to prop up my tablet when writing. What came out was a simple object, but also one of the most satisfying things I’ve ever made, for physical, and emotional reasons. This post goes over what I did, how I did it, and why it means so much to me. If you just care about the last bit skip to “Satisfaction” at the end. If you are interested in 3D printing, read it all.

Problem Statement

Writing is just easier when the surface you’re writing on is angled towards you. Having something angled at the correct angle for your body is even better.

I want something that…

feels, and looks solid.
isn’t as large as the tablet itself
can be easily carried around the house

First Attempt

I took some measurements, did some math, and even worked through what a collapsible stand might look like.

The first version is a simple object. It only took me a few minutes to model it, but there are a couple things I’m proud of. First, I was smart enough to subtract the height of the felt pad on the bottom from the height of the wedge so as not to mess up the angle. The second thing is that my experience with 3D printing kicked in before I sent it to the printer and chose an print orientation that would avoid having any notable steps between layer lines.

It worked well enough, but there were two problems:

First: It turns out I regularly rotate my tablet as I’m writing for wrist and hand comfort. I had no idea. There’s nothing forcing the wedge to shift with the tablet. The cover is fricative, and adding a felt pad to the top would introduce enough friction to solve this problem, but it irks me on an emotional, almost physical level. It would be ugly, and I don’t like the idea of grabbing some wedge that’s felt on both sides.

Second: I find myself seriously annoyed by the wasted space of its interior. I wanted a drawer. I don’t have anything to put in that drawer, but I want it.

The color change was a happy coincidence. I ran out of the sparkly grey “metal” filament and swapped to a matte Marine Blue filament. And the contrast of shiny sparkly and matte in those two colors is amazing in real life. Alas, recreating it in v1.1 would require a lot of wasted filament because of how it has to be printed.

Second Attempt

Solving For Rotation

My unwillingness to rely on friction to solve the rotation problem meant I needed “ears” or “lips” maybe? I’m not sure what to call them. Little edges that stick up. I was considering only putting one on the left, but wise Wifey talked me out of it. The problem with having ears on both sides, is that they need to be close enough to the sides of the tablet so that they start rotating the wedge quickly, but also far enough away on the right that you can easily attach the pen to the side for storage and charging.

The ears did introduce a printing complication.

The Drawer

Requirements

must not slide out freely when carrying it around
must provide no opening for contents to fall out when carrying around
must be big enough to support pens, styluses, and other items.
must be aesthetically pleasing

Staying Shut

Initially I wanted some kind of push-to-open mechanism. I used a bunch of notebook pages working out ways of doing this with an array of magnets arranged in opposing and attracting patterns to create a spring mechanism, then a rack and pinion design. Then I practically face-palmed when I realized I’d just solved this exact problem with simple plastic spring tabs with corresponding holes in my small under-desk drawer design.

I started to iterate on that, but then realized I could do something more elegant with magnets.

Hidden inside the print are two 10mm x 2.75mm disc magnets. They’re hidden not just by virtue of being deep inside the wedge, but also because they have two layers of plastic encasing them. I did this because rare earth magnets are surprisingly fragile, and I was concerned about whacking the magnets in the drawer against these repeatedly. I wanted to cushion the blow, both because it’s impossible to get in there and replace them, and because I didn’t want the “clack” sound of two magnets hitting.

This introduces printing complications.

The drawer has another pair of magnets in the corresponding location. I considered encasing these as well, but doing so would have introduced a significant printing hurdle, and I don’t have a problem the aesthetics, especially since you rarely ever see them.

Magnets Magnets Everywhere

I have a variety of small magnets in my toolbox for projects like these. I experimented with thin rectangular ones that were 1mm thick, and a variety of small disc magnets until I found some that were wide enough to address any potential alignment issues between the magnets on the drawer and the ones in the wedge, and had the right amount of pull. 1mm thick just didn’t provide enough force, and they’re trivially easy to snap. 10mm x 4mm proved too much force. I experimented with some 6mm x 3mm but the 10mm x 2.75mm I settled on had a nice balance of surface area and pulling force.

Opening

Having a pull tab that poked out past the side wasn’t an option, nor was having something small and fiddly that you could only get your fingertip into. I wanted something easy to use that felt nice to touch when using. After some sketching, and modeling I ended up with this.

In hindsight, I can see that it’s a swanky version of the pull handle you see on most file cabinets that I’ve rotated 90°. After measuring my finger, I worked to create a curve that would guide my finger gently into the right position to remove the drawer. I intended to cover the top of this, but my gut told me that it would look cool to leave it exposed. I was not disappointed.

Leaving the top exposed also solved a printing problem.

Feel

While I wanted a flush face when closed, I also wanted rounded corners everywhere else. I hate handling unnecessarily sharp edges. So, all the inner and outer edges that wouldn’t effect the flush-fit of the face have been rounded.

This introduced the need for a little bit of math, because rounded edges of the drawer that fit into the rounded edges of the hole have to have a slightly smaller radius, and that needs to account for the way the plastic spreads as it cools. In the end the hole has a 3mm radius fillet (curve) on the bottom edges, and the corresponding edge on the drawer has a 2.2mm radius fillet.

The Printing

I had three problems to deal with.

both pieces had to be printable without supports. First: because I wanted nice smooth surfaces and supports always leave imperfections. Second: because the places where you wouldn’t see the result of using supports were places that would be incredibly difficult to cleanly remove them.
Filament expands as it settles and cools, and glue isn’t infinitely thin.
Some magnets needed to be completely encased in plastic.

No Supports

In order to encase the magnets in plastic, the wedge had to be printed on its end which meant that the upper “ear” would be hanging out into open space. Supports are almost always needed in that scenario, because you can’t just print into empty space and expect the hot filament to not fall down. But, if you can offset each layer juuuust enough you can create an achievable arch or angle. Back in the cad software I increased the radius of the inner fillet (curve) where the ears meet the top of the wedge.

The drawer didn’t need any supports because the magnet holes on the end were large enough that the top arch of the circle could support itself as it was printed, and I’d chosen to leave the finger pull open at the top.

Because of the way a standard filament printer works, it just wasn’t possible to encase the drawer’s magnets in plastic and have no supports. I decided to leave them exposed.

Expansion & Glue Issues

You can’t print a 10mm void and expect a 10mm magnet to fit. The filament will squeeze inward as it cools and create a hole that’s slightly too small. With my printer I can pretty reliably assume just under 0.2mm of spread. When I add that much to the radius of the magnet hole, I get an almost perfect fit.

In the case of the drawer I designed it to be 0.8mm smaller than the hole it was fitting into, on all dimensions. This ended up being perfect.

In order to account for the gel-like Cyanoacrylate glue (Super Glue) that would hold the magnets in place I added 0.25mm to the depth of the magnet holes, and that worked out perfectly.

Encasing Magnets In Plastic

There are three complications with embedding magnets in a print

You have to stop the printer mid-print, insert magnets without disturbing anything or getting glue anywhere it shouldn’t be, then resume the print.
I use a hardened steel nozzle, which the strong rare-earth magnets really want to stick to as it passes above or nearby.
The inserted magnets need to not interfere with the print head when it goes to lay down the next layer.

The first problem is pretty easy, but required a little prep. I added a pause in the slicer just after the layer that finished the walls of the magnet holes, set a timer for 33 minutes into the print so that I’d have a couple minutes to get ready, grabbed gloves, glue, paper towel, and a magnet insertion tool.

The tool is just a plastic wand with a magnet glued to the end of it, but it’s critically important because it guarantees that I have the magnets pointing in the correct direction, and it keeps my fingers away from the glue.

When the pause was about to happen I had gloves on, two magnets ready to be picked up with the tool, the flow pre-tested and ready to squeeze - sometimes the bottle gets clogged. When the printer paused, I picked up my tool, picked up a magnet, added a small amount of glue to the magnet, carefully inserted it, wiped away any excess glue, and repeated. Then I waited a full minute for the glue to set because CA glue cures by being exposed to air, and there is basically no air on it when it’s squeezed into the hole.

The problem with magnets not being able to interfere with the print head is the main reason I couldn’t encase the ones on the side of the drawer. Not without leaving a void around the top half of the disc which I wasn’t happy with.

Satisfaction

The end result is, in my opinion, beautiful.

That’s not what’s really satisfying for me though. The first glimpse of that feeling came when I slid in the drawer for a test fit before inserting its magnets. The fit is so perfect that the air pressure cushions it as it approaches the end of the insertion, and gives a hint of resistance as you pull. Not only that, but it stays in really well without the help of magnets.

It’s a satisfying feeling, the gentle friction as it slides, and the effects of the air pressure. It was also a reminder of how far I’ve come. With a combination of experience, and trusting my gut for aesthetics and some measurements, I was able to design something that does fits beautifully; both itself, and the tablet it was designed for. It printed beautifully. Encasing the magnets went perfectly. I love the way it feels as my finger slides into place, guided by the curve. I love the way it looks when I see my finger curled into that handle. I love the flush fit of the drawer, and the soft curves of the edges I hold on to.

Creating this simple object required a lot of experience to not only know what complications would be encountered, but to know how to address those issues. Even the simple curves of the edges are the result of years of experimentation to know what feels good, what looks good, and what constituted big enough, but not too big.

In the end, I’ve created something I’m really proud of, that has helped me see just how much I’ve learned on my journey to be a better Maker.

Want One?

I’m considering selling physical versions of this, and the models with assembly instructions, and a bill of goods for the felt bottom and magnets, for people who have 3D printers. If you’re interested drop me a line on the Fediverse (Mastodon) at @masukomi@connectified.com or via email at masukomi@masukomi.org. I’m not very good with email though. Physical ones would probably be $40 or more. The raw materials to print and ship cost ~$11 USD and that doesn’t include time spent cutting the felt foot to shape, attaching it, or having to be sitting beside my printer at the precise time it will pause so that I can insert the magnets. 😉

Postscript

You may have noticed that the new wedge is entirely Marine Blue except for the side with the drawer. I ran out of Marine Blue filament 96% into the print. I swapped it for something else while half asleep at ~4 AM when the dog asked to go pee. The color was lighter than I realized in the dim light, but it was already starting to work its way through the system when I realized this, and I was too tired to deal.

It works great in photos for showing a clear distinction between drawer and side though. So, another lesson learned for future product shoots.

So Long Kindle, Hello Kobo

Sat, 11 Jan 2025 00:00:00 -0500

Overview

Amazon bricked my Kindle. I begrudgingly got a new one. I hated it. I replaced it with a Kobo Libra Colour which I freaking love.

This post is an explanation of what happened, and why I’m so much happier with the Kobo.

Backstory

Last year Amazon bricked my Kindle. I was pissed. I hated the idea of buying another one, and giving them any more money. However, there were some things which made me do it anyway.

They’ve got more books than anyone.
“WhisperSync”

Since then, I’ve also learned that a lot of self-published authors only publish via Amazon, so if you want their stuff, that’s the only way to get it.

WhisperSync is a mechanism by which you can listen to a book in Audible, and simultaneously read it on your Kindle while the Kindle highlights the words as they’re read, and turns the pages automatically. Sometimes I really want to enjoy the voice actor’s contributions to the text, but ADHD makes it almost impossible to sit still and do this because it’s not enough stimulation.

Problems

After getting the Paperwhite, two problems emerged rapidly.

I fucking hate the kindle paperwhite.
Not a single book I’ve listened to since getting it has been “WhisperSync enabled”

The Problems with the Kindle Paperwhite

The biggest problem is how you’re forced to interact with it (its UX).

Obviously, there are no page turn buttons. This is terrible, but it’s made worse by software choices.

Tapping most of the screen advances the book forward by one screen. As far as I can tell they’ve dedicated the right 75% of the screen to “move forward” functionality. You’d expect the “move back” and “move forward” tap zones to be roughly the same size. They’re not. The end result is that 90% of the time I try and go back a page I end up going forward a page.

Tapping a wee area across the top of the screen gets you some settings, but not all of them. There is no visual indication that tapping up there will do anything other than turn a page, and there are lots of people who can’t figure out how to get back to their library of books because the link to do that is hidden in that little area you’re unlikely to ever try tapping.

Swipe gestures. You can swipe up from the bottom, or down from the top. Swiping down from the top brings a different slide-out menu than tapping at the top which doesn’t include a way to get back to your list of book. Why? Who knows. There is no indication that swipe gestures are a thing.

The home screen has 3 rows of books, 1 of those is a row of books they want you to buy.

The Kobo Libra Colour

If you want physical page turn buttons in an e-reader, you have precisely one option in early 2025. It’s the Kobo Libra Colour (henceforth KLC).

That’s what got me looking at Kobo in the first place. I don’t know why e-book manufacturers hate buttons. I assume it’s just prioritizing cost over user experience.

Turning Pages & Finding Menus

The KLC has physical page turn buttons, but it also has a touch screen which you can tap to move forward or back in your books if you want. The right third of the screen navigates forward. The left third of the screen navigates back. Tapping the center brings up menus. Tapping the top edge brings up the same menus. Tapping the bottom edge brings up the same menus.

It’s all incredibly intuitive. It “just makes sense”.

Even better, you can adjust it if that layout doesn’t “just make sense” to your brain.

There is a swipe gesture from the top, but forgetting it exists won’t hurt you because it’s just a way to quickly navigate to recently opened books. Swiping up from the bottom brings up the same menus as everything else that brings up menus.

The page turn buttons are really nice. I would put them in a different location if I was designing the device, but where they are is good enough, and doesn’t annoy me.

Holding it

The section of the device that holds the physical page turn buttons is wider than it needs to be for the buttons. This makes it easy to hold the device from the side instead of the bottom. It’s very comfortable. The slight curve up at the edge means you don’t have to hold as hard to keep it from slipping. The Kindle and the Kobo are both incredibly light, so this isn’t a big deal either, way. Never-the-less it is more comfortable to hold.

The screen rotation, and button placement means that left-handed folks can use it just as easily as right handed.

Reading on it

Screen

It’s great. Colors are washed out, but that’s because no-one has figured out how to make an e-ink screen where the colors aren’t washed out. It’s just a current limitation of the technology.

Backlight

Unlike most (all?) kindles, you can turn it off. It has fine grained settings for brightness, and can go very dim or very bright. You can adjust it from very cool blue, to a nice warm yellow. Those adjustments feel less fine grained but the end result is fine.

Fonts

The Kobo makes it easy to override the fonts that any book comes with. Notably, the options include fonts specifically designed to address accessibility needs: Atkinson Hyperlegible from the Braile Institute for low vision users, and Open Dyslexic for dyslexic readers.

Changing the font size is easy, but the controls are too fine-grained for my taste. I prefer how Kindle handles this. I don’t need a slider with 100 steps from smallest to largest.

Dark Mode

It has one. It’s buried in settings, so it’s not trivial to toggle, but it works well.

dark mode

Book Selection

If its from a major publisher it’s definitely available on Kobo. Small and mid-sized ones seem to all be there too. The problem is with self-published authors who only distribute books via Amazon. If you read a lot of romance novels this may be a big deal.

We must also consider what’s available via “Kindle Unlimited” vs “Kobo Plus”. Kobo claims to have over 1.5 million eBooks and over 150,000 audio books available via their “Plus” programs. What I found surprising was that many (most?) of the books that I have wanted to read that were part of Kindle Unlimited, do not seem to be part of Kobo Plus, even if they are available.

I can’t tell if it’s just the books I’ve been looking at or if books are just generally less likely to be available via Kobo Plus.

Pricing is comparable. If you sign up for their $10 per year VIP program you’ll end up saving money purchasing books on Kobo instead of Amazon.

Audiobook Selection

Kobo seems to have most of the books that are on Audible, however the percentage available for “free” via Kobo Plus seems small. There are very few free books on Kindle Unlimited too.

As far as I can tell there is no way to view the audiobooks available via Kobo Plus. Maybe you can if you have Kobo Plus. Amazon does have page listing all the audiobooks on kindle unlimited, but it also says there are “over 6,000” even though there are more than 4,000,000 ebooks and magazines available.

Kobo doesn’t have an equivalent to WhisperSync, but in my experience essentially none of the Kindle books I want to read have that enabled.

Libraries

Borrow With OverDrive option

Users based in the US with library cards likely borrow their ebooks via OverDrive (Libby). The KLC not only has OverDrive integration built in, but the details page for every book makes it trivially easy to borrow the book if it’s available, or put it on hold if someone else has it checked out.

The Home screen gives you quick access to the books you have checked out and the ones you have on hold.

Limitations

You can only see books that Kobo offers for sale. If your library has an e-book, that Kobo doesn’t carry, it won’t show up in Kobo’s search results, so you won’t have the option to put it on hold, or borrow it directly via the Kobo.

However, books that you put on hold via Libby, or the OverDrive web site are displayed in the list of books you have on hold, and books you check out via the OverDrive site (and Libby?) just show up in “My Books” along with purchased books.

There doesn’t appear to be a good way to see which of “My Books” are once you’ve borrowed from your library and will have to return soon, and which are ones you’ve purchased and can read whenever.

Happy Surprises

Lack of greed

The Kindle is trying to sell you something at every opportunity. You can load books onto it from your library, or books that were purchased directly from an author’s web site, but it’s a pain in the ass.

Every book detail page has a prominent button to, let you ask your library to put a hold on the book. It also has Dropbox and Google Drive integrations built in. They want you to use the device and they are perfectly happy to let you load books onto it that you got from other sources.

Wake Speed

When you have a “sleep cover” (a cover with magnets in specific locations). It wakes instantly. As soon as the cover is out of the way, it’s ready to read.

I don’t know what the Kindle is doing but it takes seconds to wake, and it’s really annoying once you know you could have “instant”.

Home Screen

Other than being annoyed with the fact that ⅓ of the Kindle’s home screen was dedicated to selling me more books, I never really thought much about it. It was “ok”. It worked.

The Kobo home screen is great

The Kobo Libra Home Screen

The top row is books you’ve read most recently. Below that you have two blocks “My Books” and books by a specific author. I’m not sure how it decides what author’s books to highlight. It’s not the author of the most recently read book.

Below that are two blocks for interacting with library books, one to borrow books, and one to see the books you have library holds on.

Along the bottom edge are useful buttons for “Home”, “My Books”, “My Notebooks”, “Discover”, and “More”.

Guided Discovery

Kobo will ask you a handful of general questions when you first start. It seems to also pay attention to what books you read, and use that to help suggest new books.

Overall, it’s pretty good. I’ve found a bunch of new books that I’ve enjoyed that way. It’s not perfect though. It’s figured out I’m queer, but not that I’m a lesbian. So, it keeps suggesting books about gay men, that I’m never going to buy.

Sleep Screen

Kobo offers the optional ability to optionally display the cover of the book you most recently opened. If you turn on this feature it will display the cover when you turn the device off, and when when it goes to sleep when you leave it alone for five minutes.

This may, or may not, be a good thing depending on what you’re reading. There are lots of books that people read that they wouldn’t be comfortable with their friends, family, or coworkers knowing they’re reading.

If you’re only going to be reading in “safe” environments, then this feature is pretty great. Unfortunately, if you’re not comfortable turning this on, the default sleep screen is aggravatingly ugly.

Side note: As far as I know, no e-ink device manufacturer allows non-geeks to put custom sleep screens on their device. As with many of these devices, a computer geek can set one but they’ll have to go through the process every time the device receives a software update. I haven’t dug into the details of this on the Kobo, so I maybe it doesn’t reset every time.

Unhappy Surprises

The following are true as of January 2025, but the situation may have changed by the time you’re reading this.

Books in a series

Note: this problem is limited to the e-ink device not the web site.

Kobo sometimes indicates that a book is part of a series, but there’s nothing you can click to see all the books in the series. When you complete one book in a series it has no idea what the next book in the series is.

It’s as if there’s a metadata field on the book that’s called “series name” and holds text, but has no actual functionality connected to it.

There are some screens where you can click on a series but it doesn’t actually show you the books in the series. It performs a search for the name of the series, which brings up a bunch of other unrelated books with similar titles.

More by this author

Note: this problem is limited to the e-ink device not the web site.

Same problem as books in a series. You can’t see a list of books by an author, and when there is a link to click with the author’s name, it just performs a search for that name. Unsurprisingly, this brings up a bunch of books by authors with similar names, and books with that name in their title somewhere.

OverDrive integration

Note: this problem is limited to the e-ink device. As far as I can tell there’s no OverDrive integration on the web site or iOS app.

OverDrive is a company which allows libraries to pay obscene prices to loan books to their patrons. Unfortunately libraries don’t have an alternative, and if you want to borrow from most libraries in the USA, you don’t either.

In addition to being part of a morally bankrupt system, OverDrive’s software is crap. It’s not uncommon to try and put a book on hold and have it just spin at you infinitely. Other than forgetting to add a reasonable timeout, I have no reason to believe that any of the library integration problems can be blamed on Kobo’s developers. When it works, it works well. When it doesn’t it just spins at you.

iOS integration

Amazon is rich and was able to negotiate some sort of better deal with Apple. Kobo doesn’t have that privilege and doesn’t seem to be able to afford Apple’s cut. As a result, you can’t buy ebooks in the Kobo app.

If you choose to add payment info to your account you can buy them directly on the device, and that process is painless.

Find them on the app. Add them to your wishlist. Load the wishlist on the Kobo device, or on the web site, and buy them there.

Writing with the Stylus

I can’t comment on this. I have a Remarkable Paper Pro which I absolutely adore and use for this purpose.

Backups

There’s a great plugin for Calibre that makes it trivial to back-up books from your Kobo. Press a button, choose books from a list, and they’re downloaded. As with other devices, it’ll tell you if the book on your Kobo device is also available in your library of backups. For the most part, it “just works”, and you can also make backups of books you’ve borrowed via your library this way.

That being said, it has had trouble importing a couple books from the Kobo. This is probably related to a different DRM scheme on those books.

With Kindle you have to download books one-by-one in a special format from a hard-to-find screen, and then manually add them to Calibre.

No-one has managed to crack the encryption on Kindle Unlimited books so you can’t back those up. I don’t know if the same applies to books acquired via Kobo Plus or not.

Summary & Anecdote

The other day I got a book that was only available via Kindle, and was free via Kindle Unlimited, which I still have a subscription too. Yes, I’ll probably be canceling that soon. I loaded the book up on my Kindle and started reading on the couch. I complained so many times about different things that were worse on the Kindle that eventually my wife looked at me and said “Are you actually reading the book, or are you just complaining about the Kindle?”

Get the Kobo. It’s awesome.

We're Not Missing Out

Thu, 02 Jan 2025 00:00:00 -0500

Table of Contents

The Problem

My wife and I are still acting as if Covid is a real threat to our health an safety, because it is. Our friends & family think we’re “missing out”. They believe we are living significantly diminished lives. They think we’re living in fear. They’re worried for us, and frustrated with our limitations. They can’t imagine a world where we’re acting this way and not hurting and / or fearful.

We understand why they think we’re living in fear - even if they’re wrong - but we have no idea what they think we’re “missing out” on.

This post is an attempt to explain why they’re wrong. I also hope it might be useful for others dealing with similar problems. This is not an attempt to convince anyone to change how they’re living their lives.

First though, I need to explain what we’re doing that has them so worried.

We’re still unwilling to go into buildings unless absolutely necessary.
When friends want to visit we stay outside on the deck, we only let them in to use the bathroom, and we thoroughly ventilate the place afterwards.
We always wear KN95 masks around other people unless there’s a medical reason to take it off.

Because of our self-imposed restrictions we:

don’t go to the movies
don’t eat in restaurants
don’t go to social gatherings
don’t physically hang out with friends except very rarely in small groups outside.
don’t go into stores
don’t go into supermarkets
don’t go into gas stations, even to use the bathroom.

So, for the people who care about us, and people who care about others like us, let me try and explain why none of that matters to us.

Overall our thoughts on these can be summarized as “complete indifference” or “mild inconvenience.”

Loneliness

People think we must be lonely, but the important thing to understand is that just because you might be lonely in a situation doesn’t mean that everyone would feel lonely in it.

We moved away from Boston in 2017, before Covid. We moved to get away from the stress of the city, and it worked. It worked tremendously well. However, when we moved we put a mountain range and hours of driving between us and all of our friends. We didn’t move to get away from them, but it was a consequence of our choice.

We have no friends in this town. Most people think that’s a sad thing, but it’s not for us. The first couple years here we kept telling ourselves “We should make some friends here.” But, we said it more because of the social expectation to do so, and because other people think it’s sad to not have friends nearby.

There are plenty of social opportunities for adults to hang out together around here. Some of them are even things we enjoy doing. But, we kept not doing them. We’re not afraid of new things. We’re not afraid of meeting new people. For those who don’t know, we rode motorcycles from Boston to the bottom of South America. We were constantly in new situations that were sometimes uncomfortable, or scary. The conversations we had with strangers along the way were some of the best parts of the trip. So, that wasn’t the problem.

The truth is, we just didn’t feel like it. Mostly because we still have our friends. We have video chats with different friend groups twice a week, and wifey and I both have one on one chats with other friends weekly or monthly. If anything, we hang out with friends too much. Sometimes we just want to melt into the couch at the end of the day, but we like our friends and know that a lack of regular contact hurts most friendships. So, we stay in contact.

We’re not lonely at all. We have people to talk to. We have friends who’ll listen. We have each other. We’re never sick of each other’s presence.

Public Entertainment

I mention the following things specifically because everyone seems to think this is something we’re definitely “missing out” on.

Movies & TV

We haven’t been to a movie theater since 2017. The neighborhood theater is incredibly convenient to get to. There’s even a drive-in not far away. Before Covid we went to a craft fair and won free tickets to the local theater. We still have those free tickets somewhere.

When we were in Boston, we basically only went to the movies when a friend asked us to join them. Now, with no friends asking us to go, we just don’t care. We have zero desire to do so. There’s a lingering feeling that “we should go to the movies” but every time we actually investigate that feeling we decide “meh, why?”

It’s not because it’s so much more comfortable and convenient to watch at home. We simply don’t stream movies. We have some favorites on blu-ray that are just collecting dust. Sometimes wifey streams a tv-show that interest her. Sometimes I stream some anime. Mostly though, we watch Dimension 20 (TTRPG Actual Plays) while we eat dinner, and then get comfortable and play video games on our PlayStation, work on personal projects, or read. With rare exceptions, we don’t chat with friends about the series that “everyone is watching” or about movies we love, or any of that. Even then, it’s only wifey who has watched it.

That’s roughly what our routine has been since we moved here. We like it. It’s comfortable, and quiet, and cozy.

Performances

We’ve been together for like thirteen years. We’ve been friends for longer. In that time we went to probably two concerts by ourselves. Every other public performance we went to was the result of friends asking to go. Not us actively seeking something out. We had fun at those, but we would have never gone if the friends didn’t ask.

I don’t think either of us will regret it if we never see another live performance.

Restaurants, & Bars, & Parties

It’s true we miss restaurants. It’s also true that our town has terrible food options, and we’ve been lamenting at fact since before Covid. It’s not that we never eat other people’s food. We get pizza delivered. We go through drive-thrus. It’s just that the options suck. If we had better options now we’d use DoorDash or some similar service more, but not a ton.

Wifey never asked to go to a bar in all the time we’ve been together, and I don’t think she ever gone to one with friends either. Not in that time at least. I’m autistic, so I hate bars. They’re too loud, too crowded, and require way too much masking to be enjoyable. I also had an alcoholic dad, so I hate being around drunk people. I’m not even comfortable being around drunk friends in safe places.

I don’t like big get-togethers either. They’re just exhausting. They require constant masking, and “being present” for people you only see at gatherings like this, and never chat with otherwise. Wifey has never mentioned missing them, but I know they took a lot out of her too.

Physical Interactions

(Friends: this is blunt, and honest, and socially unacceptable, but it’s also who we are. If this hurts your feelings, I’m sorry, but also, I kinda wish you’d asked.)

As a general statement, Wifey and I don’t want to ouch anyone. I’m autistic - we generally don’t like touching people - and Wifey has her own reasons. When friends do come over we hug them because it’s a social expectation that we will, or because or friends initiate one. I don’t mind hugs from old friends. Sometimes they’re nice. I also don’t miss hugs from friends.

Think of it like not getting to eat sourdough bread again. Most people don’t actively crave it very often, or very strongly, and thus loosing access to it isn’t something they lament. The full truth of our thoughts on touch is more nuanced than that, but I think the metaphor holds pretty well for most of the people we know.

There are two people I actively want touches from, and both of them have been explicitly told that. Fortunately for me, I married one of them.

Shopping

It’s fucking exhausting. Supermarkets are literally designed to wear you down until you have a hard time resisting buying things you don’t need. It’s nice to never have to shop in one in person again.

We miss going to cheesemongers & fishmongers, but we didn’t do that very often anyway. It would be nicer to be able to try clothes on before buying them, but we rarely ever buy new clothes anyway.

We never went shopping as a form of entertainment before Covid.

Gas Stations & Travel

Covid has curtailed our travel dramatically. We used to take motorcycles, or cars, or other things around the country and beyond roughly every year.

Now, we don’t for a variety of logistical reasons. But we’re not really “missing out”. I used to ski and snowboard when I was a kid. I’m not “missing out” or lessened because I don’t do those anymore. When we visit our friends we bring a porta-potty. When using the car we bring a pop-up privacy tent thing. When using the ambulance, there’s a place for it in the back. We’ve seen each other use the bathroom before. It’s not a big deal.

The toilets is a minor inconvenience. Travel would be nice, but staying home is nice too.

Fear

We live in fear of Covid about as much as we live in fear of touching a hot stove. For the most part we just take basic precautions to not let it hurt us and don’t think about it otherwise.

Summary

Other than good food in restaurants that don’t exist around us, we don’t feel like we’re lacking much.

We like our life. We like where we live. We like the home we live in.

Is our life perfect? No. Is anyone’s?

When we left the city we lost access to many of the things people take for granted as things that “everyone” does. We learned that we don’t care about most of them. We learned that we were happy just existing with the person we love in a home that we love and talking to friends online. Being able to have almost anything we want delivered within a week or so makes it easier, but even without that I think we’d be pretty happy.

The problem - as we see it - isn’t that we’re “missing out”. The problem is that most people seem to think they need so much in order to be happy. Sometimes that’s things. Sometimes that’s activities. Sometimes that’s people. Whatever it is, it’s almost always an attempt to fill a void. Social interaction is important to us, but we don’t need it to be physical, and we’re comfortable enough with ourselves and our lives that we wouldn’t be unhappy if we didn’t talk to anyone outside our home for a month. Honestly, it’d be kinda relaxing.

Life is a lot simpler when you learn to be happy with yourself. When you can be honest with yourself, and your partner(s) about what feels good, and what feels bad, you can create a space that you enjoy being in without constantly needing “something else”. Sometimes that takes a lot of therapy, and uncomfortable conversations. It’s worth it though.

We’re not afraid to go get or do the things we want. We simply don’t want to go get or do much.

Why we’re still cautious

For those curious:

Covid is still killing people daily, and it’s not just the old and weak - not that that would make it any more acceptable.
When you get covid you dramatically increase your likelyhood of heart disease and Alzheimer’s. This isn’t a “long covid” thing. This is true for everyone who gets covid.
Whenever you get covid there’s a 1 in 10 chance of getting long covid. We’re a single income household and we’re both knowledge workers. If the person with the money and insurance gets that then we’re fucked. Not just financially and physically. We would also loose the ability to work on the projects we love.
Comorbidities. If wifey gets covid she’s significantly more likely than the average person to be fucked over by it.

The Joy Of No Batteries

Wed, 16 Oct 2024 00:00:00 -0400

Table of Contents

Overview

A musing about my enjoyment of Scheme and having to work a little harder.

Unfamiliar with Scheme?

Side note for those who aren’t familiar with Scheme:

Scheme is an umbrella term for many languages. Most of them try and follow one of the official standards like R5RS, but some go off on their own and explore completely different paths like Racket. Schemes are considered dialects of Lisp, but Lisp too is a term for a collection of languages. I’ll use the terms somewhat interchangeably below.

Please also see the bit at the end before complaining about the parentheses to me.

Old Cycles & New Learnings

I’ve been coding professionally for just shy of 30 years now. All of the professional work has been web development.

At its core web development is taking form submissions, sticking them in a database, taking the stuff in the database and showing it on a web page to read, or a web page with a form to edit. That’s it. I don’t care if you’re using Rails, or Django, or Phoenix, or some homebrew creation. The back end is essentially the same. It’s not until you start approaching Google scale that what you do, or how the infrastructure supports that begins to change.

Most of us don’t deal with requests at that scale. Most of us are coding minor variations on the same thing again and again. I suspect that it’s the same for back-end developers in any vertical, be it mobile games, or radar systems. Even if you switch languages it’s the same stuff with slightly different syntax most of the time.

I suspect that’s why so many of us work on hobby projects, or open source libraries even though they’ll eat up our free time, and are unlikely to ever make us money. Those of us who love programming, love the problem solving, and figuring out how to express an idea with in a different set of constraints.

Batteries Not Included

A programming language that has “Batteries Included” is one that has a large / versitile “Standard Library”. Languages like Ruby could be said to come with not only “batteries”, but a spare generator, & solar panels. It’s got a web server, JSON parser, HTTP support, and lots more.

Scheme’s aren’t like that. Some Scheme’s - like Racket and Chicken Scheme - have a thriving ecosystem of third party libraries, but with the exception of the SRFIs¹ those libraries are frequently written in ways that make it as difficult, or awkward to use them as to write your own implementation.

In the end, you end up needing to write a lot of your own “batteries”, and that means thinking about “simple” things that you’ve been using for years, but probably never thought about before.

Forced Thought

This is where Scheme comes in for me. Scheme is considered a multi-paridimatic language. It’s not explicitly functional, and there are various Object Orientation libraries that have been written for them. It’ll let you write code in a very OOP-like fashion, but everything seems to work a bit more smoothly if you embrace a more Lispy approach.

For most of us that means a different approach. For example, by default Scheme doesn’t have an method to break a loop or return early from a function, at least not like most languages². This isn’t a bug, or an oversight. You just don’t need them when you start thinking in a Lispy Way.

Lisp, and by extension Scheme, has a historical mystique to it. It’s a fundamental part of the history of machine learning and programming language creation.

I learned it because - at the time - I hadn’t done any functional programming and I wanted try something that would give me new challenges & force me to learn new ways to solve problems. Common Lisp³, & Scheme gave me that. Those learnings helped give me new solutions to problems in my day job too.

But I’ve been finding real joy - and frustration - in having to implement little things that we take for granted in other languages. For example, yesterday I needed to extract the first, or last N elements of an array. In Ruby I could do something simple like this.

long_array  = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
array_start = long_array[0,3]  # => [1, 2, 3]
array_end   = long_array[-3..] # => [8, 9, 10]

Scheme has a lot of list manipulation functions, but it’s also missing a lot of things we take for granted, so when I didn’t find a function to do this (see below), I figured I had to write my own. This is frustrating when you’re trying to get something done quickly, but it can also be joyful in that it makes you stop and think about simple things. “🤔 how do I efficiently select a subset of a list?”

My solution uses tail recursion, and Scheme’s ability to define a function within a function which lets me expose a wrapper function (first-n) to the world that doesn’t force the users to deal with passing in an accumulator, and doesn’t add a second top-level method to this module that future me will have to think about separately. It also doesn’t use any loop / iteration functionality. It’s radically different than how I’d solve the same problem in Ruby, but I think it’s also a pretty Lispy solution, that runs quickly.

  ; returns the first n elements of the list
  (define (first-n number a-list)
    (define (inner-first-n number inner-list accumulator)
      (if (or  (eq? (length accumulator) number)
               (null? inner-list))
          accumulator
          (inner-first-n number
                         (cdr inner-list)
                         (append accumulator (list (car inner-list))))))

    (if (> (length a-list) number)
        (inner-first-n number a-list '())
        a-list))

Scheme’s got a lot of oddly named functions, so occasionally you’ll not find a built-in one just because you don’t know what keyword to search for. In this case, I didn’t know the built-in methods for this behavior were called take and take-right, and I’d never heard anyone refer to that behavior as “taking”.

Even when I found those, I had to modify things, because those methods don’t behave well when you pass in a list that’s shorter than the number you’re trying to take, and Scheme doesn’t have built-in try/catch exception handling like most languages⁴. There are libraries to do it of course, but the point is that even when there is a “battery” - built in or 3rd party - you frequently need to futz with it.

  ; returns the first n elements of the list
  ; or the entire list if its length is < number
  (define (first-n number a-list)
    (if (<= (length a-list) number)
        a-list
        (take a-list number)))

Thinking about this as I write it, this sounds terrible. Admittedly, sometimes it is damn annoying having to write so many wee low-level functions.

I’ve got a module that just a bunch of list manipulation functions to let me easily implement common tasks that aren’t built in, like sorting a list of strings. Every one of those represents a little bit of learning, a problem that I’d never have to solve in my day job.

Each one of those is also written in a way that matches my brain. That too is one of the arguments for, and against, Lisps. Codebases, it is argued, tend to end up looking like DSLs where everything is a function tailored to the specific purpose of the app. You can end up with a codebase that makes weirdly specific things incredibly easy, but also requires a longer spin-up time for new team members because so much of it is written using custom functions instead of generic “batteries” from the language.

Parting thoughts

When starting a new project, ask yourself if you want to get something written quickly, or if you want to learn new things. If you want to learn new things, maybe checkout a language like Scheme.

If you’re interested in learning a Scheme I’d highly recommend you check out Racket. It’s got a ton of 3rd party libraries so you don’t have to write everything from scratch, and the documentation of them tends to be very high quality. Chicken Scheme’s pretty good too, with a good ecosystem of 3rd party libraries⁵ but I find the documentation of most libraries to be simultaneously comprehensive, maddening, and nearly useless. For example, every function listed with a sentence or two describing what it does, but each description is based on a pile of domain knowledge that people new to the library, or new to the language don’t have.

Post Script About The Parentheses

Whinging about Lisp’s parenthesis is a lot like being fatphobic. It’s claiming something is “bad” or “lesser” because you don’t like how it looks without any real understanding of why that particular person / thing is the way it is.

The only people who whinge about Lisp’s parentheses are people who don’t code Lisp. Not only that, but Scheme is so damn flexible that there are multiple implementations that don’t use parentheses. Wisp (Whitespace to Lisp: SRFI-119), for example, uses indentation levels like Python. The Readable Lisp S-expressions Project uses parentheses, indentation, and curlies and resembles C.

So it’s not just “yucking someone’s yum” because you don’t like how it looks, it’s also really ignorant because you don’t even need to use them.

To me, Lisp’s parentheses are little hugs that keep my codey thoughts safe and secure. They help Lisp to be a homoiconic language, and every decent editor makes them easy to work with, and helpful. So stop trying to get rid of my hugs!

SRFI: Scheme Request For Implementation. These represent a couple hundred implementations of different useful things (like hash tables). They tend to be written in a generic way that can either be used directly in any Scheme that adheres to the de facto standard called the Revised Report on the Algorithmic Language Scheme (RnRS). E.g. R5RS. Or can be easily ported. ↩︎
Most schemes do have a call-with-current-continuation function (abbreviated as call/cc) that allows you to exit a function early. However, there’s a huge difference between just returning the result of your calculations directly (ex.: return "foo") and calling a function that takes a function that then gets executed in order to get your result out, but also behaves differently based on how and when it’s called. ↩︎
I started with Common Lisp, but parts of it frustrated me, and at the time the community seemed essentially dead, and the library options (number of 3rd party batteries) was almost non-existent. It’s gotten much better since the introduction of the Quicklisp library manager. ↩︎
Yes, of course there are libraries that implement modern try / catch style exception handling. They’re just not “batteries” that are included by default. ↩︎
Unfortunately Chicken Scheme uses a centralized Subversion repository for sharing “eggs” (libraries). The process around this is so fucking obnoxious, and requires so much obscure hoop jumping that I’m not bothering to update the one library that I did submit. ↩︎

Feature Chats

Fri, 09 Aug 2024 00:00:00 -0400

Overview

A casual look a the power of discussing your side-project with like-minded friends.

Once Upon A Time

…there were two developers, who needed help staying on top of their team’s Pull Requests. One developer said “I shall write an app to help myself! I shall query the GitHub API and expose the things that matter in a way that works for my brain!”

They started pondering aloud how they would approach the problem, and soon the other developer said things like “ooh” and “cool” and “you could…”

But, the developers soon realized that while they both wanted to stay on top of their team’s work, they had very different priorities and needs. The second developer, having seen the value of the core idea, set off to make a very different app. Their parting was amicable. Two friends with different needs.

As the days unfolded, the developers would get together and chat as they munched upon their breakfast or lunch. They would discuss the problems they were working through, and features they were considering. Ideas, suggestions, and even warnings from hard-won experience were shared. Each developer cheering their friends successes, and helping them when things were difficult.

Recently

Those discussions branched into two different apps. Dachary made PR Focus, and I made DevGood, which I’ve yet to release. Simultaneously, I’ve been working on Backup Brain which is a completely unrelated Bookmark Manager. Dachary’s got a handful of unreleased iOS apps she’s been working on in the background too.

Yesterday Dachary was discussing how she’d implemented the upcoming ability to “Tag” Pull Requests in PR Focus. I’d already implemented tags¹ in Backup Brain and pointed out, that while she doesn’t need to address it in the initial version she will need to support the ability to rename tags, and have it change on all the PRs with that tag. She pointed out that that “just worked” because of how she’d designed her data model.

I realized that in my quest to not fall into the trap of using MongoDB as if it were a relational database, I’d gone too far and not used relations when I should have. I’d “painted myself into a corner” as it were.

This morning, as we munched on breakfast and she chatted about how close she was to finishing tag support, I realized that my situation was even worse. I want Backup Brain to autocomplete tag names as you type them in, but I can only do that efficiently with a centralized list of tags.

Insight

My tags problem is pretty trivial in the grand scheme of coding problems, but Dachary noticed the very non-trivial thing that surrounded it: our discussions.

Our apps have become so much better as a direct result of the discussions we’ve had. Sometimes it’s as simple as solving a problem by Rubber Ducking it with the other person. Sometimes we avoid issues entirely by describing what we were thinking of doing, and having the other person point out problems we hadn’t foreseen, or alternative approaches which would be way better. Sometimes the other person has hard experiences & perspectives that we don’t, because they’ve lived different lives & learned different things².

She noticed that it didn’t matter if the apps we were discussing were even remotely related. The same challenges come up again and again in wildly divergent codebases. She codes in Swift & Swift UI. I code in, well a lot of things, but usually Ruby and Rails. She’s working on user requested features for her PR Tracking app. I’m working on random stuff for a Bookmarking app, and yet we keep coming across places where the current work, or work that came up in discussions is relevant to what we’re working on today.

Takeaway

Being best friends with a developer you trust and live with is uncommon. We have a definite advantage over most in this regard, but that kind of arrangement isn’t required. What you need is a similarly minded geeky friend with projects of their own, someone who’d enjoy chatting about their geeky projects with you just as much as you’d enjoy chatting about yours with them.

Find someone you can hop on a call with over lunch & work through an idea. Set up weekly chats, or meet-ups. Talk about your code. Shoot the shit. Enjoy your friend, and help their project be great. Let them do the same for you. Allow yourself, and your friend to dig into whatever part of the discussion seems interesting. Drill down on “silly” programming details and questions. Allow yourself to be ignorant in front of them, and allow your friend to help explain things to you. Trust them to not think less of you for not knowing literally everything. Do the same for them.

It doesn’t matter if you code in the same language, framework or whatever. The only thing that matters is that you’ve both got projects you’re frequently working on.

So, go forth, find a friend, and chat! Make better apps. Become a better developer.

I’ve spent a lot of time thinking about, and hunting down existing academic research on “tagging” in knowledge managers. There’s some very cool research that’s been done on how people categorize and retrieve information, and how we can support that with tags & related techniques. ↩︎
It’s almost as if diverse perspectives within your team help make a better product that helps more people. Imagine a world where automatic soap dispensers worked for all the black people, and AI didn’t spout disproven racist medical advice to doctors! Gasp! this post & short video about Meredith Brousarrd’s book More Than a Glitch: confronting race, gender, and ability bias in Tech. ↩︎

Announcing Backup Brain

Tue, 23 Jul 2024 00:00:00 -0400

Table of Contents

Overview

I’ve just released a free self-hosted bookmarks manager called Backup Brain. I’m really proud of it, and I’d like to introduce it, and share some thoughts about it, and its future.

What Is Backup Brain?

Right now, Backup Brain is just a self-hosted Bookmarks manager, like Pinboard.in. I think it’s a little nicer looking¹, but I’m biased.

It has great search, and creates a “Reader View” style archive of every page you visit. That way you’ll always have the important information, even if the bookmarked page disappears; even if you can’t afford to pay for a service. You can download those archives as Markdown files too.

Being able to share a page of useful bookmarks is pretty important to me, but sometimes I bookmark things that are a little bit personal. I added support for private bookmarks, that you can only see when logged in, and instructions for setting up remote access if you want to host it locally.

To make adding bookmarks easier there are extensions for Chrome & Firefox, as well as a bookmarklet. The Helpers page has screenshots and more information.

The BackupBrain.app web site has a lot of documentation, including instructions on how to share an app on your local network with the wider world.

Bookmark Managers

If you’re not familiar with bookmarks managers, the basic idea is that the bookmarking tools in browsers are pretty crappy, and extremely limited. A bookmark manager is an app built specifically for helping you manage hundreds or thousands of bookmarks. More importantly, they have good tools for helping you find what you’re looking for in those large piles.

If you’re not frustrated by the bookmark management tools in your browser then you don’t need one.

Why Make It

First, you need to understand that - for me - bookmarks are a disability accommodation tool. I have an extremely bad memory. I need a tool that’ll help me find those really useful web pages I encountered, that I can’t remember enough to search for. I also need something to help me find useful pages that I completely forgot about the existence of.

When a friend is struggling to find information on some topic we both have an interest in, it makes me happy to be able to link them to a page of tagged bookmarks about it.

Right now I’ve got about 12,670 bookmarks on a wide swath of topics.

Pinboard Limitations

I’ve happily paid for Pinboard.in for years now, because it’s good service, and the guy behind seems to have no design to muck with it to make it more flashy, get more sales, or whatever. But there are two problems with Pinboard. The first is that he could keel over dead or just get sick of dealing with it at any time, and I don’t want to loose my bookmarks. Every time there’s a blip in Pinboard’s service I worry.

The second problem is that he doesn’t want to auto-renew subscriptions, but instead reminds users that their subscription is about to expire, and asks them to take an action. This is very considerate, and probably how most subscriptions should work, but it’s a problem when it intersects with my ADHD and my hatred of email. Twice now I have forgotten to renew within a month of my service running out. Given the fact that I use bookmarks constantly, you’d think this wouldn’t be able to happen. Unfortunately, there’s no visual distinction between a paid account and a free one. The only significant difference is that the paid account creates archives.

After a month of non-payment all your archives are deleted. This is totally reasonable, but it also means that twice now I’ve lost archives of pages that no longer exist. I don’t want there to be a third time.

A Desire For More

Even if there was some magical guarantee that Pinboard would remain, and I’d never loose my archives, there’s functionality I want that it doesn’t have, and will never get.

For example, on Mastodon you can “bookmark” a post. I want those bookmarks to show up in my bookmark manager. I could bookmark the page, but it’s more clicking to get to the post’s page to bookmark it, but that doesn’t really work when I’m using a mobile client, and I don’t think that treating it like any other web page is the best way to handle that.

What if my bookmark manager could silently ingest my Mastodon “bookmarks” in the background, archive them, and expose them to the search engine that makes it easy to find my web bookmarks.

Should You Try It?

It depends. Obviously, I’d only suggest it if you actually feel the need for a bookmark manager. If bookmarking things in the browser works fine for you then keep doing that.

If you do need a bookmarks manager, and like the idea of a self-hosted one then… maybe.

Current Features

At the time of writing (July 25, 2024) Backup Brain is at v1.2.0, and it’s been my “daily driver” for a while now.

I think it’s great, but I don’t want to mislead anyone about its current capabilities or limitations. For everyday bookmarking, and bookmark sharing it’s got everything you need.

At the same time there are some little features that haven’t made it in yet. For example, the tags management is pretty minimal. There’s no way to mass-rename a tag, or view a list of bookmarks that share two or more tags, and tag names don’t autocomplete when creating an new bookmark.

To get a good idea of the kinds of things that are still missing, as well as features coming up in the near-term, check out the GitHub issues for the project.

If you’d like to use Backup Brain, but there’s some missing feature that you can’t live without, please file a new ticket, or drop me a line on Mastodon.

Installation Concerns

I haven’t managed to containerize it yet, or put together any other “one-click install” solution. So, it requires you to follow a bunch of well-documented, installation instructions that assume a bit of general geekery and basic command line familiarity.

I would be ridiculously thankful for any help with this. Docker and I are not friends. I’d also love to get a Raspberry Pi image that people could load up with minimal geekery.

Geeks

If you’re looking for a bookmark manager you can tweak to match your brain, this one is written in Ruby on Rails, and it’s mostly open source.

“Mostly” being the restriction that you can only use it for non-commercial purposes. I’m not really thrilled with the trend of companies or individuals taking other people’s free labor, selling it, and never contributing even a fraction of the value back. Open source developers deserve better.

It is not currently my intent to offer Backup Brain as a paid service, but I am leaving that as an option for the future.

The Future

As noted in the section on why I made this, I intend to support background ingestion of bookmarks from a mastodon account (ticket here). I want to be able to edit archives. Ultimately, I want to build this into a place where you can store and find any useful thing you encounter in your regular computing. Important emails? Maybe. Special photos? Why not?

I intend to keep working on this for a very long time, even if I’m the only user. At the same time, I want to share this with others. I hope that other people will derive as much value from this as I have.

Summary

Backup Brain is a bookmark manager with dreams of becoming much more. It’s taken a lot of work, and I’m really proud of it, but it’s going to be a little bit before it’s easy for non-geeks to install it.

I’d love to hear from you on Mastodon if you install it or have any questions.

I haven’t been a designer for ages. I’m sure some of you could make it look better than it does. The mobile view definitely needs help. My focus has been on what you’ll see in a desktop app. If you’ve got design chops, and even a passing familiarity with Bootstrap, there’s an open ticket. I’d love some help. ↩︎

Using Org Mode With Hugo

Fri, 19 Jul 2024 00:00:00 -0400

Table of Contents

Overview

This post is for people who already understand why org-mode is the “greatest thing since sliced bread” & want to build a static web site with Hugo.

Hugo’s built-in org-mode support

Hugo supports org-mode files by default thanks to the go-org library. It will allow you to create blog posts with .org files and .md files. However I recommend that you don’t use this option.

go-org has the same problem that every non-Emacs implementation of org has. It doesn’t implement support for everything org-mode can do, and org-mode can do a lot. It’s mostly good, but mostly only gets you most of your needs, not all of them. It’s one of those situations where it seems good, until you start stumbling across little things that don’t work right or aren’t supported. The more you post, the more likely it is to frustrate you in the long run.

Ox-Hugo

I recommend you us ox-hugo. It’s an excellent org-mode exporter that takes your org-mode file, converts it to Hugo friendly Markdown with TOML frontmatter. It can be configured to use YAML frontmatter but you’ll probably never look at the generated file so I don’t know why you would.

Basic Usage

The idea is pretty simple. You have some org-mode files of blog posts you’re working on. When you’re ready, you tell ox-hugo to export them, and it generates Hugo-friendly Markdown files.

You can also have it create a blog post from a “subtree” of an org-mode file. That is to say “This heading and everything under it should be a blog post”.

You’ll want to keep your org-mode files in a directory other than Hugo’s content directory, because we don’t want it to even think about your org-mode files. We only want it to consider the Markdown files we generate.

At the root of my hugo site I have a proto_posts directory where I create all my new blog posts. It doesn’t matter what you call it, and it doesn’t matter if you use a directory structure inside of it. It doesn’t even matter if you have it in your hugo site. You could even keep all your writing in Denote or Org-roam collections.

Configuration

Because the org-mode files could be literally anywhere on your computer, you need to tell ox-hugo what directory to export to.

.dir-locals

If you’re writing them to a directory within your hugo folder like I am, then you can add a .dir-locals.el file at the root of your hugo folder with the following content.

((nil . ((org-hugo-base-dir . "~/path/to/weblog.masukomi.org/"))))

This is an especially nice way of handling it if you’re managing multiple sites. Each one can have its own .dir-locals.el file to make sure your proto_posts always end up in the correct content directory.

keyword

There are cases where using a .dir-locals file isn’t an option. For example, you might use Denote or Org-roam for all your writing and want to export to multiple blogs from that. In that case you’ll need to use a keyword in your org-mode metadata (frontmatter)

#+hugo_base_dir: ~/path/to/my/site

Helpful Bits & Info

Where the post goes

Most hugo sites are broken up into “sections”. Typically it’s one collection of “pages” that live at the top level. Things like your “about” page. The files for these typically live under content/

Usually there’s a collection of “posts” too. The posts are what we’re typically interacting with when we visit a blog and these live under content/post/

In order to control where your exported file goes we use the hugo_section keyword. Most of the time you’ll be creating a post, so most of the time it looks like this.

#+hugo_section: post

But if you needed a file at the top level you’d use this

#+hugo_section: /

It can be any folder name or even subtrees like post/journal/2024 depending on the theme you’re using for your Hugo site.

Frontmatter Helpers

ox-hugo tries really hard to not interfere with common org-mode metadata keywords. The official ox-hugo keywords are listed here. In practice, I suspect that most people will have some form of auto-generated metadata like I show below, so it’s pretty rare that you’ll have to think about frontmatter.

Fortunately for us ox-hugo’s creator gave emacs everything it’d need to populate the autocomplete with all the options. Just type #+hugo_ and look through the list.

Auto-generated metadata

Auto-generated metadata (frontmatter) is a massive time-saver. So the first thing I do when I open a new file for a blog post is to type hfm to invoke my “Hugo FrontMatter” snippet (using YASnippet of course).

This sets up all the frontmatter I need, & generates the date strings.

# -*- mode: snippet -*-
# name: hugo-frontmatter
# key: hfm
# --
#+author: masukomi
#+hugo_publishdate: `(format-time-string "%Y-%m-%dT%T%z")`
#+date: `(format-time-string "%Y-%m-%dT%T%z")`
#+hugo_auto_set_lastmod: t
#+filetags: $1
#+toc: headlines 3
#+hugo_draft: false
#+hugo_section: ${2:posts}
#+hugo_custom_front_matter: :summary "I NEED A SUMMARY"

Things to note about that snippet

There is no #+title: … line. This is because my process is such that whenever I open a new .org file for blogging it auto-populates with a name generated from the file name. If your process doesn’t do that, then add a #+title: $1 line above the #+author line, and be sure to increment the numbers after filetags and hugo_section

For those who don’t know the dollar-sign numbers in YASnippet are essentially fields you fill in and tab to the next one. Your cursor will jump through them in numerical order starting with 1.

I’ve set hugo_draft to false because of how I work.

The other thing to note is the #+toc: headlines 3 This is for ox-hugo’s table of contents generation which is arguably superior to the TOC generation that Hugo has built in. If you don’t want a table of contents on your post, just delete that line.

To be explicit, this is separate functionality from that provided by toc-org.

Image & Alt Text

All you need to do to insert an image is to create a file: link to something with a common image file extension like .jpg or .png. It’ll just do the right thing.

The problem with this is that it provides no alt-text for blind readers and you might want a descriptive title for the image.

To address these we use the ATTR_HTML keyword with :alt or :title respectively. These aren’t ox-hugo specific. They’re what you’d use if you had an org document that was going to ultimately be converted to HTML.

For example:

#+ATTR_HTML: :alt a cute black and white puppy being cradled in my lap
#+ATTR_HTML: :title our new puppy
[[file:/images/path/to/puppy.jpg]]

That would get converted to:

{{< figure src="/images/path/to/puppy.jpg" alt="a cute black and white puppy being cradled in my lap" title="our new puppy" >}}

ox-hugo is using Hugo’s figure shortcode, because Markdown doesn’t actually support alt tags, or titles

Note that, just like in normal Hugo Markdown, the path you use needs to be the path that will work on the final generated site. For example: the images on this site are under /images but in my hugo folder they’re under static/images/ Whenever I insert an image I have to use a /images/… path to make it work in the final rendered site.

I’m sure someone could combine some elisp and the hugo_base_dir info to enable the images to be displayed inline but I don’t really care.

My Hugo Image Snippet

I don’t like having to worry about unique image names. I always keep the images for a post in a dated folder that matches the post’s date. For example: this posts images are in a folder named /images/2024/07/19/

When I want to insert an image into the page I type himage to invoke the following snippet that generates the alt and title keywords + pre-populates the image url with a date based folder path.
```
# -*- mode: snippet -*-
# name: hugo-image
# key: himage
# --

#+ATTR_HTML: :alt $2
#+ATTR_HTML: :title
[[file:`(format-time-string "/images/%Y/%m/%d/")`$1]]
```
Note that the cursor starts inside the link path because I’ve usually got the image filename on my clipboard. I can then just paste, & tab over to start writing the alt text.

Most of the time I delete the title line.

Relative Link Helpers

Cross-referencing other pages on your site is pretty common. The problem that Hugo is solving with ref & relref shortcodes is that, without reading the frontmatter of the file you’re linking to, & pondering how Hugo will interpret it, you don’t know the final url of the page you’re linking to. For example: pages on this site are all prefaced with year, month, and date that the post was initially published, but that’s all calculated from the frontmatter during Hugo’s build process. All I know when writing is that it’s generated from a file called “my_relative_file.md” in the same content/post/ directory that the file I’m linking from will be in.

Shortcode handling is a little problematic in ox-hugo. See Shortcodes below. To create a relref link you’d have to write something like this.

@@hugo:[foo]({{< relref "my_relative_file.md" >}})@@
OR
[foo](@@hugo:{{< relref "my_relative_file.md" >}}@@)

I don’t like having to type that obnoxious line and there’s a reasonable chance I’ll make a typo or misremember something when writing the filename.

So, I’ve added a couple functions to my emacs config to make inserting a rel or relref link work just like inserting any other link.

Now I can

use C-c l to insert a link
choose or type ref: or relref:
hit return, and navigate to the path of the other file under hugo’s content directory.
select the file I want
enter a description.

When I export it will convert it to a markdown style link with the ref / relref shortcode for the url.

;; New link type for Org-Hugo internal links
(with-eval-after-load 'ox-hugo
  (org-link-set-parameters
   "relref"
   :complete (lambda ()
               (concat
                "relref:"
                (file-name-nondirectory (read-file-name "File: "))
                )
               )

   :export (lambda (path description backend)
             (format "[%s]({{< relref %s >}})" description path  )
        )
   )

  (org-link-set-parameters
   "ref"
   :complete (lambda ()
               (concat
                "ref:"
                (file-name-nondirectory (read-file-name "File: "))
                )
               )

   :export (lambda (path description backend)
             (format "[%s]({{< ref %s >}})" description path  )
        )
   )

)

Note that there is no :follow function set. Clicking on these links in org-mode won’t go anywhere. This is intentional because the link is going to the markdown file used when the site is generated, but I don’t know where the org-mode file used to generate that markdown file is, and that is the file you’d want to open.

I’ve considered changing rel: & relref: to hugorel: & hugorelref: but it’s not currently interfering with anything. If you do change it to something else be sure that the initial string and the text after concat match each other.

Things to watch out for

Frontmatter

I expected that it’d just convert all the org-mode metadata / frontmatter, but it defaults to only converting a common subset of it, that it knows Hugo will want. Here’s a table documenting those.

I assume that the thinking is that org-mode files can have a lot of frontmatter that has nothing to do with your eventual blog-post.

There are two ways to solve this. For most people who need a non-standard keyword you’ll just want to add this to your org mode frontmatter. You’d just change :key and "value" to whatever hugo frontmatter key & value you want.

#+hugo_custom_front_matter: :key "value"

If you’re converting subtrees of a larger document into individual posts then you can use Properties. This is documented in the Org meta-data to Hugo front-matter post.

summary keyword

ox-hugo doesn’t pass on the summary keyword which many Hugo themes use to display a short summary under your posts. Without this, most Hugo themes will just use the first bit of text in the post. If you use Tables of Contents, like I do in most of my posts, then that’s going to produce terrible summaries.

tags

offically you should use #+hugo_tags: tag_a tag_b but I’ve been using #+filetags and that converts just fine.

Shortcodes

Using Them

ox-hugo is good, but Hugo’s shortcodes are a problem because {{< … >}} and {{% … %}} are not legal Org syntax.¹

ox-hugo has multiple ways of addressing this. Most blog posts don’t really use shortcodes much. The most you’ll probably want on a semi-regular basis is something quick and inline rather than a multi-line block you can use these handy escapes.
```
@@hugo:..@@ <-- for Hugo templating stuff
@@md:..@@   <-- for raw Markdown stuff
@@html:..@@ <-- for raw HTML stuff
```
For example, if I wanted to create a relref link i could say
```
@@hugo:[foo]({{< relref "my_relative_file.md" >}})@@
OR
[foo](@@hugo:{{< relref "my_relative_file.md" >}}@@)
```
Basically it’s saying “Just let hugo deal with whatever’s in here.”

Because creating links to other posts on your site is a pretty common thing I’ve created a couple helper functions to make this less prone to typos & more natural feeling to org-mode users. See Relative Link Helpers.

Blogging About Shortcodes

Documenting the markup of a language without invoking the markup of the language is a pain in most (all?) markup languages. In this case we’re actually dealing with two layers of this. We don’t want to have the shortcodes invoked in the exported file, and we don’t want any org-mode syntax (like asterisks for bolding) to be invoked in the org-mode file.

Chris Liatas discovered the simple solution of sticking a comment inside the shortcode.

So everywhere in this document where you see something like {{< … >}} or {{% … %}}

What I’ve actually typed in the original is two curlies, the < or %, then /* … */, and then the closing characters for the shortcode.

org-entities

Org-mode has built in support for laTex style special characters. John Cook has a nice blog post that helps explain why these are potentially useful. As a simple example \ast represents an asterisk.

In writing this post I discovered that ox-hugo does not convert them. So you end up with a literal \ast in your markdown. I’ve filed a bug documenting the problem. If you’re reading at some point after July 2024, and want to use org-entities you should check the status of that ticket.

I don’t really understand why this is illegal syntax since org-mode doesn’t seem to complain when I enter them but it doesn’t really matter. What matters is that they give ox-hugo headaches. ↩︎

Amazon Bricked My Kindle

Thu, 18 Jul 2024 00:00:00 -0400

Table of Contents

Overview

Yesterday I discovered that Amazon had decreed that my Kindle e-ink device was too old. This post is my 🧠-dump of a intensive afternoon & evening of researching what to replace it with.

Current Status

My Kindle

It can no longer sync purchases.
It can no longer access the Kindle Book store.
Contrary to the claims in the photograph above, new books can not be delivered directly to this kindle.
It no longer shows up as a USB device when plugged in to a computer.
- Thus you cannot “Download & Transfer via USB”. When you choose that option it says “You do not have any compatible devices registered for this content. Buy a Kindle or get the free Kindle reading app.”
- Thus Calibre can’t interact with it.

It can read the books that are already loaded on it, and it still receives new advertisements to display at me, because of course it fucking does.

As far as I can tell there is no reason it needed to be bricked other than greed.

Me

Pissed at Amazon. Increasingly so as I learned more.
Still want an e-ink tool to read books on. I have a Remarkable 2 tablet, but while it can display eBook format books it can’t run the Kindle app and thus can’t get around the DRM on Kindle eBooks
Not afraid of a soldering iron if I’ve got decent instructions
Really dislike e-readers without physical buttons to change pages.

Lessons Learned

A quick aside

Amazon has a tech called “Immersive Reading”. When you have purchased the Kindle and Audible copies of the same book, and that book is “Whispersync Enabled” You can listen to the Voice actor(s) narrating the story while the kindle software simultaneously highlights the words on the page.

It’s great for language learning, but also great for my ADHD because it gives me just enough additional stimulation that I don’t go trying to scroll social media.

There is only one company that makes e-ink hardware that supports Immersive Reading, and it’s not Amazon. It’s Boox.

Open Hardware

The Open Book

The Open Book project got a bunch of press a while back because it’s a decently documented DIY kit for building an e-ink e-reader. However it’s not a viable contender because

The canonical format for books is plain text with the book title on the first line, OR plain text plus some front matter and some ASCII control codes for chapter breaks and formatting.

In other words, it can’t read ANY of the eBook formats.

EPub-InkPlate

EPub-InkPlate is a project that does support ePub on InkPlate hardware. However the documentation is crap, and assumes a ridiculous amount of domain knowledge. I have no idea how to install it or how much custom twiddling is required to make it work.

It’s all Irrelevant

Even if there was an open hardware device that was physically identical to a modern Kindle it couldn’t read their DRM encrypted files.

DRM

For those who don’t know, Kindle ebooks are all encrypted with DRM. What most people don’t realize is that Amazon can, and does, sometimes remove books you’ve purchased from the marketplace and devices that have downloaded them. Additionally some kindle devices will delete all the files if the device can’t connect to the server within a pre-defined time window. For example, if you turn off wifi to conserve an old battery.

When you buy a kindle ebook you’re not technically “buying” the book. You’re purchasing a license to read the book which can be revoked at any time.

Unfortunately it appears that Calibre can’t strip the new DRM from their KFX (Kindle 10) format, as of July 2024.¹ The only tool I know of that can remove KFX DRM is Leawo Prof. DRM eBook Converter. However, the .epub file it generates lacks all the formatting. It’s just a big long piece of plain text that you’ll never want to actually read. Epubor Ultimate can also strip the DRM, but its file also seems to also lack formatting.²

Historically I would open up Calibre every now and then, import my recently purchased Kindle books, strip the DRM and have a backup so that Amazon couldn’t remove it. I could then load books non-kindle e-books that I’d purchased elsewhere onto my kindle over USB.

The combination of DRM that Calibre can’t strip, & the fact that My kindle no longer acts as a USB device you can connect to means that I am prevented from loading legally obtained books onto my kindle. This includes ones purchased from amazon with DRM left intact.

In the wise words of Cory Doctorow, “DRM Broke its promise”

Long Term Support

Amazon removes support for devices after 10 years. Kobo removes support after about 8. This seems a ridiculously long time in the world of consumer electronics, but you have to understand that there’s no reason an old e-reader can’t keep working just as well as it did on it’s first day, so long as it’s got a functional battery.

For context, the last update to the ePub format was updated was 13 years ago in 2011 & e-ink devices can, and do receive software updates to support new formats. The most recent kindle format is KFX which was released 9 years ago in 2015. My kindle has happily opened many Amazon purchased books since then.

There’s no good reason ereader devices shouldn’t be supported long after they’re sold.

Alternatives

Kobo

The Kobo Libra Colour is a beautiful device that has real buttons to turn pages. None of the currently available Kindle e-readers have buttons.

The Libra Colour is well reviewed, but it has the same problem all the other Kobo’s have. The Kobo store has a notably worse selection than Amazons. Their audio book selection is - comparably - even worse. Since it’s an Amazon competitor, there is no Kindle app that you can run on it.

They don’t have an equivalent to “Immersive Reading” in their e-ink devices or phone apps, and it wouldn’t matter if they did because their audiobook selection is much worse than Audible’s.

Them having a worse store is because Amazon has a functional monopoly on the publishing industry.

They also remove support for old devices after roughly 8 years vs. Amazon’s 10. It’s unclear if they brick devices after they’re too old like amazon does.

So, it doesn’t matter how good the Kobo software is. Unless you have “money to burn” and can afford a an Amazon device, and a Kobo device, it’s a worse choice as a consumer.

Boox

As far as I can tell, Boox is the only manufacturer who’s e-ink devices support “Immersive Reading”. I don’t know why. They’re not doing anything special to enable this. It’s just an Android e-Ink device running the standard Android Kindle software.

In the case of the Poke5 device they’re using the exact same screen as some Kindle devices so it’s not an issue of refresh rate.

Of Boox’s devices the Poke5 is the only one that’s directly comparable to a Kindle e-reader. The rest are significantly more expensive because they’re intended to do significantly more than just read eBooks.

Because it’s running Android it can run the Kindle software, the Kobo software, and apps to download eBooks from your library.

However, there are some issues, and one of them is a deal-breaker.

Despite using the same screen the hardware is objectively worse than the Kindle Paperwhite when it comes to the task of being an eReader. Lots of minor ways that add up. The most notable for me was that the layers of material they place on top of the display result in a visibly worse contrast ratio.
Boox devices run a custom flavor of Android, and they only guarantee support for a device for 3 years. Eventually, they’ll stop updating it, and it won’t be able to get updates from modern apps in the Google Play store. It’s just a question of “when” and there’s no way to predict the answer.

There’s also the fact that my library has a horrible selection of e-books³ and an almost non-existent selection of audio books. I’ve literally never found the book i was looking for when searching their options. As such, it’s not worth considering.

Nook

Tied to a struggling book store (Barnes & Noble), notably more expensive than comparable Kobos, the Boox Poke5 (despite doing much less), and the Kindle Paperwhite. Even a Refurbished Nook GlowLight Plus costs more than a Paperwhite. Like the Kobo, B&N’s store isn’t as good as Amazon’s because monopolies suck & DRM is a pain in everyone’s ass, except the monopoly’s. Like the Kobo, it also can’t run a Kindle app.

The Nook GlowLight 4 Plus does have buttons, which is a significant differentiator, and it does have a headphone jack.

Here’s a YouTube review from someone who is a fan of Barnes & Noble (~14 min), and overall seems to like the hardware, but titled his review “Nook GlowLight 4 Plus Review: Premium & Infuriating” because of software issues.

For example the top half of the home screen shows you books from your library, and the bottom half shows you “recommendations”. I loathe the similar behavior in Apple’s “Book” app on the iPad.

Unfortunately I see no good reason for anyone to buy a Nook right now, other than sheer hatred of Amazon, or physical limitations that require you to have physical buttons.

Conclusion

I don’t want to buy an ereader that’s going to be abandoned in 3 years.
There’s no realistic Open Hardware option & it couldn’t read any book I purchased even if there was one, because no-one’s cracked KFX’s encryption.
I can’t afford 2 devices, and I don’t want to limit my options for what I can read before I’ve even bought the device.

It’s all a compromise…a bad compromise.

The Boox is arguably a better choice with regards to what it can do, but I don’t want to have to deal with this crap again in 3+ years because they’ve dropped support. The Poke5 provides a worse reading experience than the Paperwhite because of the slightly worse hardware & backlighting, and it still doesn’t have any fucking buttons, and it’s not waterproof. I don’t plan on using it near water but I have ADHD which means I have motor control issues and spill drinks more often than most people.

The Kobo Libra Colour is the physical device I’d love to use, but the store’s worse, especially when it comes to audiobooks & there’s no equivalent of “Immersive Reading” with their e-Ink devices or phone apps.

I’m going to keep buying media from Amazon because I don’t have an alternative with the books I want (especially the audiobooks) & I really want to be able to keep using “Immersive Reading”.

So, I bought a Kindle Paperwhite, with a slight discount because it just happened to be “Prime Day”. I couldn’t buy one “Without Lockscreen Ads” because those were “sold out”. I’m honestly wondering if they ever have any in stock.

I’ll have to pay $20 more to get rid of the stupid ads. There was literally no Kindle reader I could buy that had physical buttons.

While I don’t want to, I can go without “Immersive Reading” on an e-ink screen, because when I use it I’m not focusing as hard on the words & “reading” so much as following the moving highlight to satisfy my stupid ADHD. I’ll compromise and use my phone when I want that.

Sadly, the new Paperwhite is wider than my bricked kindle, so I can’t use my beloved DodoCase cover and they don’t make Kindle covers anymore.

My Beloved DodoCase cover.

2 Month Update

I’ve read at least 26 books since writing this post. I regret buying the Kindle Paperwhite instead of the Kobo Libra Color.

The touch screen is obnoxious. I can’t count the number of times I’ve tried to swipe back and it’s gone forward.
“Whispersync” has not been available on any of those 26 books despite most of them being from very popular series. I’m pretty annoyed about this as it was one of the main reasons I bought the kindle.
The official case has an uncomfortably sharp edge if you hold them with a finger under the bottom edge to support it.
The power button is exactly where my finger goes when trying to support it, so even if i find a replacement case it’ll have an uncomfortable hole or bump in a bad location.
The syncing between audio book and ebook is completely useless if you’ve dared to listen to / read the book before. It syncs the devices to seemingly random places that are always wrong. The only solution I’ve found is to mark the audio book as read, and reset it to the very beginning of the book. If you do this before you start rereading you’ll be ok. Probably.
There are two different menus hidden at the top.
Some preferences are hidden in weird places

The only thing i like about it versus the one they bricked is that it has a nicely backlit screen.

according to the official thread on this topic

Some books that Amazon always delivers with the strongest encryption may not work when downloaded using these programs, however no other method is likely to work for those books anyway.

The newer Kindle for PC app available in the app store for Windows 11 and the latest Kindle for Mac app (7.0 and later) cannot be used to download usable books.

↩︎
I can’t actually tell for sure if Epubor is loosing all the formatting or not because it will only allow me to see the first half of one random page of the book without paying. It claims you can see 20% of the book without paying but that’s a lie. I’ve tried two books and it seems like it’s loosing the formatting. ↩︎
Libraries are absolutely screwed when it comes to ebooks & digital audiobooks. They pay significantly more for them than they do for a paper copy & they can only lend them out a specific number of times, or for a specific time period before they have to pay again. ↩︎

TTRPG Archetype Worksheets

Fri, 31 May 2024 00:00:00 -0400

Table of Contents

Overview

My game’s pretty close to public playtestability. That means I need to put together some character Archetypes.¹ In order to do this I’ve put together an internal worksheet for the creation of classes to make sure I remember to include all the critical bits for each one.

I’ve never heard anyone talk about using this approach but I find it invaluable. I’m going to share a couple thoughts about what I’ve learned & go over my current one as an example.

High Level Thoughts

From my experience, an internal Archetype/Class worksheets should:

guide your 🧠 in breaking down a vague Archetype idea into the game relevant sub-sections
track what common skills / tags / whatever you’ve used in this Archetype in a way that makes it easy to flip through the full collection & go “oh, damn, i’ve got way too much emphasis on fighting” (or whatever)² AND “wow, I never use skill X. Maybe I can drop it.”

When using these it’s important that every time you revise your rules around character creation you check your Archetype worksheet & make any applicable changes.

Whenever you update the worksheet, take an Archetype you’re especially familiar with and re-write it on/in the new worksheet. I frequently find that something that’s important to me about that Archetype simply doesn’t have a place anymore, or its delivery has to be changed in a meaningful way that I may or may not like.

This is a form of QA testing & playtesting for your character creation rules. If i can’t describe an Archetype that fits well with the rules then either how we describe Archetypes has to change, or our character creation rules have to change.

Obviously, add a clear version number to your worksheets / character sheets / whatever. Otherwise you can make a small change & then find yourself using an old one and wondering why things feel off. It wouldn’t be the first time I’ve left a TODO item to make a change I’d already made because I was looking at an old sheet.

My Sheets

Custom Remarkable 2 Notebooks

(see the image at the top)

I took a worksheet, and squeezed it down to the roughly A5 size of the Remarkable 2’s screen. You can see the result in the first photo. The lack of writing space was a problem, but more importantly it’s a ton of annoying work to put together a PDF with hyperlinked navigation back and forth between pages & the table of contents. I have absolutely no desire to go through it again every time I change the worksheet. So, even if it had a full A4 or Letter sized screen, I still wouldn’t bother. Paper’s just easier.

What I would advise is printing out 1 sheet after you make a revision. Just one. Then fill it out. You’ll probably go “Oh, crap, that… I need a thing here”. Edit it. Print 1. Fill it out again. Only print more after you’ve successfully used one and not wanted to change it should you allow yourself to print more.

My Current Sheet

I’ve put the version number right there at the top. I used to hide them down at the bottom in small print on my character sheets, but then I’d forget to update the number when I updated the character sheet. Now my version numbers live clearly at the top of every page for all the internal versions.

On the right I’ve got all my game’s current skills listed with a little dot beside each one. As I’m filling out the sheet I incorporate skills into the questions (Mazes Style). Every time I do, I fill in the dot next to the one I just used.

Each Archetype has a core Aspect (think FATE) & a handful of other Character Aspects people choose via leading questions.

Like Skills, character aspects have a place on the right. This is the most condensed form of “what this Archetype is about?” This is good because it helps keep me honest. “Does this Archetype actually mechanically provide what it describes?” It’s also an easy way to flip through your created Archetypes and see if there’s a flavor of character you want but haven’t offered.

FATE style aspects can be “all over the place” so there’s no point in trying to have a picklist.

You may have noticed the dots next to the Character aspects. These are “note to self” almost for future character sheets. In the same way that many FitD playbooks have you check off character features I like the idea of checking off what Aspects & Skills you’re choosing as you work through an Archetype’s character creation questions.

It’s not good though. I don’t have playbooks. All of this just needs to be transferred to the character sheet which is completely different (more traditional). In theory I can use this when making a new character. In practice I won’t. I’ll just write things directly into the character sheet & that’s what I expect players to do.

So, mostly it’s me not wanting to let go of an idea, BUT this is an INTERNAL sheet. It’s just for me. It’s OK to leave a little chaff on your internal stuff if you recognize why you’re doing it.

And that brings me to the headings of each section of the main page. These are the briefest of hints to myself. They would be utterly useless to anyone I handed it to, but that’s OK. I have written guidelines for what should go into an Archetype. This is my worksheet for me. Using personal shorthand is fine.

Tools

These worksheets & my character sheets were created in Omnigraffle which is a glorious app you should absolutely use. It’s designed for flow charts & similar infographics, but it’s great at any form of organized information display. macOS and iPadOS only.

When I make form fillable things for players, or hyperlinked PDF “notebooks” for the Remarkable I use Wondershare PDF Element which is a good app that keeps getting regular and meaningful updates. Windows, macOS, iOS, Android. I’m not in love with it like Omnigraffle, but it’s good, and I’d suggest giving it a try if you need something like this. There are lots of tutorial videos for how to do specific things too.

A call to action

If you use a technique like this, please share it. I think we don’t talk enough about how we go about game creation and the tools that work for us.

If this has given you thoughts or ideas, please let me know. My TTRPG Mastodon account is probably best, but email works too ( masukomi@masukomi.org ).

Also, please let me know if you found any value in this post (Fediverse / email / courier pigeon). Even just a “thanks for that”. It kinda feels like I’m yelling into the void on this blog. 😉

: functionally my Archetypes are “classes”, but in implementation they’re somewhere between Mazes, & Mutant Year Zero. ↩︎
: I firmly believe that if your common skills / tags / whatever are all roughly equally useful they should be used roughly equally. If they’re not you’ve either made unbalanced defaults or you’ve overestimated the value of the ones that didn’t get much attention. This may be a red flag that your current rules aren’t emphasizing something you felt was important, or that the game has changed in ways that should make you step back and reconsider what you’re making. ↩︎

Lessons Learned While Making My Game

Sat, 25 May 2024 00:00:00 -0400

Table of Contents

Overview

I’ve been working on a Tabletop Role Playing Game (TTRPG) for years now. It’s been a very educational experience, and I wanted to share some of the non-obvious lessons about game design that I’ve learned along the way.

There’s a lot of stuff here, and many examples. Please skip anything you already know, or isn’t interesting to you. This as a skatter-shot of random learnings, not a homework assignment. 😉

🙇‍♀️ Disclaimer: this could really use a good editing pass, but after writing so much I needed a break. I’d rather you have it unedited then have it sit on my computer for months.

Background

Before we dig into this, there are some things you need to know about me in order to understand the context I’m coming from.

I’m a “frustration driven developer”. Using a thing with obvious flaws drives me buggy and makes me want to fix it.
I love game mechanics.
I love reading other people’s RPGs and learning how they approached different gaming problems.
I’m absolutely not interested in making “a better D&D”.
I’m only mediocre at creating settings.

I’ve been working on this game for years, not because I’m polishing my “perfect” game. It’s taken so long, because I’ve learned so much along the way, and had to restart from scratch so many times. It doesn’t help that there are so many wonderful games out there that made me feel like “yes! like that!” and want to throw out whatever core mechanic I had.

The Big Three (+1) Questions

Jared Sorenson is credited with “The Big Three Questions”

What Is your Game About?
How Does it Go about That?
What Behaviors does it reward and/or encourage?

The +1 question is “How do you make that fun?” I don’t know who added it.

Search for his name and “The Big Three Questions” and you’ll find plenty of details about using them. I think that having answers to all of those is critical to designing a good game. The +1 question is very subjective. At the same time I believe that it’s really important to have a strong opinion on it while designing.

It’s important to have answers to The Big Three Questions as you set out. That answer may be just a strong feeling, a specific direction to explore, but it needs to be something.

What’s Your Game About?

There are many different people advising that it’s important to know what your game is trying to be, or what kind of stories it’s trying to tell. They’re right, but I have a more practical take on why.

What your game cares about, and the kind of experience it’s trying to provide, can not be delivered with a core mechanic that doesn’t support that.

If you don’t know what kind of stories you’re trying to tell with your game then you should really pause and ask yourself why you’re making one.

If you just don’t like the way your current game handles something, then just homebrew a solution for that. You don’t need to make a whole game.

In my mind there are two reasons to make a new game:

I want to tell a particular story that no-one else is telling.
I want a game with a particular perspective and/or vibe that I can’t get elsewhere, and can’t achieve by simply creating a new setting.

A lot of folks keep wanting to make new “generic systems” which can tell “any” kind of story. Please, don’t. We have enough¹, and more importantly every well designed game that’s trying to tell a particular kind of story with a particular vibe, is going to do a radically better job than a generic game system used to do the same thing.

Core Mechanics Supporting the Story:

Powered By the Apocalypse (PbtA) games care about emphasizing significant moments, and complicating characters lives in interesting ways. It’s one of the best examples of mechanics clearly supporting the story.

PbtA games specifically don’t care about any decisions your characters make that don’t directly contribute to the type of story they’re going to tell. You only roll if there’s an applicable Move². If there’s no move, you don’t need to roll. If there’s no move, the game doesn’t consider what you’re doing to be important to its goals.

There are generally only 3 outcomes too: success, success with complication, or failure, and you’re way more likely to get a complicated success than a simple success. This is the game saying that it doesn’t care a lot about simple success or failure, but that it likes stories with complicated, and messy progress.

If you don’t know that “complicated, and messy progress” is what you want, you can’t make a core mechanic that supports that, and your game will only feel “right” if you lucked out in your initial choice.

PbtA games only have story supporting mechanics. They don’t have mini-games. They don’t generally have much in the way of sub-systems. They not only have story supporting mechanics, they don’t tend to have any mechanics that don’t directly support the story. This is what we should all be striving for. Obviously some games need more complexity, and there’s nothing inherently wrong with having sub-systems, but we need to focus on throwing out everything that we can that isn’t absolutely necessary to tell the stories we want to tell.

That, but with a twist

Sometimes you love a game, but it’s fails to do something that’s important to you.

The core mechanic of Ironsworn, and by extension Starforged, tells us that Shawn Tomkin wasn’t satisfied with the simple successes and failures of PbtA. It tells us that he likes it when a story has the occasional dramatic successes and failures, but that he still likes “moves”. So, he came up with a core mechanic that combined all of that.

If that was all Sean cared about it could have just been a homebrew rolling variant with guidelines for handling critical success and failure with the existing moves. Fortunately for us, he had other things to say too.

No, less.

A common problem of new game designers is the desire to put ALL of their ideas into one place. Even if your ideas are all great, it’s rarely a good idea to try and combine them all in one place.

I heard someone on a podcast say something like “your first game is five games”. I think that’s true, and a lot of the time I think that’s because we have five games worth of ideas that we’re trying to shove into one game.

Personal Example

I hate the idea that magic users can bend reality with no cost or consequences to doing so. I think that altering reality should hurt. It should drain you. I think that sometimes, casting a spell should go horribly wrong in unpredictable ways³.

It’s not hard to address all of those. You take stress / harm when you cast. You roll on a random table when you have a critical failure, and something bad happens to you or your friends⁴.

As much as I loved that, I ultimately had to throw most of it out, because I’m not trying to tell a gritty story about powerful magics, and violent high-magic encounters. The only part that’s survived is the idea that casting spells is mentally draining.

It’s not about that.

Maybe this is a me problem, but each iteration of my game has changed, refined, and/or refocused what the game was about.

When I started working on my game I was enamored with ICRPG. It was just going to be a hack for the magic system. But, the more I wrote, the more I realized that while ICRPG is a wonderful game, with lots to love, it’s not the kind of story that I want to spend countless hours imagining myself in.

I said above that it’s important to have answers to The Big Three Questions as you set out, but you need to allow them to change. There will likely come a point where you’ve implemented a good solution to one of them, try it out and realize that you don’t actually like how it effects things.

A Personal Aside

Years ago I read some Banana Yoshimoto books, that absolutely changed me. Her works are fascinating to me because they’re rarely about anything, and yet you keep turning the page to see what happens next. The ones I read were slice-of-life stories about completely normal people having normal lives, with the tiniest hint of magic at work in the world.

Her books are like the Matrix: “Unfortunately, no one can be told what the Matrix is. You have to see it for yourself.”

If you’re interested in creating a game like this, or a “cozy witchcore”, you should know that Monte Cook Games is currently (May 2024) working on a book specifically about helping you create those kind of stories. It’s called “It’s Only Magic”, and I’m confident it’ll be useful even if you don’t care about the Cypher System.

It’s not for them

When most people write a game they try and keep other people in mind. Don’t. Obviously the final product needs to be something that other people can understand but it doesn’t need to be something they like. The more you try and cater to what other people enjoy, the less interesting and compelling your game will be.

The best thing that happened during the creation of my game was sitting myself down and saying “Fuck that. What do I want?” I intentionally made an incredibly selfish wishlist of things that would be in an ideal game for me. For example, I wanted cards related to character abilities and items, because I have an ADHD brain, and fiddling with a handful of cards with pretty pictures helps me to focus.

It didn’t matter that cards were way more work & expense, or that they’d radically increase the cost & logistics of a game. What mattered was that it was something that I personally cared a lot about, regardless of other people’s feelings on the matter. What mattered is that this list of selfish selfish desires transformed the creative act of game design. I stopped compromising with non-existent people who i didn’t care about. I started making something that would bring me joy. I hope it brings other’s joy too, but the odds of it being particularly memorable are pretty low if it’s filled with compromises.

I’m pretty sure cards won’t be in the final game, but that’s ok. Most of my wishlist items won’t be. Like I said before, you can’t have everything you want in one game. I did try though, and the act of trying to have important things that fit on a card that was mostly picture introduced a critical constraint.

Embrace Constraints

It’s not just that no-one wants to play a game with 50,000 metaphorical levers to pull. It’s not that simpler is somehow better. Constraints focus efforts & keep us on track.

They don’t even have to be topical constraints. For example: “The core rules will fit into 30 pages.” or “There will be no more than 4 pages of spells.” These are great constraints. There’s nothing meaningful about those numbers, but they force certain design decisions. For example, limiting spells to four pages means that either you make a game with a bunch of spells with little-to-nothing in the way of description, or you make one with a very limited but very cool selection of spells.

Topical constraints can be good too though. In ICRPG, for example, you can carry ten items. That’s it. That little constraint means you no longer have a monk walking around carrying a hundred items like the Junk Lady from Labryinth and claiming they can dodge incoming arrows.

Let’s be real, no-one tracks the weight and volume of every item their character picks up.

Mausritter took this an additional step, and elegantly accounted for the size or weight of objects by giving you physical cut-outs that you have to fit onto a grid on your character sheet. If you don’t have space, you can’t carry it.

Mauseritter’s inventory constraints tell us that having more things isn’t important, or helpful, to solving the problems you’ll encounter. They way they’re physically implemented, tells us that this is a came that cares about cute little ideas, not nitty-gritty-details.

A game with specific constraints is expressing its opinion about what’s important.

Nothing’s set in stone.

Constraints are great, and wonderful, but sticking to them too rigidly can really hurt too. Maybe you start out trying to write a game that’ll fit in under 30 pages, but along the way you realize you no matter how much you edit away, you can’t convey some of the most critical pieces without more space. That’s fine. Maybe you modify the constraint to be “everything but X in 30 pages”. Maybe you say “30 pages, before layout and images.” Alternately, maybe you realize that you were wrong, and that you’d be doing the game a disservice by restricting the page count so severely.

Trying to work within constraints forces interesting and meaningful game design decisions. It’s valuable even if you learn that that constraint hurts your end goal. Now you know that it’s something important to avoid.

It’s all about the character sheet.

The Character Sheet is the ultimate constraint of your game, because as countless designers have learned, “If it’s not on your character sheet, it doesn’t exist.” There’s too much going on and players will forget and/or ignore anything that’s not staring them in the face.

Needful Things

Your character sheet should provide everything a player needs to take action on their turn. More specifically, your character sheet should answer the question of “what are my options?”

There are two levels to this. The first is “What are the things I know about my character that are actionable?” The second is “What mechanisms does the game provide for me to leverage those?”

Practical Example

I contend that this sheet from FATE Accelerated succeeds on the first, but fails on the second. Further, I think there’s space to fix that.

It tells us all the important things about our character, and thus answers the first question. It also has some minimal bookkeeping items (refresh, character name, etc) that don’t help us in the moment, but that’s pretty reasonable.

Looking at this though, a new player doesn’t know that at a high level there are only four “Actions” they can perform:

create an advantage
overcome
attack
defend

It’s damn hard to “sneak” up and “Attack” someone in the middle of an empty field who’s staring directly at you, but it might be pretty easy to act “Sneaky” with them watching you in order to “create an advantage” for someone else.

It’s really important that new players know this when its their turn, but for the GM to be able to set a difficulty for the roll, but also to help flesh out the shared narrative space of everyone at the table.

There’s enough space at the bottom of that sheet for 1 line that says “Turn Actions” and then lists those four choices with a their helpful icons. Or maybe you little flow-chart arrows to guide players through the things they need to consider on their turn. Like first you choose an action, and then follow an arrow that leads you to choose an approach.

Make the character sheet first

The more I iterated on my game, the more I transitioned to a Character Sheet Driven Development (CSDD 😉) process.

With each restart I’d get an idea for what I wanted, then try to shove it all onto the character sheet. This inevitably fails, so then I have to ask myself “which of these things really matters?” Do I need attributes and skills? Do I need to list all the skills? Do I even need skills? Can I maybe get rid of one of those attributes?

I firmly believe that games are always better when their creators have removed every piece of mechanical crap that isn’t necessary to telling the kind of story they want. If you take a Character Sheet Driven Development Process, and you agree that no-one wants to have to reference the book, then you are severely constrained in the number of systems your game can have.

Modify it through play

Make your sheet, define some rules, start playing (see below). Pay attention to what’s missing or confusing on the sheet. Mark up your character sheets to indicate changes as you play. Write in the additional info you wish was there. Next time you sit down to work on it, you’ll have a pre-made list of items with (🤞) all the context you need.

This is inevitably going to have follow-on effects. For example, I use different shapes around things to indicate if it’s a die you roll, or a counter, etc. At one point I’d managed to fit a small visual “key” on the page, but then some change meant I no longer had space for it, but I’m ok with putting reference things on the back of the sheet, so I moved it there.

Later on I came to the conclusion that rolling to see if your shield absorbed any additional damage felt like unnecessary faffing about, especially since my game isn’t even about going and getting into fights. I was able to remove some bits and bring it back.

If you keep needing to look up things that aren’t on the sheet, then your game is telling you you’re either missing critical information, or maybe you don’t need that additional stuff.

Things to keep in mind

In my mind there are a few critical things to keep in mind when putting together your character sheet. I should note that I used to be a Graphic Designer, so there’s a fair amount of hard learned lessons behind these thoughts.

The more space you devote to something, the more important it becomes in the player’s minds.
Visual Style matters
If it doesn’t fit, make space, or throw it out.
Your character sheet effects if people want to play your game.
Keep your old sheets.

Visual Style Matters

On the Left we have one of Dyson Logos’ takes on a D&D character sheet. On the Right we have the character sheet from Heroes & Hardships⁵. I’m not trying to pick on H&H, but if you covered up any game name, put these two in front of me, and asked me which game I wanted to play it’d be the one on the left 100% of the time.

It’s fine if you have no visual design skills, and or work with something ugly and spreadsheet-like during game creation. Before it reaches the table though, it must convey tone & help me to know what this game is about. This includes the playtest table. It doesn’t have to be beautiful, but it needs to be better than a spreadsheet.

Don’t make interacting with playtest materials feel like work.

Do I want to play THAT?

It doesn’t matter how cool your game is, if player don’t want to interact with its core elements. I need to interact with the character sheet, but if that looks like a miserable, boring, or annoying experience I’m not going to want to play your game.

If you get me to a playtest, but your core materials suck to look at and work with, and the game isn’t great, then I’m not to playtest it again.

If you give me decent materials to interact with and an ok game, I’ll probably come back to help in the next round.

I actually like the core design in the Heroes & Hardships books, but its character sheets makes me want to set them on fire and run away screaming “YOU CAN’T MAKE ME!!!!”

Make space or throw it out.

That’s pretty much it. If the player can’t determine what their options are and how they can execute on them then you need to make some space for things that can give them those answers.

Unless there’s a way to cheat.

Cheating

Sometimes cheating is OK. A good example of this is games with long lists of skills, that also limit how many skills you can take. Genesys’ default character sheets are a good example of where cheating wasn’t employed, but should have been.

I find this character sheet maddening, because the character it defines only has 5 skills, but the character sheet has space for 44 skills. Why? Yes, you can gain skills as you go, but you’re never going to get anything close to all of them.

This is a great place to cheat. Figure out what the max number of skills a character can reasonably get is and put in that many blank fields. It doesn’t matter if you game has hundreds of skills to choose from. They never need the full list to play the current session. They only need the ones that are important to them.

Also, Note that there is a column for “setting”. That’s indicating that these are the skills that are available in the current Setting this Generic System is being used for. Never waste space on your character sheet listing things your players can never use.

Needful Compromises

Many games allow your character to have a bunch of spells, or special abilities that simply can’t be fit on one side of an A4 / Letter sized page. D&D would be a much worse game if we just threw out spells.

For many games it’s a practical reality that some things will have to go on another sheet. However, the character sheet is dramatically less useful if we remove all relevant info for something critical from the main page.

For example: The official D&D character sheet has a wee slot for common “Attacks & Spellcasting” things, but it lacks the most critical information a spellcaster needs: an indication if it’s even possible for your character to cast anything.

There’s nowhere to indicate how many spell slots you have left. You can’t indicate that one of the “Attacks & Spellcasting” things requires - or doesn’t require - a spell slot. Do you need to be able to move your hands to cast this? D&D’s creators have deemed that all of these questions are important to playing a spellcaster, but I can’t answer any of them without flipping through other pages.

It’s reasonable to move your list of spells off to another page, but it’s not reasonable to force people who play spell-casters to check a second page to know if they can even cast a spell at the moment⁶. Doubly so when most classes seem to eventually get some sort of resource limited magic or magic-like abilities.

Throw it out if it’s not critical

See those little widgets on the left, for all the different forms of coins in D&D? I don’t know anyone who keeps track of how much change they have in real life. No-one I know wants to make change in some fictional currency they probably don’t remember the subdivisions of.

In early D&D editions, coins mattered because they directly translated into experience points. They don’t anymore, and money rapidly becomes irrelevant in most D&D games. Sure your character might not be able to “afford” the +5 suit of armor, but if that’s the only thing keeping players from getting it, they’ll just murder the shopkeep and take it.

There’s NO reason this valuable space needs to spent on coins when it could have been used to indicate how many spell slots characters had left, or other useful things.

Even if we didn’t have some other critical thing to track, the character sheet would still be improved by simply getting rid of these and allowing a bit more space to list your equipment.

Keep your old sheets

It saves a lot of time. I’m regularly making a tweak to a character sheet and realizing that there was some old version of it that had exactly what I need now. Or, maybe an old version of a sheet you made for some other game.

The more iterations your game goes through, the more interesting these are to browse through. You can see how your values and approach changed over time. Sometimes you even go “oh hey, I liked that thing.” and realize that your game has changed enough that you might be able to bring it back.

Also, keep a sheet with all the visual widgets you create along the way for your sheets. Just a kitchen sink of progress indicators, nifty icons, or whatever.

Accept Defeat

I’ve tooted about Spiral Dice before. I love these things. I desperately want to use them, and I keep trying to use them in this game. It’s taken me a long time to accept that they’re not the right tool for this particular game. It doesn’t matter how much I want to use them. I can’t. At least not here.

There’s a phrase amongst writers: “Kill your darlings.” It doesn’t matter how much you love an idea. It doesn’t matter how much you want an idea. What matters is if the idea contributes meaningfully to what you’re trying to do.

Narrative Dice Are Kinda Broken

There are a few takes on “Narrative Dice”. The most common, or well known use, is to allow rolls to have all of the following outcomes:

critical success
success with ancillary complications
simple success
tie with ancillary positive effect
simple tie
tie with ancillary complications
failure with ancillary benefits
simple failure
critical failure

The Narrative Dice that Fantasy Flight Games created for Warhammer Fantasy Roleplay (3rd Ed), and later reused for their Star Wars, and Genesys games are possibly the best known ones that do this, and I love the core idea. I love how a single dice roll can generate all those possible outcomes. These dice make die rolls into tools for driving wonderfully messy storytelling. At least, in theory.

Once you start to use them, you quickly learn that it’s really hard to come up some ancillary positive or negative side effect for every single test. Like, really really hard. In practice folks just end up using it for the simplest mechanical thing: extra damage on their hit, a bonus to someone’s next roll, etc.

The difficulty of coming up with the “yes, ands” and “no, buts” on every roll completely undermines the promise of dice that help tell the story.

And that’s before we address the fact that the dice are covered with symbols with zero inherent meaning, that players have to memorize and in order to understand which ones are good and which ones are bad, and which cancel out, and which count as two goods vs one good, or whatever.

Two other Options

There are two alternate ways of using Narrative Dice that I’ve seen that are both easy and helpful.

You can do something simple like assigning a color to each factor that contributes to a roll. For example black dice for your core skills, red dice for benefits from weapons, and blue dice for benefits from magic. Then when you roll, you see that you didn’t have enough successes from your core skills, but that the magical dice added just enough to succeed in your attempt. Now you can narrate how you “…lost your footing, and would have missed if not for your companion’s spell guiding your blade.”

The other alternative is what Parable Games has done with Shiver. To over-simplify a tiny bit, there’s an 6 sided die with a bunch of symbols on it. Each symbol’s associated with a skill. For example, a fist for “Grit” (lifting, punching, brute force), a heart with a rose in it for “Heart” (persuasion, deception, charm, etc.). You decide what skill you’re using, roll the relevant number of dice, and see if any came up with the Skill’s symbol. What you see on the dice reinforces the thing you were trying to do. This is dramatically helped by the fact that it’s easy for western players to associate the symbols with the meaning. Fist for punching and strength. A lightbulb brain combo for smarts. A four leaf clover for Luck. They leverage the established meanings of most of the symbols to help support player understanding.

You could just use a 6 sided die and say “When you roll Heart you succeed if a 4 comes up. When you roll Grit you succeed if a 2 comes up.” But that’s a lot harder to remember. It’s an accessibility aid, and a narrative aid. If you tried a wits roll, but failed with a bunch of fists you can look at the dice and say “I didn’t succeed because I tried talking instead of punching”.

Solo Playtesting

I have literally never heard any other game designer talk about doing this, and it is - without question - the most powerful and effective tool in my arsenal.

The idea here is pretty simple. Before you bring your game to anyone else, you will have played dozens or hundreds of sessions with yourself, and Mythic Game Master Emulator (GME). Print out character sheets, make two or three characters using your character creation instructions, sit down at a table and start playing. There is no planning necessary. Literally. Mythic can be your Game Moderator & generate the entire adventure as you go.

Of equal importance is the fact that you can stop at any time. If you stumble over a critical rules problem, or important decision that needs to be made about how the game works you don’t have an entire table of people who either have to go away or have to sit around while you spend however long it’s going to take to fix it.

This means you can iterate so much faster. You can try out half-baked ideas. You can try out that starter adventure, or better yet, generate that starter adventure (see below).

I can’t count the number of times I have put together a core mechanic that worked, that did exactly what I was hoping it would, but either wasn’t fun, or revealed that the bookkeeping required was worse than the gameplay it supported.

It’s key to be very self aware while playing like this. You need to try and notice when you’re annoyed, when you’re bored, and when you’re having fun. The latter is a little harder to notice in the moment, because you get completely immersed in the events that are happening. That’s why you…

Record Everything

The medium isn’t important: video, audio, written on paper, written on the computer, whatever. What’s important is that it’s a medium that is easy and/or enjoyable for you. These recordings are for you alone. You’ll probably never show them to anyone.

As you play you will encounter things that make you realize “oh, I’m going to need a rule for that”. You’ll have thoughts like “Doesn’t Starforged have a tool for this?”. Obviously these things need to be captured somehow, but there are smaller things that are equally important. Things like the die rolls.

When I was in the earlier stages of this process I wouldn’t write down all the die rolls. Later on, I’d want to make a tweak to the mechanic and wonder how it would have effected past scenes. Without the old die rolls recorded I couldn’t say. I’d have to spend time doing another playtest session. I love playtesting my game, but at the moment I just want a quick answer to my question so I can move on.

As you design a game, your focus moves from one area to another. In my experience I’ll wander away from one thing focus on something else, but then have questions like “Does that first thing still hold up with what I’ve changed since then?” “Am I still happy with that?” You can pull out those old records and revisit old decisions from a new perspective. Maybe you swapped a mechanic for a new one, and find yourself questioning the decision. Having recorded playtests means you can easily compare things. Well, “easily” once you find the right place to look.

Obviously, once you get your game in front of other people you’ll want to record that too. If you’re using video (best) or audio recordings remember to ask for consent & make sure they know that it’s just for you to review gameplay things and that you won’t be putting it online.

Example

I prefer good old-fashioned paper. I do a “journaling” style of solo RP where I’m literally hand-writing a story as I go. It’s slow AF, but something about it really works for me. Also, I find it way easier to find a specific piece of information in an annotated text than in a long video.

Every single time a die is rolled, I note which character rolled it, why, & what the result was. That sounds a lot more formal than it is. Here’s an example from the combat encounter I mention below.

Don’t worry about trying to read my scribbles. I’ll walk you through it. This record was incredibly useful during the playtest & after.

Doom Doomity Doom

In the right column you can see that I’m keeping notes on my Doom Pool⁷: “doom +1 = 2” & “doom +1 = 3->0”. This was partially because I’ve learned that it’s important to record everything mechanical that happens in this process, but more importantly to me at the moment the fact that my I had a mechanic such that whenever a 1 came up on the a player’s roll Doom was generated, and the GM would roll a die. If the die was less than the current Doom level, some complication would be inserted. This mechanic was “firing off” way more often than I had anticipated & it was becoming a problem.

As I continued to play the side-bar showed me the practical reality of my mechanic and how the numbers changed over time. I was able to clearly see that it’d always be “too much” and that it wasn’t just some bad rolls. I abandoned the “doom” mechanic, continued the playtest and came back to it later.

How many rolls

Later on while trying to figure out how to fix my broken mechanic I needed to know how many rolls I could expect in a typical session.

This isn’t a number you can look up online, because not only is it different from game to game, it changes with the GM’s storytelling style or what kind of antics the players like to get into. However, I’d been tracking all the rolls. In the way I record stuff, everything between the blue highlighter lines is either a roll, or “above the table” stuff; the discussions at the table that are about the narrative but aren’t, in the narrative.

I was able to go back through my playtest, scan through all the short blue bars, and count up how many rolls the players would have made over the number of events that I figured would fill up a standard gaming session. In the screenshot above there’s a roll directly after most of the lines with a note in the left column. T1-T4 is indicating which of the unnamed “bad guys” I’m rolling in response to. I don’t remember why I used “T”.

meta-notes

One of those notes is “[Doom = another voice heard in the distance shouting that it’s coming (2 rounds)]”. At the table the GM would just say “You hear a shout of support coming from the woods. Another one is coming soon.” I was recording how I adjudicated things when the doom pool was triggered. Sometimes that’s good example material for future GMs. Sometimes that’s a record of how you were struggling, and what was problems you were having.

Calculating rolls per session

Knowing the game system is enough to give us a reasonable starting point to work from. If your game’s dice usage is going to be similar to some other game, you can use it as a stand-in until you’ve got enough playtesting of yours.

For example, we know that most D&D combats don’t last more than 10 rounds. We know that players roll on every round, and that it averages out to about a 50% hit rate. So, 50% of the time they’ll also be rolling damage. Most characters get attacked most rounds & (guessing here) 25% of those times they’ll have to roll some sort of constitution or dexterity check.

Assume a 4 player table, and an 8 round fight, and you’ve got some numbers you can work with. On the player’s side we have 32 rolls to hit, 16 rolls for damage, and 8 “check” rolls. D&D tends to have a fight in every gaming session so we can reasonably assume there’s at least 56 player-facing rolls in every session. Round it up to 60 for some out-of combat stuff and we’ve got two useful numbers. Tada 🎉.

Now we can answer the question “how many rolls in an average session?”. For the many games like D&D it’s somewhere around 60 rolls per session, & 15 rolls per player per session.

If you haven’t tried solo role playing

If you haven’t done solo role playing with a “normal” RPG this may sound weird / impossible. It’s not. It’s incredibly easy. If you want to see an example of how this works go watch Trevor Duval’s Me, Myself and Die! Season One⁸. The first scene is a “chef’s kiss” example of how Mythic GME can tell a story you had no idea was coming.

Side note: Version 2 of Mythic GME is the combination of years of playtesting and learning by tons of players. It’s more refined set of tools, with tons of examples. However, my 🧠 has a lot of trouble extracting the core things you need to do from the descriptive / explanatory text in v2. If you have that problem, Version 1 is the same core ideas in a package that is very “to-the-point” and easy to use.

Generating a Starter Adventure

Grab the GME, a few characters, and start playing.
Record what happens as you go.
Bring it to a satisfying conclusion.
Take all the “here’s what happened” and convert it to “here’s what could happen” & delete or change any bits that weren’t entertaining enough.

Simple Example:

In a recent playtest 3 characters were quickly making their way through the rainforest to get to an unknown artifact before an opposing faction did. They crossed a perilous ravine, exhausted & happy to be alive. They didn’t realize they’d been watch by a new group of people who moved into the area. While they laid there catching their breath, they were ambushed. Completely overpowered they fought back until they could run for their lives.

Now I have detailed information on 2 separate “encounters” with very different things for characters to do. I’ve got a perilous ravine to cross & I know what that looks like & what environmental troubles & help they’ll have. I’ve got a combat scene that introduces characters to the idea that the only way to survive is to be creative. You won’t be able to murder your way out of every situation.

Solo Playtesting Adventures

While originally designed for emulating Game Masters, Mythic GME can be used as a player emulator. This, obviously can help your playtesting by coming at things from a different perspective, but it also means you can simulate what might happen when players start interacting with a pre-written adventure of yours. Alas, there’s no good way to simulate another GM reading and interpreting the things in your written adventure. You just have to give it to someone, and keep track of the questions and problems they have along the way.

Mythic Magazine volume 41 discusses how to use Mythic GME as a Player emulator.

What else?

There are probably some more important lessons that I haven’t thought of at the moment. Over time I’ll likely update this document with things I forgot, and new things I’ve learned.

I’ve also specifically avoided talking about tools. The tools that work for me probably won’t work for most of you. That being said, I derive a lot of value from seeing the tools other folks use to accomplish tasks. There will probably be a future post going over the tools I’ve put together, and what I’ve found to be useful, or not.

In both cases, if you’d like to hear about updates you should follow my account on Dice.camp

Call to action

This post took a lot of time. If you found any part of it worthwhile, please let me know. My TTRPG Mastodon account is the best way, but email works too ( masukomi@masukomi.org ). My blog posts kinda feel like I’m spending a lot of effort to yell into the void. If you’d like to see more. let me know. Ditto for anyone else creating content online.

: Whatever cool generic system thing you’re thinking of doing, please go read GURPS first. I assure you they probably did it, and they probably did it better, and more comprehensively than you were even considering. GURPS has a ton of bad PR about being a “crunchy” game, which turns many people off. It’s not. It can be amazingly low crunch, and there are so many great books for it on so many topics. It’s ugly. It’s old. It’s got far too many character options to choose from, but when you get to the heart of it, it’s a really good generic system. ↩︎
: If you’re playing a PbtA game and always using the “default” Move, then it’s either a poorly designed game, or you’re trying to tell a story it wasn’t designed for. ↩︎
: The spells in Dungeon Crawl Classics are a thing of beauty. Ridiculous unpredictable things that, even when you roll “successfully”, may or may not get you what you were trying for. Consulting a massive table every time you cast a spell isn’t great, but for the right table it can be ridiculous fun. ↩︎
: If you want a simple game where you go around having fun fighting monsters & bad guys, where magic can go wrong and screw everything dramatically, check out Index Card RPG (ICRPG). It has three default settings that are all great. ↩︎
Despite what I said about Generic Systems, Heroes & Hardships is a really good Generic system that does a lot of things right, and I’ve got a huge amount of respect for its creator. Alas, I hate that its character sheet looks like a freaking spreadsheet. ↩︎
: because someone’s going to try and say it: No, you can’t always cast a cantrip. ↩︎
: At its core a “doom pool” is a mechanic that lets the GM build up points that they can later spend to complicate players lives.

If you’re curious what the notation meant: “doom +1 = 2” meant the roll generated 1 doom & “doom +1 = 3->0” meant the roll generated one doom, the total was raised to 3, but then the pool got used and reset to zero. This is just what I was doing on the fly and not a recommendation for anything. ↩︎
: Me, Myself and Die! Season One is quite possibly the most entertaining actual play series I have ever watched. ↩︎

Making Great Productivity Tools

Fri, 17 May 2024 00:00:00 -0400

Table of Contents

Overview

Chris Simpson mentioned that he was working on “development tools for gifted brains” in response to my mentioning having created Noted. What follows are my thoughts on what it takes to make a great productivity tool that wont be abandoned, & works for everyone, not just the creator.

The Thoughts

Software is amazing. I love it, & I especially love when developers take the time to really focus on making better tools, or improving the ones they have.

There are also some GREAT things starting to happen in software with regards to helping #ADHD brains.

BUT they almost never stick.

I theorize that there’s always an impedance mismatch resulting from the fact that every 🧠 is different, & has different values & needs.

BEST case scenario for most attempts at ADHD is that they work GREAT for the creator, and a handful of others who happen to stumble on it. BUT there’s a looooong history of ADHD folks going “ooh shiny! that’ll solve my problems!” and then 2 weeks later they’ve wandered off. Given that happens with a LOT of software, BUT we’re kinda “extra” in this regard.

This is why - when it comes to “productivity” & organization of tasks - I turn to paper. Specifically paper with NO organizational structure I have to adhere to. I’m going to explain that, but then I’m going to talk about where those same attributes can be found in software.

Here’s the thinking: The organizational tools that work for other people’s 🧠s are RARELY ever going to be a perfect match for mine. On top of this, no-one really knows what works for their 🧠 until they really start experimenting.

So, I think we need to start with a foundation that allows us to try a strategy, abandon some parts, tweak others, and add new ones.

In the early days, this iteration needs to be able to happen FAST. Like, day-to-day changes. IF we actually pay attention to what is and isn’t working for our 🧠s (HUGE “if” I realize) we should be able to find something that “seems to work well” relatively quickly.

BUT that’s never the end. The longer you spend with a tool the more familiar you become with its strengths and limitations. You’ll find things you want to change after a while. Eventually YOU will change as a person. What’s important to you, where you’re focusing your energy, etc. So, again your tools will need to grow and change.

For example, Bullet Journaling (BJ) https://bulletjournal.com/blogs/faq really is a SPECTACULAR system / tool AND It was created by a person trying to overcome the very serious problems that their ADHD presented them. If you’re having trouble keeping on top of your tasks & schedule & remembering what you did it’s a GREAT place to start.

HOWEVER, very few people stick with the “official” Bullet Journal process, & many that like its approach have jettisoned certain aspects, & changed others.

BUT because BJ wants you to use “blank” paper (lined / dot grid / literally blank) it FULLY supports changing with the user. It’s an amazingly flexible framework built on the even more flexible foundation of paper. The only restriction paper really imposes is the size of the sheet.

In my game design notebooks, I’ve ended up using its “collections” idea, abandoned literally everything else, and inserted my own way of making page headings, subheadings, & noting specific sections of a page as atypically important.

Noted is a collection of physical tools to hold note cards, but what makes it really useful to me is that I have a specific framework for managing and organizing tasks. Sadly, I haven’t documented this publicly yet. Much like Bullet Journaling I think this will be really useful for a lot of people (even if tehy don’t buy my card holders) BUT I don’t expect many people to use it unchanged, & I built it on the amazingly flexible foundation of paper.

This post started with software though. And, all is not lost in that realm. I believe that any productivity tools that impose a strict process that can’t evolve with the user are ultimately doomed. In my experience people making tools for ADHD people to stay on top of their 💩 are atypically blind to this problem.

“Hubris” is one of the “Three virtues of a great programmer”. It leads us to create amazing new things instead of sticking with “good enough”, BUT it also leads us to believe that the fact that our tool works SO amazingly for OUR 🧠 that it’ll also work amazingly for other people’s 🧠s, but it rarely does.

All hope is not lost though. There are two amazing tools for developers which clearly show us, that it IS possible to make software that a user can mold to their needs, even if they’re not a developer.

Vim, & Emacs. BOTH of these tools are IMNSHO absolute dog-shit in their bare-bones configuration. HOWEVER no-one uses them in their default configuration, because what makes them amazing is that they are incredibly flexible foundations that do a core task (text editing) BUT allow users to change almost everything around that.

Imagine a “todo list engine” that had almost no functionality. Out of the box it might be an ugly list manager with barely any UI or guidance that does NOT work the way you want a todo list to work.

Imagine also, that it was ridiculously customizable and that, almost every way you could imagine to interact with, leverage, and style a todo list was sitting right there in a package manager waiting for you to install it. If you came up with something new, you could add it, or ask someone else to.

The creators would distribute it with some collection of things they thought was a good starting point. Some people might even make “distributions” with heavily customized collections of mods. Much like Bullet Journaling these would be a great place to start. Like BJ they’d also allow you to mix and match other ideas, to throw out ones you don’t like, etc.

This, technically already exists. It’s called org-mode. It’s amazing, and it does way more than todo lists. BUT it is text-centric AND Emacs has a reputation for being “hard” and “kids these days”, and the point wasn’t to convince you to switch. ;)

The point is that we have 2 historical references showing us that it’s entirely possible to build software tools that approach a common problem but also support wildly divergent brains.

Once someone “gets” that Emacs & Vim can be easily customized to support how their 🧠 approaches problems they end up molding them into the “perfect” tool for their brain. Over time they grow with you. You add new packages. You get rid of others. The community makes versions of old ones that may work better for you brain, or come up with wildly new tools no-one anticipated.¹ People use these apps for 30+ years because they grow with them.

Emacs built a flexible framework for text manipulation. It did a REALLY good job of that, but more importantly, it not only allowed for, but encouraged people to mold it to their needs.

If we want to build truly great productivity tools that support neurodivergent brains (ADHD, ASD, DID, etc) I think we need to learn from the lessons of Emacs and Vim.

We need to build frameworks that support one core idea exceptionally well and make it trivial for everyday people to mix, & match, & modify tools to support their brains, and not just the brains of the people who coded it.

This is easier said than done, and it means writing a bunch of “modules” to help show what’s possible, and make it actually useful for others. The modular approach means that we can also release a core collection of things that works great for us, and demonstrates the power of our tool, while also saving us from having to write all the possible variant needs for all the possible brains. We “just” need to convince a handful people like us that we’ve created something useful, and support them in making it more useful in the ways that they need.

A great example of things that couldn’t have been planned for, is Howard Abram’s tool for playing Ironsworn I love this example because it’s something the core framework was NEVER designed for, but is amazingly useful to the point that I want it for ALL my games. He’s spent so much time using a tool so devoted to supporting user extensibility that his tool is also a framework - within the framework that is Emacs - for supporting other RPGs. ↩︎

Lessons from an unexpected playtest moment

Sun, 21 Apr 2024 00:00:00 -0400

Table of Contents

Overview

Playtesting my Tabletop Role Playing Game (TTRPG) I encountered a situation that worried, and surprised me. This post discusses an unexpected combat where I’m worrying if my characters will survive because they’re too “real”, and then finding myself 🤯 “blown away” by what happens.

If you don’t care about how TTRPGs work, don’t bother reading this. I’ll be narrating a surprisingly short combat, and then talking about what worked well.

Quick Mechanical / Rules Note

In this game I’ve got approaches, which are a lot like Starforged / Ironforged & Fate Accellerated, but they’re combined with skills. So, if someone is - for example - trying to punch you, you could be like “let ’em try” and try to impersonate an immovable wall with sheer muscle. If you do it really well, they might become intimidated or something else narratively appropriate. Alternately you could “float like a butterfly” and try and dodge the blows.

Also, all the rolls are player facing, so when an adversary attacks, the player rolls to defend.

Learning from what went down.

Setting The Scene

Our companions have just overcome a harrowing - and potentially deadly - attempt to cross a ravine. When they reach the far side they fall to the ground exhausted; breathing heavy, looking at the sky, and thankful to be alive.

Before they can fully catch their breath, one of them hears a sound. They look over and see 6 people with spears coming at them with very stabby intent (🔪🔪🔪).

Side note on how we got here

Flopping to the ground after the harrowing encounter was the end of a scene. I was planning on having the characters just catch their breath and eat lunch. However the Mythic Game Master Emulator (GME) had other ideas. The oracle tells me it’s a “Confident Threat”. I’m thinking maybe it’s a large predator thinking it’s got an easy meal, but then the Creature Crafter is like “no way. it’s 6+ armored people”. I ask my oracle what their deal is and it says “Threatening Warning”. So, I’m thinking “ok, these folks must have recently moved into this area & are guarding it. Maybe we can talk our way out of this.” But then my Doom mechanic kicks in, and it’s like “well, actually… they are pissed and going to stab first and discuss later”

My Doom mechanic is basically a Doom Pool (a pool of points the GM can optionally spend to complicate players’ lives) with some rules to mechanically kick it off sometimes. As I play through this combat I learn its actually a little too aggressive & I end up ignoring it half way through. That’s a separate discussion though so I’m not going to really mention it much past this. Just know that most of the rolls are generating doom & the mechanism keeps making me use it.

Playing it out

At this point I’m fully believing that they can not survive fighting these folks, and running is their only real option.

You see, in this setting there’s a hint of magic, but mostly people are just… people - although not always human. Some are weak, some are strong, but mostly they’re like us: primarily differentiated by their personalities and the things they know how to do. PCs are no more powerful, and no less stabbable than anyone else. Also, it’s pretty easy to die. This is because in real life it’s pretty easy to die. Also, I’ve not been not rolling a ton of “successes” up to this point.

Our party consists of 1 large martial artist (Les), who’s paired with a weak, semi-ambulatory magic user (Meg) who usually gets around on a “Hover Disk”. Think wheelchair, but it looks like a wok. For story reasons that’s strapped to her chest, and even if it was under her, it doesn’t move quickly. They’re traveling with a Seer / Herbalist (Sennen) who has fuck-all for fighting skills but is physically fit. Note that magic is NOT about creating explosions and zapping rays in this world. It’s pretty subtle, but also very flexible.

However, they wouldn’t have made it across the ravine without Meg’s spells, and if she casts one more she’ll take a “Condition”, which would probably be a very Bad Thing™. There’s a good chance she’d pass out. She’s got the aspects “Weak” and “Semi-Ambulatory” which can be invoked by the GM (me), but mostly just mean “she’s not running anywhere, or lifting anything”.

I work out the red black initiative, & discover that 3 of the 6 bad guys go first. It is my expert opinion that the characters are fucked, and it’ll be a fucking miracle if they get out of here alive.

Three of them head for Les because he’s narratively an obvious danger (not relevant why).

BG1 (Bad Guy 1 - At this point I don’t care what their names are) manages to cut Les, BG2 tries, but Les rolls spectacularly, gets a critical success, uses it for a free attack, succeeds & because less has the “Powerful” aspect he spends a Story Point (similar to “FATE Points”) to invoke that and break the guy’s arm. BG3 doesn’t manage to hit Les, and now it’s Les’s turn. He gets another critical success, spends another Story Point & breaks this guy’s arm. Unarmed combat is Les’s “thing”, & he’s Meg’s bodyguard so all of this makes a ton of narrative sense.

BG4 is going after Sennen. Sennen - again - has fuck-all for fighting skills. She will not be able to just dodge the impending spear. As a player I’m thinking “Oh shit. Oh shit. Oh shit.” because I’ve got nothing. I realize there’s no way i can approach this like most TTRPG fights. The mechanics are clearly communicating, “You better get damn creative or you’re gonna die.”

So i start thinking about the character, and what she can do. Sennen’s job as Seer means that she spends a lot of time observing people, and understanding them and how they work emotionally. She needs, to so that she can convince them her predictions need to be taken seriously. Her strongest approach is “Heart”.

So, I lean into that. Sennen knows that she can’t beat these guys in a fight. Her strong intuition is telling her that they are not going to listen to any reasonable discussion. She knows what makes people afraid, because fear is a great reason to listen to a prediction. So, she becomes a completely insane Honey Badger of a human and instead of trying to dodge the attack runs at the guy screaming the most unhinged things she can think of to “throw him off” mentally. And it works! She rolls a critical success. Sennen catches him off guard, gets in close, uses the extra success to disarm him, and spends a Story Point to his spear into the woods. This is just so awesome and 🤯 that I have to reward it so (borrowing from FATE) I give him & his partner the “Aspect” of “disturbed / unsettled” with 2 free invokes. The next baddy was just coming in to stab a flopped intruder but now some fucked up shit is happening and the Honey Badger woman just got in his partners face and disarmed him.

Mechanically this gives me an extra die from invoking the “disturbed / unsettled” aspect, and 1 because he doesn’t want to hit his friend. So, Sennen just keeps going with what’s working, pushes off of the first guy, doesn’t dodge and fucking lunges at the second continuing to spout disturbing things and acting like she’ll fucking eat his eyeballs directly out of his skull. She wouldn’t, but he doesn’t know that. And again, a critical success, so again she uses it to disarm her opponent, and again spends a Story Point to huck it into the woods.

So, to recap: we’ve got 2 attackers screaming in pain from their broken arms. We’ve got 2 attackers with no weapons at hand, & only 1 of the characters has had had a chance to take their turn.

It’s Sennen’s turn now. She yells “RUN!!!” They were all close to begin with. She sees Meg getting to her feet, and shoves her forward so that now she’s “supermanning” her Hover Disk, which means its got someone on it, and it’s oriented correctly relative to the ground so it starts acting like a Hover Disk, and Sennen is pushing Meg and trying to GTFO.

The last attacker was going for Meg, but now tries to spear Sennen as she’s starting to go with Meg. Sennen’s still acting completely unhinged but she’s not directly interacting with this adversary so it’s not going to have the same effect. She’s just got to run with pure muscle and hope that she’s faster. That’s not her forté though.

To Help Meg spends 1 Story Point to say that as she was starting to get up she grabbed a handful of dirt and rocks. She then Helps Sennen by throwing it at the attacker’s face.

Sennen rolls and we discover that she doesn’t “run”. She RUNS. She rolls 3 successes and is fucking gone.

Finally, it’s Meg’s turn, but she’s strapped to a Hover Disk, being rapidly pushed through the woods like a kid pretending to fly. She can’t access her slingshot. She can’t cast anything that’ll be particularly useful to Les, and if she tries she’ll take a “Condition” (a Bad Thing™). So, she just lets herself be pushed and watches for obstacles. Les is on his own.

The 1st attacker, the one who actually hit, is pissed. Two of his friends just got their arms broken, but he actually cut Les and is gonna do it again. Until Les, rolls another critical success, takes the free attack, succeeds at that, spends another Story Point and this time, because he knows it’ll slow them down more, breaks the guy’s knee.

On his turn he takes off, avoiding the adversaries.

The scene ends with our protagonists “booking it” through the woods, while the camera zooms back to a group that’s got 3 screaming guys - one of whom is rolling on the ground holding their leg, two of whom are completely freaked out by the Honey Badger woman who disarmed both of them, and the last one is wondering WTF just happened.

There is also, a new adversarial faction that’s very pissed off, and will soon start hunting our protagonists.

Lesson’s Learned

At its heart my core dice mechanic is the Year Zero Engine from Fria Ligan. I’ve taken a LOT of liberties with it, but players are building a pool of dice, and hoping some of them roll sixes. So, each die has a roughly 16% chance of success. It’s not a lot.

Doom Pool

On top of that I’d added in a Doom Pool mechanic where every time you rolled a 1 it generated “Doom”. As soon as the roll was resolved, you’d see if the Doom pool got activated. It was getting activated way too often. Additionally I found it easy generate more doom (rolling a 1) but difficult to succeed (roll a 6). That is of course, a purely emotional take as the odds are always identical, but it was still sticking its nose in “too often”.

Whenever Doom was generated I’d roll a d6. If i rolled under, something “negative” happened. I rolled under a lot. Especially because many rolls generated more than one point of Doom.

In a way this feels like how PbtA games frequently feel like it’s nigh-impossible to have a roll without complications. Unlike many PbtA games I don’t have suggested complications for every roll, because I don’t have “moves”. I plan on creating some tables for mental and physical complications, but I just haven’t gotten around to it. Even then, I feel like “Doom” / GM Intrusions / FATE Compels shouldn’t be happening so often it feels like every other roll.

Also, the mechanics kicking it off so often means that there’s frequently none, or hardly any in the pool for the GM to use for story reasons.

I need to reconsider how Doom is generated, how much can be built up, and how it’s invoked mechanically by the game.

Helping Players

The big lesson here is not that my Doom mechanic is trying to kill me. It’s that with sufficient support, perfectly “average” characters can absolutely beat the odds.

Before I get into this, I need to acknowledge that the characters did roll atypically well, but I firmly believe that they could have pulled through with more average rolls. They’d just have been more battered. I think we can look to the many successful campaigns of Mutant Year Zero (and friends) for confirmation that it’s a dangerous / “deadly” system, but one in which most characters stay alive for an entire campaign.

The difference here is that in games like Mutant Year Zero all the characters and going out ready for a fight, and having reasonable expectations they’ll have one, & be able to survive it.

My setting isn’t like that. It’s more about telling stories of mostly “normal” people who find themselves in extraordinary situations. Yes, there’s magic sprinkled in but it’s just a subtle enhancement. It’s influencing elements or creatures, encountering ghosts, getting an occasional glimpse of the future. No zappy zappy with magic or sci-fi weapons.

In this case my characters were trying to race 3 days through the woods to get a thing before a religious group did. If they encountered the religious group, they had no intention of fighting them… but 💩 happens.

So, ultimately what we need to do is have a way for characters to find themselves in situations they’re completely unsuited to, without saying “Tough shit. You’re fucked.”

I think I may have succeed in providing the structure to support that. I’m not sure if players will be able to take advantage of it. As we saw with Sennen, it may require some very “lateral thinking”

Meta Currency / Story Points / FATE Points

This was the primary reason the characters survived. BUT the key to it working was to not use it for something simplistic like a bonus to rolls, or a reroll. First off, Year Zero already gives me a nice reroll ability that comes with a cost. Secondly, I think a lot of people have come to the conclusion is that one of the big problems with FATE is that no-matter how cool your “stunt” is, they’re ultimately all just “add +2 to your roll”.

Yes, I’m oversimplifying, but not by much. The point is, spending meta-currency to get a simple same-feeling mechanical bonus just isn’t fun.

Using one to invoke a Flashback like Blades in the Dark is pretty awesome. Using one to inject an object / fact into the world is pretty awesome.

I think Les using a Story Point to change a successful attack into a broken arm by invoking the fact that he’s “Powerful” is awesome. The rules don’t define the mechanical result of invoking your Aspects. They just tell you how, and trust the players and GM to do something that makes narrative sense, and is something that “could actually happen” in the scene.

Normally “disarming” an opponent means they drop their weapon, but that they can also pick it up again. Her opportunity to disarm was an option in the rules for “critical success”, but spending a Story Point to remove it from play wasn’t fancy, but it was an awesome underdog move. It also made narrative sense. She couldn’t have done it if they were in a room, but they were by the edge of the woods so yeah. It made narrative sense for that to be gone until they spent time to wander off and look for it.

Giving your players a tool that gives them huge flexibility as long as it makes narrative sense enables them to do creative things that have significant mechanical benefits.

My characters start out with 5 “Story Points”. That may be too much, but it’s not a lot. It’s also tempered by the fact that you can only invoke it when it’s

Critical Successes

I love games with complicated degrees of success. Great success. Success with complications, failure with benefits, etc.

Critical Success are a ton of fun. Having only 1 potential consequence like “double your damage” isn’t. I think I’ve got 4 specified options related to combat situations, and the strong suggestion that any reasonable form of “more” or “and also” is highly encouraged.

Mechanically Encouraging Cooperation

I’m leveraging Year Zero’s “push” mechanic. You’re rolling a pool of D6s & this lets you reroll everything that isn’t a 1 or a 6, but it comes with a cost. This is usually physical or mental stress, of which the characters have very small pools.

Rerolls do increase your odds, but not as much as rolling “with advantage” and allowing 5s & 6s to be considered a success. The difference isn’t as big as you’d expect, but it feels like it is. Of equal importance is that it encourages characters to help each other. That comes with a cost too though. If the roll goes badly, everyone who helped will share the negative consequences - assuming it makes narrative sense.

Combined with the ability to spend Story Points Meg was able to Help Sennen get a fantastic outcome at something she was bad at, and it enabled Meg to participate in a meaningful way when she would have otherwise just done nothing.

Aspects

There’s a lot of debate about “Aspects” as FATE uses them. I debate them with myself constantly. If you haven’t played with them I recommend checking out the episode of Wil Wheaton’s TableTop where they play FATE with one of its creators. It’s also just a great intro to FATE.

I have so many feelings about the idea of creating an Aspect in a scene and letting players then use it mechanically, but it can work.

I think it worked well with Sennen’s making her attackers worried / disturbed / uneasy. It made narrative sense. The dice were certainly trying to tell that story, and it also makes sense that after a couple “invokes” it’d be harder to leverage that. The adversaries would start dealing with it more competently. It should be noted that when I rolled I wasn’t trying to create an aspect. I was trying to not get skewered. After succeeding my GM brain kicked in and said “hey, that was an awesome moment. Let’s reward that. Let’s build on it.” So, I created an aspect that was ultimately just a side effect of creative play.

In addition to making a player feel great, making Aspects in that manner is also going to help reinforce the idea that “oh yeah, I can create an aspect to help myself”. If things had played out differently that may have been the best option for Meg’s turn. The game encouraging players to “help” each other so they can roll with “advantage” whenever possible is also going to feed into this. Players will be more likely to do something to help their friends in more ways.

At the same time, Aspects are a bit “weird”. I can see why some players might have problems with them.

What I learned from this is that they’re another important tool for helping characters to help themselves when they weren’t created in a way that is any good for the situation. It gives them a mechanical benefit for creative play, and creative play was the only way out of that situation.

Forced Creativity

With “Story Points” and flexible “Critical Successes” alone I’ve got a pretty decent support system for “you can do more”. Allowing players to intentionally, or inadvertently create “aspects” that help them gives them more options.

The complication is that I can have the rules put you in a tough place. I can’t make you think out of the box though.

For example, I think that if you asked someone who’d only played D&D to play Sennen, when she was about to get poked the first time they’d probably just “try to dodge”, and fail miserably.

I think the idea of “approaches” does help with this though. If you’re looking at your character sheet and going “damn, couldn’t punch my way out of a wet paper bag, but I am really good at [insert approach here] it encourages them to try a different approach.

Now, you’re definitely going to get players trying to bend the intent. I think Sennen’s “Honey Badger” approach using “Heart” was right on the edge of that. Some GMs might have ruled against it. Personally I allowed it because it was plausible, and because if I said no I’d basically be saying “Tough shit.” The rest of the encounter would have probably sucked for them because there wasn’t much else they could do. Also, just “holy shit yes!” I want to see what happens when the player / character tries something “crazy”. “Be a fan of your players” is some great advice, even when you’re playing solo.

My task is to figure out how to direct players towards non-standard options. I also need to find ways to encourage GMs to be fans of their players & their characters, but NOT to just “let them do whatever”.

I think it’s critical that whatever they attempt is narratively plausible. If you’re watching a movie about a weakling nerd who needs to see what’s happening on the other side of a concrete wall, you’re going to be “W.T.F?!” if they suddenly punch through said wall to see.

Trust things that work.

While I’ve severely modified it, the Year Zero Engine is a proven system. The math works. Tons of people have had great experiences playing it in a variety of settings. I was seriously wondering if I’d screwed up because I was rolling so bad, for so long. So, I graphed the probabilities, and saw that “Yeah, it’ll work. I just need to give players the tools to help themselves succeed.”

Manual Support Fins for 3D Printing

Mon, 11 Mar 2024 00:00:00 -0400

Table of Contents

Overview

Whilst very useful, automatically generated supports can waste a lot of material and result in lots unnecessary cleanup. Sometimes, you want to go with manual supports.

This post follows my failures and lessons learned in using manual supports. It should save you a lot of pain if you venture down this route.

Originally posted as a Mastodon thread that spanned multiple days. This presents of series of unfolding mysteries and discoveries as I try to understand some of the quirks of 3d printing.

The Setup & Goal

As part of a accessibility project I’m working on for a friend, I need to print out a thin plate that’s wider than my print bed, but happens to fit into the cubic printable area without needing to split it. Not wanting to deal with cleanup, or huge print times from a billion automatically generated supports. I decided to explore a technique for manual supports that was suggested in this video from Slant3D. They use FDM printing at massive scales, and know a thing or two about good printing techniques.

Here’s what I’m trying to print. I need two versions, one that’s 2mm thick, and one that’s 1mm thick. It’s 290mm wide, but my print bed is only 256 by 256. This is just one component of a larger device.

The goal is to generate a fin that’s offset from the print by 1mm with a series of small sprues that provide support for the angled piece, but can be easily broken off.

Here you can see the sprue design that I’m using. This didn’t change throughout the following tests as it worked pretty well out of the gate.

First Attempt

I checked in on the print and something had gone very wrong. It initially seemed like a very predictable, failure. I was wrong.

I figured that the two pieces to either side of the hole have no vertical support. Their layers there were simply being stacked at a 35° offset. I figured that it was simply a matter of not being able to do that for very long without any support.

However, things become weird when you step back and realize that the failures started BEFORE the cutout, or when you step close, and see what the side profile looks like.

It’s as if certain layers were simply skipped, but that couldn’t be happening. Was the piece vibrating back and forth as the height increased? I can’t wait to see the time-lapse, but I doubt it will have any answers for me.

Stepping back though, you can see that errors started emerging a couple centimeters BEFORE the cutout. Why?

Looking at the back-side / underside I don’t see anything terribly surprising given what was observed on the front. That is, UNTIL I snap off the support.

Here I see something truly surprising…

I open the slicer, and reslice the model using the same settings as before. Our culprit is revealed.

This is a false-color view. the white dots and lines are the “seam” points where the print head jumps up to the next layer. For most of the lower section of the print it is placing the seam behind the support. Then, it jumps to the side. This matches the source of our first edge failures.

It jumps back to the central support for about 1cm. During that time, we have a pause in the failures. When the seam points jumps back to the edge, the failures start again. Then, we reach the cut-out and the seam moves to the inner edge of that, stepping gradually up.

Wherever the seam is NOT along that central line, we have failures.

Lessons Learned

Normally you want your seam to be along the edge of a print. Something about this structure makes that a problem though.

I suspect that if this was a box, with sides, the sides would act similarly to a suspension bridge and provide the rigidity needed for this to not be a problem. Alas, it’s not a box. It’s just a 2mm plane with a cut-out.

After a little research I decide to add 2 more support fins, so that those side pieces aren’t “floating” so much. I also decide to manually paint where the seam will be so that i can guarantee it never swaps over to an edge. It’ll be behind the central fin whenever possible, and then behind one of the side fins as we cross the cut-out region.

Second Attempt

Seam painting turns out to be an absolute nightmare. I need to carefully paint the guide on the back of the print, but that’s always partially obscured by the support fin. It’s difficult to do with a trackball (my default mouse input).

I get really excited for a bit when I remember that I have an iPad and can use that to draw with the stylus. That turns out to be only marginally better, because Apple refuses to put any buttons on their damn stylus, and I have to keep reaching over to the mouse to middle click and drag the next section of the model into view. I have to be extremely zoomed in to be able to paint “behind” the fin. I spend maybe 30 minutes painting this stupid seam.

Before I started painting I added the 2 support fins on the side, and cut a bunch of holes through them to save on filament. This was a bad idea for two reasons. First, it introduced another variable which makes diagnosing the result more difficult if there are problems. Second, it introduced a ton of motion as the printer had to make z-hops while retracting the filament and fast starts and stops as it transitioned across the circular gap to get to the next place it needed to lay down filament.

This extra motion is extra concerning in a thin piece like this which could easily end up vibrating and being in the wrong place when the print head comes back around to lay the next layer.

The extra fins plus seam painting seem to have solved the problem, but after getting rid of the horrible failure artifacts from the last print, I realize that they obscured the problem along the top edge of the cut-out. As the line of the cutout angles up I’m gradually printing too much filament into empty space. The dangling loops make this pretty obvious.

Lessons Learned

Be cautious about saving filament if it’s going to introduce a lot of motion. Sometimes it’s more important to keep things moving smoothly.

Don’t assume that because you’ve diagnosed one problem, that it’s the only problem.

Third Attempt

At this point I’m thoroughly fed up, and late on shipping this to my friend. He won’t care, but I do. I decide to forgo the nightmare of manual seam painting, introduce automatically generated “slim tree supports” to address the cantilevered cutout edge, and just see what happens.

I was about to click print, but then I saw the time, and filament usage: 8 hours 2 minutes, plus a full quarter spool of filament.

Just getting rid of the holes in the manual supports dropped it down to 7 hours, 50 minutes. Painting away autogenerated supports along the lower edge gave me 6 hours 16 minutes. Abandoning the use of different filament for the autogenerated support interface layer brought it down to 3 hours, 33 minutes. Abandoning the brim gave me 3 hours, 26 minutes.

I’m down to 176 grams.

At this point I’m feeling demoralized, and just want to get this printed and sent to my friend. I’ve lost the spoons for being interested in lessons learned.

4 hours later I have a good print. So, I load up the 1mm version and slice that, forgetting to paint along the bottom edge to prevent autogenerated supports there.

This one… is close. A minor print artifact along the top edge where there wasn’t a support and the seam jumped to the egde again. I call it good enough.

Cleanup

At 0.2mm the tip of the sprue just barely makes contact with the print. In a handful of cases it proved to be too small and didn’t actually end up connecting. Maybe 0.3 or 0.4mm would be better.

This small size means that you can wiggle the fin back and forth a few times and easily break it off with your hand. However, there is a problem. The tiny bits of plastic that remain are sharp. You’d easily scrape a table if you dragged them across it with any force. They’re also very unpleasant to touch.

Because this is so late… Because these are just test prints to confirm an idea before making the final thing… Because only the side without the sprues will be seen after “installation” I decide to just attack it with a sanding block.

The end result is predictably nasty looking. You should never sand a 3d print that you’re not going to paint.

If I have to do this again I’ll probably use my Dremel Press (just a drill press made for a Dremel) with some sort of precise sanding tip to sand each sprue with minimal effect on the rest of the plate. A sanding block is a crude tool, but I just didn’t have the spoons to care.

As someone who takes pride in their work I hate this. I hate that I’m going to send something to a friend looking like this. He will see it because I’m just sticking these in an envelope. It’s already almost week after I said I’d send it out, though.

Conclusions

This is an interesting technique. Slant3D applies it liberally because they’re running a massive print farm. Minimal bed contact means that they can use automated systems to push a finished print off of the plate and free the printer up to start the next one. That’s not a problem most of us have.

On the other hand, removing supports is sometimes a massive pain. Sometimes it leaves the surface covered with unpleasant looking connection points where supports have been removed. Sometimes, like this time, you want to fit something diagonally up into the Z axis, because you print bed is just a little too small.

My takeaways from this:

It’s most effective when you have a piece with edges that can help provide a suspension-type-support to the plane you’re supporting above the build plate.
Cutting holes into the support fins introduces additional time and motion that isn’t worth the filament savings and can potentially introduce problems to some prints.
Combining it with auto-generated supports works well.
Drawing seams is obnoxious and should be avoided whenever possible until someone adds a line tool to the drawing mechanism.
You’ll need a plan for dealing with the tiny remnants of your sprues.
With a well calibrated printer, you can get make sprues that are only 0.2mm at the point of connection but that will still result in some sprues failing to connect the gap between support and supported. I’m thinking I’ll use slightly larger connections next time. It should be noted that I printed this with a 0.6mm nozzle. I suspect a smaller nozzle would have fewer failed connection points without changing the sprues.

Fnatr 02 Box Fan Replacement

Sun, 10 Mar 2024 00:00:00 -0500

Table of Contents

How to replace a broken fan on the Fnatr #02 Box

How to replace a broken fan on the Fnatr #02 Box

Overview

It’s essentially impossible for human hands to insert the plug from a new fan into the circuit board. There is a very tempting screw that looks like it’s holding the circuit board on. You’d think you could just undo that and have easy access. Removing that screw does nothing. Don’t bother. Instead, you’re going to need to carve out a space large enough for human fingers to fit in there and align the tiny plug into the tiny socket.

While you’re off buying a new fan, you might want to consider grabbing some magnets and printing my replacement HEPA filter holder. I have no idea what filters the Fnatr expects, but my replacement allows you to use cheap, easy-to-find, 3rd party ones.

Before you start, gather the following

A replacement fan.

You’ll need a 80mm x 80mm 5v DC fan with a 2 pin connection. If you want to reuse the screws that came with it you’ll need that fan to be ≤ 10.5mm thick.

This fan on Amazon US is an appropriate replacement. It comes with 2 fans and some metal grills that you can’t use.
A 2.5mm Allen Wrench
Tape

Painters tape, Scotch tape, Masking tape, whatever.
A Dremel

Alternately a router with a small bit, but that would require disassembling the enclosure and you probably don’t want that.
A wood carving bit.
Something to provide upward facing lighting

You’re going to be carving into the ceiling.

If you’re wondering that shiny stuff is the aluminum layer on the inside of the Butyl Rubber soundproofing. It’s designed for cars, and works great there. It works well here too. From the outside my enclosure is entirely black because the other side - the rubber side - is very black.
Eye protection

Carving upside down means little flakes might fall into your eyes.
Respirator

I don’t know what the roof and floor of the enclosure are made of, but it releases some pretty obvious VOCs when you start carving into it. It’s not terrible, but it’s not great either.

The process

This assumes you’re going to do the work in-place. This will be easier if you remove the enclosure lid, flip it over, and put it on a work surface. However, that means reassembling the thing, which is a pain-in-the-butt unless you feel like also routing a chamfer into the outer edge of the groove before you re-assemble it. That would be a nice improvement, but as this carving will take you less than 5 minutes, and you’ll probably never disassemble it again. It’s probably not worth it.

Remove whatever’s in the enclosure (presumably a printer) to give yourself space to work.
Set up lighting.
Unplug the enclosure The USB-C plug.
Unplug, the existing fan and light. You’ll probably need to use needle-nose pliers.
Unscrew the fan.
Move the light wires out of the way. I recommend taping them out of the way. Removing the light bar would be better, but I think it’s glued in.
Place tape over the plugs and sockets so shavings don’t get in them.
Start carving with the Dremel

Note, you CAN NOT use the depth shroud thing. As you can see in the next image, it won’t allow you to get close enough to the edge. You’re going to have to freehand this.

This is what mine looks like now that I’m done. The only applicable bit i had was a cone with a rounded end. That’s why the top of my carving looks all wibbly. Also, you can see just how fine the particles are and why it’s important to tape off your connectors. I used canned air to clean everything out.

Note that you can make the hole bigger. I think the size in that photo is about the least you can do and actually be able to plug things in. It doesn’t matter if the edges of the hole make a seal against the side of the fan. The cutout for the fan is really only used to orient it under the screw holes.
Vacuum everything.
Pull the old fan off of the metal plate.

It’s not attached. It’s just sitting on little posts.
Replace it with the new fan.
Plug the fan and light back in.
Plug the USB-C back into the outside.
Test that the fan is blowing in the correct direction.
Screw it into the enclosure.

Be sure that the cord is exiting the fan towards the doors of your enclosure.
Optionally install replacement filter holder

If you printed my replacement filter holder, and have the appropriate filters, now’s the time to install it.
Stick your printer back in the enclosure.
Run a test print to make sure nothing got jostled while moving the printer.
Congratulate yourself on a job well done. :D

What is 3D Printing Good For?

Mon, 19 Feb 2024 00:00:00 -0500

Table of Contents

Overview

There are a lot of folks out there who are interested in 3D printing, but then they look at one of the many sites of free models like Printables and see a lot of silly tchotchkes that seem like a waste of plastic and space, or cheap things they can already buy cheaply like pen holders. Recently someone asked the following question on Reddit.

What type of people need a printer?

I’ve been sitting on the idea for 4 years to buy a 3D printer but every time I decide against it. In my mind, If I need a small part for something, I’d rather just buy a quality version of it instead of a brittle plastic one. I considered it for small tools for locksmithing but … why would I? I can just buy the real thing and have it last years. I think it’s useful for intense D&D players or cosplayers but that’s not me. And every time i research useful things to make with a printer it’s always stuff like “pen holder, mini plant holder, phone case, remote mount”. Which I have to admit are pretty lame for a $200-$500 machine and materials. Everything I read can be found at a dollar general. But they have to be popular for a reason right?

So who consistently uses a 3D printer? What do you personally use it for that isn’t just a holder for a small thing? Can you justify printing something over just buying it?

It’s a totally reasonable question, and one that I’ve answered variations of a bunch of times. This post assumes you don’t know a lot about 3D printing and are wondering if there’s any “real” value to getting one.

First though, let’s address some conceptual housekeeping so that we have a common understanding going forward.

Terminology

When people say “3D Printing” what they usually mean is “FDM” (Fused Deposit Modeling) printing. This is where you’ve got a spool of filament that is gradually extruded through a hot nozzle and builds up a print layer by layer. There are countless practical uses for this, but it’s not good at printing fine details (sub millimeter).

However, at the consumer level there’s also “Resin” printing, which uses light (laser or LCD) to strategically harden layers of goo. This is a messier process that involves dealing with some nasty chemicals but produces pieces with incredibly fine detail. This is great for things like D&D Minis.

Plastic types

short version: PLA, ABS, and TPU are 3 of the many filament types available, and I’ll be referring to them later. If you don’t care about details skip this bit.

PLA is the most common filament. It’s made from Polyactic Acid which is technically “plant based” but even when there aren’t additives it’s not something that’ll break down quickly in the environment or even in a composter.

ABS is what’s most commonly used in injection molding, but some home 3D printers can print with it too. As a rule of thumb, if you buy anything plastic it’s probably made with PLA. It’s got a lot of good properties. However, it releases some truly nasty Volatile Organic Compounds when you heat it for printing that you really shouldn’t breathe. The biggest reason to use it is that it’s got enough heat resistance to be stuck on the dash of a hot card in summer and not melt. There are better alternatives, and many aren’t as nasty.

TPU is a “rubbery” filament that can be used for gaskets or things where flexibility is important. It comes in multiple levels of… floppyness. Technically this is called the “Shore Hardness”. I don’t know why. What’s important, is that this is a very useful option for consumers The softer it is, the harder it is to print.

Resins Unfortunately this is not an area I can really speak to with authority. I know there are many available, and that it’s easy to mix pigment and sparkles into the clear resin to make something a particular color, but most folks seem to use it to print grey things that they paint afterwards.

Misconceptions

Strength

For most things you’re likely to want to print FDM prints are more than strong enough. Especially when it comes resisting compressive forces. They’re less good at resisting being pulled apart. However, we’re talking over 900 Newtons of force to rip a standard PLA (the most common filament type) print in half.

Lasting Power

3D prints last a LONG time. Despite being “plant based” the things you print with PLA are going to outlast you. It may fade in sunlight, but that’s true of most plastics. PLA is NOT good in water, but other filaments are.

Degradability

Multiple filament makers promote the fact that PLA is “Plant Based”. It would be equally accurate to say that petroleum based plastics are also “Plant Based”. Some filaments say they can be composted. Alas, this is only technically true. It would have to be an industrial composting facility which has significantly higher temperatures than your back yard, and even there it’s so problematic that they generally won’t accept them.

PHA filament from ColorFabb is the only one I’m aware of that is truly compostable, even in a home composter. However, at the time of writing (Feb, 2024) it’s pretty new, not cheap, and very few people have actually worked with it.

Filament Reusability

It’s technically possible to re-melt filament from old prints, but in practice it’s surprisingly expensive and non-trivial. I have a blog post explaining how to recycle 3D prints.

Food Safety

Even if you print with a food safe filament, FDM printed items are not food safe. The problem is that bacteria can hide between the layer lines and resist cleaning. Using a food safe filament for things like organizing your cutlery drawer is fine though, because the print is never going to come into contact with food.

Printing Minis

People who play tabletop games like D&D or Warhammer generally like to have miniatures representing their characters or troops. Your common FDM printer is not going to be good at this. They just can’t reproduce the level of fine detail you need. You need a Resin printer for this. The good news is there are some really affordable, good quality ones that can easily print most minis.

What’s it good for?

If your primary desire is to print gaming minis, a cheap resin printer from a reputable maker will pay for itself in a week. There are tons of excellent mini designers out there with very affordable models. You’ll never need to model your own. Just be careful about getting one with a big enough print plate for the things you want to print.

For everything else though…

It depends on your willingness to learn how to model things yourself. Simple shapes are easy with tools like Tinkercad, but the more you get into this the faster you’ll get frustrated with how hard it is to do anything but the simplest of shapes. Learning real CAD (Computer Aided Design) software is a fair amount of work, but it’s absolutely worth the time investment. There aren’t many good options between “beginner” and “professional”. The most popular professional tool for amateurs is Fusion 360. It has a free plan, and there are tons of video tutorials that’ll help you learn it fast.

If you’re not interested in spending time learning a professional level tool, then frankly I don’t think you should bother getting a printer. Tinkercad is fun and easy but incredibly limited and hard to do anything complicated with. Sites like Printables do have a ton of things you can download and print, but most of it is not anything you really need often enough to justify buying a printer. The big exception might be the ever-expanding Gridfinity organizational system.

Where 3D printing really shines though is not the stuff you can download and print. It’s the things you can’t buy, and sometimes the things that are unreasonably expensive to buy, or ship.

Fixing Things Manufacturers no longer value “high quality, well made” things that last a lifetime. Things are constructed as cheeply as possible, have no replacement parts available, and are rapidly abandoned by their makers. Things will wear and break in ways that shouldn’t require throwing them out and researching potential replacements.

If you know how to measure and model things you can make just about any plastic replacement part you need: replacements for worn gears, broken switches, lids, etc.. The only real restriction here is heat. If you need something that can survive the heat of a car on a hot summer day with full sun, then you’ll need some special filaments which require higher end printers and ventilation systems that aren’t easy or cheap to set up.

3D prints can also be used to make molds for poured metal parts like brass gears, or metal sculptures.

Prototyping Thinking about making a physical object for sale? Need a way to cheeply iterate on something in the real world? Maybe confirm that it fits and does what you expect before spending a lot on making a metal version? 3D printing’s great for this.

Solving Unique Problems This is where 3D printing truly shines. Once you learn how to quickly model your own things the possibilities for solving real world problems are endless. It’s hard to convey a sense of just how many things you can do, so instead I’ll give you examples of what I’ve used mine for in the following section.

How I use Mine

Non-exhaustive - and unordered - lists of things I’ve printed and hope to soon print.

Things I have printed

a custom system for managing notecards to help keep track of all my ideas
bolt covers to keep the bolts on the bottom of my desk from ripping my jeans, and pressing into my legs uncomfortably.
custom dividers and inserts for Milwaukee packout cases
things to organize my tool drawers: bit organizers, socket organizers, lots of Gridfinity things
a custom keyboard and trackpad holder to address a friend’s accessibility issues (palm rejection doesn’t work for him so laptops always think he’s mousing when he isn’t). Technically this is still in-progress.
custom mounts for my split keyboard to attach to my desk so that the right half stops “going walkabout” while I’m trying to use it.

I’ve actually made two different versions of these to attach to two different desks and at different distances. One for myself, and one for a friend.
one for my friends desk with an longer curved & angled front because his keep sliding down the front edge.
custom dice trays, with leather bottoms that attach to the sides of my wooden lap desk, and then connect together with a rubber (TPU) gasket that holds them closed like a clamshell.
a valet tray that I use in our freezer because the weird silicone ice cube tray i use to make Tea Cubes has a habit of overflowing and leaving a creeping frozen brown in the freezer… or it used to.
Currently working on an adapter for my Dremel Drill press to allow it to mount the soldering iron I use for heat-inserts
custom organizers for board games with lots of pieces and / or cards
a custom organizer for games with lots of little tiny markers or dice that suck to put into or remove from those terrible little zip-lock bags they come in.
a custom pen/pencil holder that attaches to the side of the little side-table shelf thing that sits next to my side of the couch.
a custom single index card clipboard that fits in a pocket and allows me to write a note on one anywhere.
custom switch cover to install a switch in a big gaping hole in our ambulance.
more custom switch covers
a light box for photography
A jig for evenly spacing and aligning the LED strips for that light box.
A Micro Jib (video link) for photo and video purposes.
A jig for precision cutting of steel rods for the Micro Jib
A custom hole cover to protect wires from sharp metal edges
A Paper Towel holder mount
A special flexible plastic to adjust the seal on a CPAP
coasters
new discs for my disc binder
bookmarks that attach to disk binder disks
custom tool holders
adapter to allow me to use cheaper, easier to find HEPA filters with my printer enclosure
tons of mods for my 3d printing stuff. Everyone does this though.
Tool holder wall (I went with the Honeycomb wall, might go with Multiboard if i revisit this.)
jigs for holding dice I laser etch.
jigs for holding other things.
magnet insertion tools
a fake rock with cutouts for holding a small bottle of medicine and a syringe.
A custom tool to facilitate cutting lids off of 5 gallon water bottles.
D&D Minis. These were on my last FDM printer and they were not very good.
Headphone hangers
Fixed a lamp. It fell over and the ring that held on the diffuser no longer fit. So I printed a replacement out of flexible filament.

Warning

If this post has convinced you to get a 3D printer, I must give you a warning before you do. Cheap FDM printers are, in my opinion, a pain-in-the-ass. I almost never used my first printer because it was a constant series of frustrations and poor quality prints. There are thousands and thousands of posts on reddit of people asking why their print has one of a hundred different possible problems. Getting a $200 (USD) printer dialed in to make great prints is possible, but it’s a lot of frustrating work that feels like your trying to read tea leaves.

My current recommendation (February 2024) is to get any of the printers made by Bambu Lab. The more you spend the more you’ll be able to do with it. The reason I recommend Bambu is because their printers are the closest anyone has ever come to making a printer that’s as easy to use as a Laser Printer. It’s not quite as easy yet, but it’s damn close. Getting a printer with an enclosure like their X1 Carbon (X1C) will make your life easier, because the ambient temperature has a significant impact on the quality of your prints. Unfortunately, the X1C + the multi-filament management system (don’t buy it without that) is like $1500, and then you’ll need to buy filament.

I use my X1C probably 3 times a week on average. I never print tchotchkes.

Feel free to ask me questions on Mastodon. I’m happy to help people out.

Wyrmwood Modular Table - Thoughts

Fri, 02 Feb 2024 00:00:00 -0500

Table of Contents

Overview

This post is broken down into two sections: thoughts on the table & accessories, assembly gotchas. This post will not go into many of the significant issues with the company’s leadership, and management.

Table and Accessories

The table itself

Overall the table lives up to the marketing. The thing you need to keep in mind about it, is that while these are high-end tables they’re also not artisan tables. These are mass produced with good quality materials. There are plenty of blog and video reviews of Wyrmwood’s first generation modular table, and I believe their commentary apply well to the 2nd generation. This isn’t a notably different table.

I am dubious about their implications that children can paint on it and use markers on it and everything will clean off without a care, but I’m not about to put that to the test.

The magnetic rail system is very nice. It works really well. Things feel very solidly held, and the system is so simple that anyone with a some magnets and some wood, or a 3D printer can make their own accessories.

We were concerned that reaching past the edge into the table would feel awkward. In practice it’s been absolutely fine.

There are, however, three frustrating aspects of the table for me.

First, there are two holes at the end of each piece of the apron that are a key part of the assembly, BUT they’re drilled too far from the edge for the hardware provided. I’ll cover this in more detail in “Assembly Gotchas” but the short version is that the legs are well made, but each bolt is only using about 1/3rd of its threads. It works, but if I had access to a lathe I’d mill some new hardware for them.

Second, at the center of each apron piece you can see an area that either didn’t get varnished, or didn’t get the last coat of varnish. It seems as if maybe some sort of holding piece was here when they were varnished.

In their defense, this makes sense from an industrial mass-production perspective. It’d require twice the drying time if you varnished all but the side being held, let it dry, turned it over, and varnished the side that didn’t get it the first time. Also, it’s in a location that you’ll never see once the table is assembled. However, this is marketed as a premium table and that feels lazy.

Third, the plywood inner-table. Underneath the felt surface are multiple pieces of plywood. Intellectually it’s unreasonable to expect them to use anything else, and they did show that it was plywood in their behind the scenes video of making things. Emotionally it feels really cheap.

Dowels connect each piece, but the dowel holes are way too big, and the plywood is so thin that there’s very little wood between edge of the hole and the surface. You’re essentially guaranteed to break it if you follow their instructions for sliding the pieces together on anything except maybe the small table. Wood screws are used to attach the plywood to the table meaning each time you assemble it (when moving) you’re damaging the holes a little more. It’s not an unreasonable choice because you’re not going to disassemble it and reassemble it many times, but it’s also the cheap and lazy choice.

The “Toppers” (the removable table top) are sold separately. This feels ridiculous. I would be surprised if even 0.5% of their table customers buy a table without them.

Minor defects:

One of toppers has a manufacturing defect on the bottom. Ours is “rustic” which means many small pieces of wood of varying colors are used to make up the whole. One of the pieces of wood had defects that went too deep for their sanding. The piece should have been thrown out and QA should have caught it. There’s also a gap in the end of one of our pieces. It doesn’t extend the full length and is probably just a sanding issue, but it is visible. In their defense I’m being very nitpicky. Minor defects like these should be expected in a mass-produced item. At the same time, this is not a cheap purchase.

The accessories

With the exception of The Player Desk, and the Hobby Shelf every accessory seems to have a curve on the attachment-side that matches the curve you can see. This looks nice, but only when it’s not in use. When in use it means that any pressure you put on these is not going to be evenly distributed along the far edge but focused on the two rear corners. Does this matter practically? I’m not going to press hard enough to find out when and how ours break, but it’s an artificial weakness that wasn’t necessary and doesn’t help anything.

The Hobby Shelf

I don’t like that the End Caps of The Hobby Shelf sold separately, or that they are detachable. I understand that the idea is that you can connect multiple of them and make a wide flat place for things. I don’t think many folks will actually do this. And if you get enough for that you’ll probably need somewhere to store them.

Without the End Caps, The Hobby Shelf looks unfinished relative to the rest of the table.

The Player Desk

It feels surprisingly sturdy. It works well, and it meets the expectations set by the marketing. However, it’s not very comfortable to actually use for any notable typing or writing because it ends up sitting a little too high. There’s not really anything they can do about this. It’s just the nature of having a vertically thick table whose underside is high enough to go over your legs when you sit.

The end result is that this is great for reference. Put a laptop on it. Put a book on it. Don’t try and write your homework on it. At least not at the table.

Cup Holders

We got the Large Cup Holder and Small Cup Holder. The small cup holder holds beer bottles, and basically nothing else. They say “stemware” but I’m dubious. Even if your stemware happens to fit, I’d be afraid of breaking off the stem if I lifted it too fast. The Large Cup Holder works as advertised. Don’t get the small one unless you consume a lot beer in bottles, or things that come in bottles of that size & shape.

Card organizer

I think the Card Organizer is designed for standard playing cards where you can overlay them and only need to see the corner of each. It’s not wide enough to hold even 3 poker cards with the full face visible. The rows are so close together that it’s impossible to see anything but the top edge of anything that isn’t in the front row. With traditional cards this means you’ll be able to tell it’s a black 3 but not if is it a club or a spade. I feel like the people who designed and approved this couldn’t possibly have been into traditional card games, because it’s useless for any game with large hands where you need to actually know suit and number.

The games I play with cards require me to be able to see the whole card, which means it’s useless for me too.

Don’t buy this. I’ve added the task of designing a replacement that actually works to my personal ToDo list.

The Topper Block & Tray

First some terminology. A “topper” is one of the slats of wood that fit together and go over the gaming table to convert it into a normal table. It’s kind of like a table “leaf” except that it’s just a pretty board that sits on top. The Topper Block, is just a block with slots to hold those where they won’t get scratched while you’ve got the gaming table open.

This works as advertised but I’m really annoyed by this whole thing. First, it’s bullshit that The Topper Block Tray doesn’t come with the Topper Block. Most of the time you’re going to have the “toppers” on the table and the block will be empty. Otherwise the table surface is just a piece of felt waiting to soak up spills and collect dust and particles.

Our Tray also doesn’t match our block. This is because they don’t offer “Rustic” versions of the trays. It’d been so long between ordering and delivery that I thought they’d sent us the wrong one. The mismatch looks bad, and like they cheaped out.

They also really cheaped out on the construction. The outer box is fine, but they just reused the same packing foam that they shipped things in to hold your toppers in place. I expected that the little “fingers” that hold things up were going to be felt covered plywood or some other form of rigid structure with a covering to not hurt your toppers. Instead it’s just a stiff plasticy packing foam. The foam is being compressed when you have pieces in it. In order to make this work they needed to make it a very snug fit. So, when you insert or remove a topper you have to use force to push or pull. This isn’t terrible, until you get to the last piece at an end. Then you have to put a foot on the block and hold it down otherwise it won’t let go of your topper.

It gets worse. The topper pieces that go at the ends of your table are slightly different. They have little rubber feet on them to keep them in place. They fit just inside the corners of the inner table area. I’m 100% fine with that. The problem is that they didn’t cut a slot into the foam that would accommodate inserting it with the foot side pointing outward. Because of the way the toppers fit together on the table you’ll be grabbing an end first, and you’ll want to put it in one of the end slots of the Topper Block.

The problem is that when you lift a Topper from the side of the table, the bottom is facing away from you. The simplest motion is to pick it up, and hold it vertically in front of you as you walk to your Topper Block. BUT you need to flip the first end piece around before inserting it because otherwise it won’t fit. All the other pieces will be not flipped because that’s easier.

Is this a minor nitpick? Yes. It’s also a minor annoyance every single time I open the table and there’s absolutely no good reason for it.

It’s also not a square. It looks like a square, so I keep grabbing the Topper Tray and just trying to put it on, but half of the time that doesn’t work, because it’s a rectangle and needs to be rotated 90°. Again, a minor annoyance, but an annoyance. There’s nothing indicating “this side forward” although 2 of the edges of the topper have a little cut out of them it’s not obvious if that should be on the side or the front.

Topper Tray

They market it as being useful as a dice tray. This is true. It works well as a dice tray. However, you’re not going to use it as one because it’s too damn big. It takes up too much space to be used by a single player or pair of players. It’d be too far away from some players if you put it in the center of a long table. It’d take up too much space if you put it in the center of a small table.

I appreciate that they at least made it capable of doing something other than just covering the Topper Box, but in reality you’re not going to use it.

Tray Drama

The Corner Dice Tray, and Topper Block Tray were sold to Kickstarter backers - and presumably some pre-orders after the Kickstarter - as having leather lining (for rolling your dice on). Both shipped with felt. The Topper Block was also show with with a chamfered edge.

It was eventually revealed that the company created a handful of Topper Block prototypes before the Kickstarter. That’s what they used for the promotional photos and videos. It seems they never considered what it would take to build those designs at scale. Then, after changing it, they didn’t bother to tell anyone. Customers started getting things that were different than what they ordered and many were very upset. Doug - the co-founder who seems to run things - responded that, “Those people need to relax.”

Overall, Wyrmwoods handling of it was 💩.

In the end they offered a $25 gift certificate to affected parties. They did this is one of the Kickstarter updates saying, “to those that have their trays shipped to them before updated photography is available”. This was on November 20th. The Kickstarter campaign ended on January 15th. I’m not sure when they ended up updating the photography on the site, but if it ended up being before someone got theirs then tough shit. Doesn’t matter that we sold you one thing and you got another.

There was no separate email to customers about this. It also completely ignores the fact that a lot of people aren’t going to read every kickstarter update, or every detail of the long ones. In the case of this campaign, the updates are essentially all the same and can be summarized as “we’re behind in shipping” and “logistics are hard”. I suspect lots of folks didn’t notice until it was too late.

Did they technically say “sorry”? Yes. Did the whole thing feel like them not actually giving a shit and expending the least possible effort whilst saying the politically appropriate things? Also yes.

I feel like their CEO (Jason) actually does care about customers. I also feel that it doesn’t matter because Doug seems to set the tone and handling for everything.

Assembly Gotchas

Instructions

The paper instructions are fine. The PDF instructions are terrible. The PDF is laid out for the same long folded paper that they used for the included printed one. This doesn’t correspond to anyone’s home printer, or anyone’s screen. It’s just bad.

Tools

In addition to the tools provided and recommended you will need a flashlight to see down into the dark holes, and you should have a “speed square” to make sure you actually have apron sides and legs all square to each other. A drill bit that is the same size as the holes in the plywood. Some coarse grit sandpaper.

When using the speed square you should be careful to not lay it on grub screws that are poking out, and only hold it against wood. The grub screws keep being where I wanted to place it.

Plywood

Finish the screw holes

There are holes through the plywood that the wood screws will go through when attaching to the apron. Many of ours were not drilled the full way through, or had chips that weren’t removed at the end that prevented us from seeing if the holes were aligned with the pre-drilled holes in the apron.

I’d recommend taking a quick pass over each hole with the coarse grit sandpaper. Hopefully that’ll remove most of the problems. Then go back and drill out any hole that needs it and sand any chips that are left.

Use your flashlight to align the holes before drilling. Do not assume that because you lined up one piece of plywood that the piece next to it will be aligned.

Align every piece with its holes individually. Then screw in the four corners of each piece. Then go back and screw in the rest.

Be cautious with dowel holes

The instruction video shows lifting one piece of plywood with dowels in the end to slide the next piece onto them. Do Not do this! The distance between the dowel hole and the plywood surface is too short and the dowel is /very likely to rip through it. I don’t have a better solution beyond just being very slow, and very careful and using the help of others.

Attaching the Legs

The leg attachment is a real problem. It’s also how the entire table is held together.

At a high level, you screw a series of “posts” into the leg, and slide them into a hole in the apron. The apron has 2 holes you drop cams and grub screws into. These clamp the posts into place. The idea is fine. I have no reason to believe it isn’t a good solution. The problem is that they fucked up the measurements of the posts and put the holes too far away from the leg.

There are two different and incompatible instructions about how to deal with the posts.

The first instruction is to screw them in until they stop, and then back them out just far enough that the divot in them points towards the far end of the leg. This is exactly how it should be, but if you follow that instruction the post will barely even reach the hole for the grub screw, and thus you won’t be able to hold it in place.

The second instruction is to use a plexiglass template they provide and unscrew the post until it is at the edge of the template. Do not do this either! The template was clearly constructed with the wrong measurements. If you do this there will be zero to one-half of a thread holding the post in. It will not only fall out, it won’t be able to hold the leg on.

Instead you need to compromise and find a point where the edge of the post is just barely past the center of the hole for the grub screw, so that the grub screw has something to catch on to and so that the post actually has enough threads in the leg to hold it on.

This is bad. If you know where to buy longer posts do it before assembly. If that’s not an option and you are one of the rare people with a lathe, make new posts that are longer.

I’ve found the connectors they’re using on a German site. [Click the German flag at the top to see the English version]. These may be available elsewhere. Try and find posts that are about 1cm longer than the ones Wyrmwood shipped. For some context in finding these, this is not something an individual woodworker would likely use. This kind of connector is used by companies producing things as quickly as possible in significant numbers.

Should you get one

You should get a gaming table if you can afford one, or make one if you’ve got access to the tools. Having it has been wonderful and we’re actually playing the many board games in our shelves.

Should you get one of Wyrmwood’s gaming tables? Honestly. No. You shouldn’t. Their magnetic railing attachment thing and accessories are unique, work well, and very tempting. The barely attached legs are extremely concerning.

For a variety of reasons, in addition to the company dismissing numerous allegations of sexual harassment and keeping the person in question on staff, everything they communicate and do feels incredibly dismissive, half-assed, and incompetent.

Despite having Kickstarted essentially the same table before and having massive logistical issues then because of unexpected demand and being a small company, they completely fucked up the logistics the second time around too in incredibly predictable ways. Yes, they have a very difficult logistical problem, but none of it should have been a surprise and all of it should have been planned for.

We were supposed to be in the December wave of shipments. We got ours in January. This was well within our expectations, however there are still people from the first wave of shipments in June who haven’t received their stuff. I’m writing this on Feb 1st, and it looks like maybe 75% of the December wave people still haven’t received their shipment.

On January 31st I received an email from them saying “Your Wave 6 order was scheduled to ship by the end of December. Unfortunately, fulfillment is running late, and we apologize for any disappointment.” They then offer a $25 gift certificate as a form of compensation.

The thing is a) they don’t seem to know we already have ours. b) this came at the end of the month after the month it was supposed to have shipped. It should have been sent around the 1st of January not the 31st.

Where then?

I don’t know. Carolina Game Tables seems like the most visible alternative, but while their thick edges may be comfortable for resting forearms on it’s going to require you to reach a lot farther to interact with anything in the table. The thinner edge of the Wyrmwood table is not uncomfortable and allows you to have your cards and dice much closer to you.

ATMA TTRPG Review

Sun, 28 Jan 2024 00:00:00 -0500

Table of Contents

Overview

ATMA is a rules-light no prep Tabletop Role Playing Game (TTRPG) that requires significant improvisational work by all players in order to figure out how anything fits together. The mechanics kind-of work but leave you making up a lot of rules on the fly because they don’t cover a lot of common things.

Like most TTRPGs it’s based around the idea that you’ll go places, bad things will happen, and there’s a good chance you’ll have to fight bad guys to resolve the problem. If you want a good quick overview of the setting and how this game works, I recommend you check out this short 5 minute video, because this post is more about the details than the high-level stuff.

Disclaimer: after writing this whole thing I just feel drained and don’t have the energy to spend another hour editing it. My apologies for any repetition, rambling, or run-on sentences.

Some Perspective

Before I get into this, I feel I need to share the perspective I’m coming from. I refer to myself as a “frustration driven developer”. This true for both software, and game development. What’s notable is that the things that really frustrate me are the things that could have been really good, but were left in a state that just… isn’t.

It should also be noted that I’m a total nerd when it comes to game mechanics. I love learning new ones, and really understanding the tools available for RPG design.

ATMA has great bones, but it is missing a lot of important tools, and has many internal contradictions. This frustrates me greatly, but again only because it could be great.

First, Something Good

The game absolutely lives up to its claims of being a “no-prep” RPG. The setting is fun. It’s nice to just have the game tell you “stuff is happening here” and having the next scene be thought up by the game is also nice. The characters have nifty backstories. It’s cool to have art to give you an idea of your character and the characters they encounter.

It’s nice that each box is usable by itself, and that none of the boxes contain the same cards. It should be pointed out that the “Interlude” box is in no way an “interlude” between Act 1 and Act 2, or anything else. It’s just a tiny version of the Act 1 game with less cards that can be combined with Act 1’s cards and / or Act 2’s.

Is this a fighting game or not?

I made the assertion to Dachary (my wife) that this game was a “combat focused game” that expected you to go from scene to scene and usually fighting to resolve problems. While playing we managed to resolve one scene without any combat. We also learned that there were characters who were completely useless in combat situations.

Afterwards, she countered that it couldn’t have been intended as a “combat focused game”, because there are multiple characters who have no combat abilities. Unfortunately the same argument applies in the other direction because there are characters who are exclusively combat focused.

Our first scene was a cooking contest, and the possible goals were to win the contest, or stop an extortion attempt. The combat focused characters are going to suck at the former and the latter has a decent probability of erupting into violence.

This implies you could pick non-combat characters and choose non-combat goals. However, the “Story” card defines your overall goal and doesn’t let you pick. Ours was “Sabotage the weaponized army of [robots]”. That could theoretically be accomplished without combat, but that seems very unlikely unless you’re telling the story of a spy spending months or years to get into position.

Everything’s contradictory

Some of the characters are 100% combat focused. They have zero non-combat moves beyond the ones everyone has (Realize, Coerce, Survive). Some characters are useless in combat situations. They have zero combat moves beyond the ones everyone has (Rumble, Barrage).

The GM never rolls. NPCs never roll to attack. Instead the GM spends a token to justify the action, and players roll to “Survive”. Cypher System clearly demonstrates that games with “player-facing” rolls like this can work well. However, there’s no mechanic, or even guidance, in ATMA that supports NPCs in conflict.

Many of the cards clearly show that NPCs can be allies. However, in situations where a Player would roll to see if they succeed the NPCs have to spend a token. BUT tokens are the only currency the GM has to complicate the lives of the characters (make the story more interesting) and spending tokens for an ally to help the players directly undermines this ability.

The game clearly wants you to be able to get into a fight, and conveys that some characters are big and powerful and some are small and weak, via both art, character abilities, and different characters having different amounts of health. Mechanically however everyone does exactly the same amount of Harm when attacking. A titan with fist that look to be the size of Volkswagen Beetles can successfully punch a skinny human teen with no defenses and do 1 harm. The skinny human teen with no weapons or combat abilities can punch a massive robot and do 1 harm. The combat mechanics around damage completely undermine the narrative fiction.

You can take harm, but there’s no mechanism to heal. The quote below is the literal entirety of the healing rules.

If [the characters] need medicine, food, or supplies to heal, offer hints about where these might be found in the scene.

Missing tools

Sticking with the problem of healing for a moment. We have no idea what the effects of “medicine”, “food”, or “supplies” to heal are. It’s a sci-fi game so we could assume some “med pack” thing that inexplicably heals things, but how many hearts does that heal? Why would “food” heal a character who was stabbed? How do “supplies” help? Can any of this be used during a fight?

As mentioned before, there are no-tools for handling NPC conflict of any sort, and no tools for NPC allies to do anything. It’s clear that NPCs can be allies, but if an NPC has special abilities it requires the GM to spend a token to activate, which again undermines their ability to make things more “interesting”.

Drawing NPC cards randomly requires either a GM with master level improv skills OR a mini brainstorming session where the table tries to come up with some plausible explanation for why this character just appeared and what they want.

Most GM-less games address this with something like an “oracle”. This is usually two tables that you roll on. One is a “descriptor” and one a “subject”. You ask a question and roll on the table. For example “why did this food delivery person suddenly enter the scene?” I just rolled on one of my oracles, and it said “threatening location”. So, maybe they’re a robber who is just disguised as a food delivery person to gain entry. It still requires a little improv, but it’s not like the game’s saying “Fuck if I know. You figure it out.”

ATMA requires you to constantly do real work to figure out everything. In “Theatre of the mind” games like this you need to establish a shared narrative space that makes sense to everyone. The physical locations of each individual in the scene may not be important, but everyone needs to share the same understanding of what’s going on, and what the character motivations seem to be. It also has to be something they can all “buy in to”. If you’re thinking “This makes no sense. They’d never do that.” then you’re going to have a really hard time engaging with the game.

Combat is also missing a ton of important information. For example: I had a special ability where I could punch my huge fists into the ground and cause an earthquake. This was visually depicted as a huge rent in the ground shooting away from me in a straight line. So… could I effect multiple NPCs with this? Did they have to be in a line. The canon weilding bear’s ability specifically states multiple characters are effected. Mine mentioned nothing like this. We had to make a ruling on the spot. We decided “multiple, but in a line”.

Dachary’s character’s hair seemed like maybe it was prehensile, but it wasn’t stated. We ruled that it was. It was drawn as standard western female hair length but the cards said it could be used as a rope. This implies it could get longer. How much longer? These questions actually came up in play and had to be decided or kicked down the road to be discussed again later. We ruled that it was long enough to use as a rope across a passageway, and punted on the question of how much longer it could get.

By itself these aren’t big problems. They’re easy to rule on the fly. The problem is that you’re constantly having to do this. Imagine playing D&D but literally every spell and special ability is missing critical information like that. Not only are you constantly designing the game as you go, but you’re defining house rules about every ability than you now need to keep track of for the remainder of the game.

What happens if someone at your table wants to use that character again in a game months later? You probably didn’t write all those home-brewed rulings down. You’re going to have to do the work all over again, and sometimes you’ll rule differently and then someone’s going to get confused about what’s possible because things worked differently last time than this time.

Nonsensical cards

The “Props” and NPC cards are especially problematic.

NPCs were were kinda neat, but most of them made absolutely no sense once a scene was in motion. Imagine you’re playing out the fight in the beginning of Star Wars. The Empire’s forces have boarded the ship, laser bolts firing everywhere, they’re about to capture the princess, and suddenly Donald Duck walks into the room wearing only a bath towel. Or, maybe, a volcano erupts, and threatens a nearby town, that you’re obviously not in because you’re on a star ship. I’m not exaggerating. It’s that level of random w.t.f.

We ended up reading ahead and picking NPCs manually because most of them made no sense in the scene. When we eliminated them and needed to introduce a new NPC we just said “uh… I guess another one of those appears?” because none of the remaining cards made any sense given what had transpired.

“Props” were mostly useless. One was a mug of spicy chai. They either needed to be worked in as a scene was revealed. Like “oh, there’s um… a spicy chai vendor in this outdoor plaza”. Or else it was like “You just got out of a fight, and the room is filling with lava, but as you look around you notice a mug of spicy chai.” Both require effort to come up with a justification for, and both leave the players going “What?!” or “uh… ok? I don’t know what to do with that information.”

Invalidating Player Abilities

“GM Intrusions” is a term I’m borrowing from Cypher System, because ATMA has no term for this mechanic but uses it. In Cypher System (also FATE, and others) the GM offers the player some resource they can use in exchange for introducing a complication. In ATMA the GM can spend a token to say “yes i know you rolled successfully, but I’m invoking something that partially or fully invalidates that success” Tokens are a GM only resource so the player can’t do anything with it, and they have no means of refusing the intrusion.

I was the managing most of the cards in our game so I just ignored this because taking away player agency is bullshit.

In addition to this, the lack of GM rolls meant that the GM only has to spend a token to get around any kind of obstacle. For example, I had gravity spikes that people “fell towards”. I lined them up to create a barrier to hold back the bad guys. The GM never rolls, and spends a token to have the NPCs do anything and literally can’t fail if there’s no player roll to counter it. So, as a player you throw down your gravity spikes to slow the enemy and the GM says “ok, I spend a token on my turn and jump over or push through them”. What’s the effing point of giving me powers if the GM can just spend a token to ignore its effect?

The token economy is broken

It’s like, really broken. The instructions tell the GM to try and not keep more than three tokens. So, you’d be constantly spending them to introduce bad guys in a fight, or environmental complications. Tokens are generated for the GM on every roll that isn’t a critical success. So, they’ve got a LOT of tokens coming in that need to be spent.

In a fight this works if the number of bad guys is roughly equivalent to the number of Player Characters. If we have 4 characters on each side of a fight then the GM will spend ~4 tokens each round, and roughly 4 tokens will be generated each round.

We were playing it as a two player game, which is officially supported. Every scene is started with 3, 4, or 5 tokens + whatever you had from the last scene. Every round of combat we generate ~2 tokens. Let’s assume the GM starts the scene with 8 tokens. They either they need to bring out a lot of adversaries to spend them or introduce a lot of “props” or “twists”. You don’t want to introduce more than one twist per scene, and the props are mostly nonsensical and/or contextually useless.

My character had 3 Hearts, Dachary’s had 2. Adversary hits do 1 Heart of damage. Actually we don’t know this. It’s never stated. We’re just assuming, because if they did more than that her character would be taken out with a single hit and mine with two.

This means that if there were a lot of bad guys one of two things would happen. Either, we’d get eliminated very quickly, or the GM would spend all their tokens attacking us, we’d get lucky and dodge, and then half of the NPCs wouldn’t be able to do anything every round afterwards because we’re only generating 2 tokens but there are 4+ opponents. The GM isn’t receiving enough tokens to spend to have them do anything. Eventually, by having each opponent act, the GM spends down to an equilibrium that matches the number of characters or is slightly below it. They’re screwed.

If the GM is managing an ally NPC then they’re screwed even more quickly, because the ally will also cost a token to act. NPCs don’t roll, so having an NPC ally means having a guaranteed successful attack (no roll so it can’t fail), that also takes away an action from the GM.

Missing what makes PbtA great.

One of my favorite things about “Powered By The Apocalypse” (PbtA) is the playbooks. Every character has a description, and some special moves that not only made them special, but also really gave you a feel for the character. ATMA does give you a feel for the character via the backstory on the back of each special ability card, but the abilities themselves don’t feel like they really tell me about the character. The cannon weilding bear can bite things, and shoot its cannon. This doesn’t help me feel the character at all. The teleporting teen can… teleport.

The Titan I played did kind-of achieve this, but it was also contradictory. My backstory said I had been mind controlled and forced to hurt people and I felt bad about that. Meanwhile one of my special abilities was to embrace my violent past, and slam my fists into the ground. Afterwards (or separately? I don’t know.) I could “deny mercy” and “sow terror” or “incite hatred”. Am I a violent raging ass-hole, or am I a repentant person who only fights when forced to?

It would have made much more sense if the special move left me shaken about reverting to my past ways, or something like that.

Despite being mind-controlled for years, one of my abilities was to posses others. No-one who’s been mind-raped for years and forced to do things against their will is going to be comfortable mind-raping other beings unless they’re just a horribly broken being that needs to be eliminated for everyone’s safety. Even if we completely ignore the safety issues around this topic, it just doesn’t make any internal sense. In their defense they did get sensitivity readers for the “Act II” set, so hopefully there’s no more of this in those cards.

Conclusion

This game really frustrates me, which is another way of saying that this game has great potential.

I am fortunate to have a wife who’s amazing at coming up with stories on the fly. This helped a lot, but - without exaggeration - we spent at least half of our time trying to figure out why everything was happening, and trying to figure out what the hell ever card we pulled had to do with anything.

We’d paused before the final scene because dogs needed walking. The next day, we wanted to see how the story ended, but by the time the final climax was reached and we were starting to vanquish the bad guys I did not have the energy to give a shit. I had spent so much time, and energy trying to come up with explanations for everything and constantly having to come up with new house-rules for everything our characters tried to do, that I just didn’t care. It was like “…and the last two guys run away and [quick illegal roll for an NPC] the Magistrate barely wins the election and eventually all is well with AIs and non-AIs. The end. I don’t care. I just want to put away the cards.”

This game could be really good. Every mechanical problem it has is something that was solved years ago by other talented designers.

It doesn’t seem to know if it wants to be a fighting game or not, and the characters all feel completely unbalanced. Either they’re all about fighting or they’re useless in a fight. The ones that’re useless in a fight mostly have no skills that’d be useful in a game about social conflict.

The character’s special abilities all need to be rewritten so that you don’t have to create a house-rule for all of them. Is the hair prehensile? Roughly how long can it become? Can the teleporter teleport places they haven’t been?

The combat needs to match the narrative. It completely breaks me out of the fiction to have a huge titan smashing a tiny teen human do exactly the same damage as a tiny teen human with no fighting abilities punching a massive metal robot.

The description needs to match the images and be internally consistent, and consistent with the other elements of the world. The “Warmech Veteran” is drawn with a human and a robot. The description is about a robot who “suppressed their higher level functions like logic and speech” but it can “befriend another fighter” … isn’t friendship kind-of a higher level function? What’s the deal with the human? Are they a pair? The robot is drawn with some sort of missile launchers on its back, but are they unlimited missiles? does the missile hurt only one character if it explodes beside them? What does it mean that it can it “ride upon missiles”? Why does a big robot that’s obviously designed for war, only have 2 hearts when a squishy human also only has two hearts?

Speaking of hearts, why do some characters have multiple separate lines of hearts and some only have one line that may be long or short. Does that separate line mean something? Does something happen when all the hearts in one line are removed?

I hate that it has forced me to either ask these questions and come up with house-rules for each, or say “fuck it none of these rules make sense, no-one understands what my character or the enemies are actually capable of, and I have to just accept it”?

I don’t think this game is good for new players if any of them are inclined to actually consider the implications of anything written on the cards. If you have players who embrace “don’t think about it.” and are really good at collaborative improve you’ll be fine. Otherwise, I can’t recommend this. It just requires way too much work, because it defines way too little, and doesn’t provide the support you need to make generating the story easy.

On Generic TTRPG Systems

Fri, 26 Jan 2024 00:00:00 -0500

Table of Contents

Overview

I love the idea of generic role-playing games, but as time goes by I find myself caring less and less. Yet, there’s still something great about them. This post explores those thoughts.

Context

The basic premise of a Generic Tabletop Role-playing game is that you can learn this one system, and then play any kind of game with it. No need to learn new rules. Just throw together some new characters for whatever setting you and your friends have decided to have fun in.

I currently own the following generic systems:

Cypher System
D6 System
FATE (Core, Condensed, and Accellerated)
Fudge
GURPS
Genesys Seemingly abandoned for years, maybe about to come back to life?
Heroes & Hardships
HeroQuest (now called QuestWorlds) The Robin D. Laws game. SRD here.
ICRPG It’s debatable if this is really a “generic” system.
Savage Worlds
TinyD6
True20
Unbound
and some others…

When I step back and think about each of these it becomes clear that, with the possible exception of GURPS and HeroQuest none of them are actually trying to let you play any kind of game. Each of them has an inherent idea of what a “fun” game is and then gives you tools to play that kind of game in any setting.

For example, FATE has the baked-in assumption that your characters are very competent people who are each especially competent in at least one area. It’s really difficult to use FATE to play characters who are really flawed and not good at some things.

It’s all about the fighting

What I’m coming to believe is that most of these aren’t really Generic Game Systems. They’re just codified rules for a specific flavor of combat.

Someone I respect recently posted about a Kickstarter for a generic system they were helping to make a new version of. When I went to check it out I found myself just not caring. They obviously enjoyed playing it, and it might be a really good system, but a quick glance at the old version made it clear that this was just another codifed flavor of combat. Sure, it sounded like a slightly different one but…

In these systems you can make any kind of character you want, in any genre you want, in any setting you want… so long as it’s a story that centers around physical combat, and “heroes” who solve problems with violence.¹

Now, don’t get me wrong. There’s something very cathartic about punching space-nazis in the face instead of waiting for your current flavor of failed government to do something about it. I’m 100% down for a good session of that, but there are other stories to tell. I want to play a grannie solving mysteries in a sleepy town. I want to experience what it’s like to be Bluebeard’s Bride, or a Thousand Year Old Vampire trying to hold onto their sense of self.

That’s where generic systems loose me.

I want more

I love some of these systems. I have great respect for many of the people behind them, but the world doesn’t really need another generic combat system. We’ve got plenty.

I want games that’ll engender fun experiences that aren’t focused on going places and killing people. Sometimes I want that, but not all the time.

The problem is hard

I don’t know that it’s possible to make a truly generic system. Robin came pretty close when he created HeroQuest, but that’s partially because there’s hardly anything to the system. GURPS is flexible enough that it might do a pretty good job of letting you pretend to be grannies solving crime. Again though, this is largely due to the fact that there’s very little to GURPS. Sure, there are tons of books and tons of very specific options in those books, but at its heart it’s a very bare-bones mechanic.²

Even so, both of those are going to impart a certain flavor to whatever game you play with them.

It seems like the key to making a really generic system is to make a system that barely exists. The problem with that, is that when everything is just “roll the standard test vs difficulty & apply modifier” or whatever the game stops being about anything.

I think Tiny D6 is a good example of this. There’s so little to the system that you can do anything with it, but there’s also nothing interesting about rolling the dice. Maybe you succeed. Maybe you fail. The odds are roughly the same all the time and the game mechanics never leave you particularly surprised or excited.

It seems to be intended for young kids, and I’m betting it’s great for them. I’m not a young kid though, and neither are you.

I want a game where there’s a good chance I could fail at some things, and a good chance i could be amazing at others. I want rolls to be interesting. I want to actually worry that my character might fail to do something important. Most of the games in my list do that. However, the better they are at that, the more influence they have on the story being told. They flavor it.

As soon as your game imparts flavor, it’s no longer generic, and some types of stories cease to be supported very well. I think recreating Yazeba’s Bed & Breakfast in Savage Worlds would be an utter disaster.

If they’re not really generic…

If your table is not single-mindedly focused on only role-playing combat focused stories, then there isn’t a particularly good reason to invest much time in a generic system. It doesn’t matter how much you love the system if it’s not good at supporting the next kind of story you table wants to experience.

Even if you are only looking for combat-centric escapism, I think it’s worth asking yourself if you really only want one kind. There are so many amazing flavors of action movie. Do you really want to only play John Wick type stories with different set-dressing?

As soon as you realize that you want more than one flavor there ceases to be much point in investing much energy into a generic system.

Now, don’t get me wrong. I love Savage Worlds. I’ll happily play in any game a friend wants to run in it. But I also love the feel of stories that emerge from playing Starforged, or Brindlewood Bay.

If there’s a generic system that produces the type of game you prefer, and that’s mostly what you play, then go for it. What I’m suggesting is more that we should really reconsider the whole idea of a “Generic” TTRPG, because they’re generally pretty bad at supporting “any” type of story. Mostly, they’re just good at supporting a specific flavor of combat.

Maybe we should be reframing them as “generic combat systems”, and working from there.

To be explicit, some of the games I listed - especially FATE & Fudge - do a really good job of supporting combat-free games. But, that doesn’t make them truly generic. ↩︎
HeroQuest and GURPS are both marketed as combat focused things, but that’s also the kind of escapism that TTRPGs were used for when they were created. That hasn’t changed much. There are very few high-profile games that aren’t about killing “bad guys”. I think they both deserve more attention than they get, especially HeroQuest (QuestWorlds). Although, I should note that there was some weird business decisions that shoe-horned some RuneQuest terminology into HeroQuest’s rules. It feels very out of place, and just confuses things.

GURPS has a reputation of being crunchy-AF, but the reality is that it’s only as “crunchy” as your table wants it to be. The minimal version of it is one of the simplest RPG systems out there. ↩︎

Recycling 3D Prints

Wed, 24 Jan 2024 00:00:00 -0500

Table of Contents

Overview
Shredding
- Gotchas
Extruding
- Gotchas
  - Color
  - Materials
  - Thickness
  - Winding
Pelletizing
Summary

Overview

Despite being “plant based” there are almost no 3D printer filaments that are actually compostable or biodegradable in any meaningful way. PLA needs oxygen, a temperature of 140+°F (60°C), and a variety of organic compounds to break down. You’re not going to find these outside of an industrial composting facility and most of them won’t take PLA anyway because it’s frequently mixed with other things that make it non-compostable.

Fortunately PLA is completely re-usable. You “just” need to melt it down and re-extrude it.

UNfortunately, that’s a lot easier said than done.

This post describes what it would take for a home user convert your old prints into new filament to make new things with. It was written based on the tools available in January 2024.

Shredding

The first step in re-using the plastic from old PLA is shredding it. To do this you need a bunch of specifically shaped disks made out of hardened metal that will chew your old prints into little pieces. You’ll also need one or two motors with a lot of torque to force the “teeth” of those disks through a block of plastic. The bigger the opening the more cutting disks you need, and the more powerful the motors need to be.

The SHREDII 5s is the most capable thing i’ve seen in a price range achievable by most people. It’s $1,400 BUT you also need 2 identical motors with enough torque and that’s roughly another $1,800. It can only handle something about the size of a soda can. It’s made by the folks on the ActionBox YouTube Channel who have videos of its use, and the prior generations that led to it.

I don’t know of any off-the-shelf shredder that I’d bother buying. They’re either industrial things that are ridiculously expensive, or hobbyist things that can only shred things that are stupidly small. You’ll never be able to shred anything but the tiniest of prints, test strips, and brims.

There’s not a lot the community can do to improve the cost of the shredder. High torque motors are expensive and no-one really wants to build one from scratch. There’s nothing terribly complicated about the shredding part. It’s just some hardened metal disks with vaguely saw-like teeth on two rods that rotate in opposite directions. You can definitely get the cost down significantly if you have the right tools and are willing to put in the effort.

For comparison, here’s a 4 minute overview of the $9,000 Filabot Reclaimer which can’t handle pieces larger than 3" (~7cm) and has feeding issues with many things that are smaller than that, requires 2 stages of shredding, and warms up enough to cause low temperature materials PLA to clump together, exceed it maximum size, and clog within a few seconds.

Gotchas

Cleaning out all remnants of things you’ve shredded before isn’t easy. If you don’t do it, you’ll get small pieces of past filament colors mixed in with the shreds of the current color.

Extruding

A pre-made desktop extruder is going to cost $3,500 (USD) or more, but there are kits available for homebrew ones that will cost you about $600 to put together and provide very usable results.

At the time of writing the Arteme 3D Mk2 is the best one I’ve seen. [Note: when visiting that site you can change the language at that link by clicking a wee flag at the top.]. Unfortunately there’s no “good” way to measure the thickness of the new filament you’re extruding. It’s possible, but not easy.

This YouTube Video by CNC Kitchen does a good job of showing off the Artme 3D and compares it to a ~$3k machine. The $3K machine definitely seems less hackey and produces more consistent seeming results.

It’s decent enough for a small-scale home setup, but there’s a lot the community can do to improve it. Incorporating something like this cheap (~$5) open source inline filament sensor would be a huge improvement, but would require some programming and electrical engineering to give you a display of the current diameter, or better yet, incorporate it into a speed controller for the extrusion process. Professional extruders run the filament through a water bath to cool it off quickly, and something like that could be incorporated too although it’s probably overkill for this low-speed extruder.

The mixing bin is, in my opinion, completely inadequate for anyone who actually wants mix things to control the color of the resulting filament. In that case you’ll definitely want a separate mixing setup that does a way better job than a human with a big spoon.

Some of you may be thinking “but there are really cheap (~$200) extruders on Ali Express”. Please watch this video from Slant3D going over how amazingly useless the cheap Chinese extruders are. The one they got currently sells for $1344 and was barely functional.

Gotchas

Color

Mixing filament colors is just like mixing paints. Mix enough colors together and eventually you end up with something brown or black. So, you’ll need to keep your filaments separated by color unless you don’t care what color the new roll is.

Intentional Mixing

Unless you’re really careful about keeping your shredded filament colors separately you’re going to be mixing colors. If you’re mixing colors you’re probably going to end up with banding from uneven mixes. It turns out this is a hard problem. The folks over at Protopasta do this for a living, and they still have problems with it. As a result, they mix new colors and put them through one extruder, then shred the results, and re-extrude them in another extruder. Here’s a link to where they talk about this in a factory walk-through.

Creating Custom Colors

Probably the coolest thing about having your own extruder is that you will no longer be limited to the colors you can buy from other manufacturers. You can buy the raw resin pellets in bulk. Then buy whatever pigments you want and mix them together. You can add in sparkles and anything else. The only “gotcha” here is that if you haven’t done so before, you’re going to have to spend some time learning basic color theory as it applies to mixing pigments. At a high level, everything they teach about mixing paints is applicable here, with the caveat that mixing pigments with plastic is probably going to be about as different from paint as mixing watercolors is from mixing oil paints.

Materials

Many manufacturers mix things in with their PLA. Because of this we don’t really know what happens when you re-melt and re-extrude them until you try. Additionally different filaments melt at different temperatures and extrude differently. Personally I’d stick to only re-extruding simple PLA and PLA with sparkles until you’ve done some research about the compounds involved.

Note that PLA+ is not the same as PLA and the “plus” could represent the addition of just about anything. There’s no industry standard around the term. So, you can’t mix the two and you can’t - or at least shouldn’t - mix PLA+ from different manufacturers.

Thickness

If your newly extruded filament is too thick it’ll clog your nozzle. If it’s too thin… well I don’t really know what that does, but i suspect it’d heat too quickly and give you the same result as printing with a nozzle temperature that’s too high. If the thickness is inconsistent you’re just screwed.

I do not like how the Arteme 3D MK2 handles the problem of measuring your filament thickness. I hope the community comes up with a good improvement in the near future. Right now it seems to produce filament that’s “mostly close enough” in the thickness department. I wouldn’t use it for anything where precision extrusion mattered in the final product.

Winding

Winding your new spool well is really important. I’ve gotten multiple cheap rolls from cheap Chinese manufactures that are wound poorly, get bound up and snap because they won’t unroll anymore until you get your hands involved. The homebrew winding solutions seem to work reasonably well, but i figure there’s got to be more to it or else even the cheap companies that do this for a living wouldn’t be screwing it up.

I’m not thrilled with the winding solution of the Arteme 3D MK2, but you could either respool it with some of the more elaborate 3D printable solutions, or you could integrate something into a hacked version of the Arteme.

Pelletizing

Not technically required, but if you want the best possible results my understanding is that you’ll want to shred, extrude, pelletize, and then re-extrude. Pelletizing is basically just making them into uniform little pellets that’ll help your re-extrusion process.

Summary

All in all you’re looking at about $3600 and some kit building to get started. If you already have a CNC that can work with steel you could save about $1400 on the shredder part, and maybe even make a bigger one, but you’re still going to need 1-2 high-torque motors. With a setup similar to the SHREDII you’re going to have to spend time cutting your old prints on a band saw or something to make them fit into your shredder.

Once you’ve got all the pieces you’ll have to be diligent about keeping your old print material separated by color and material type. That means a lot of bins, and that means a much longer time before you’ll have enough waste of a specific color and material to make a new spool. You’ll be much better off if you don’t care about color and just want to reuse material for test prints. In that scenario you only have to keep things separated by material.

You’ll need to clean your shredder after each use, which is probably best achieved by running some clear PLA resin through it. A little bit of that left in the system shouldn’t significantly effect the color of the next filament you shred.

If you don’t want random color banding in your prints you’re going to need to come up with a good mixing solution, and probably extrude your newly mixed color, shred it, and then re-extrude it.

All of this is very fiddly. It takes a lot of time, and it requires energy to shred, mix, and re-melt all your stuff. It requires energy and raw material to make the shredder and motors and extruder and electronics and everything else.

Right now home re-use of filament is doable, but it’s a lot of work. If you’re not generating a lot of PLA waste, I doubt that the small amount of material you keep from a landfill will compensate for the environmental impact of making all the things required to do it. At the same time, we need hobbyists to be willing to put in the time and energy to try this so that we have people iterating on the tools available to the wider community.

I don’t think you should bother with this if you just want to be a little more green. I don’t think that’s realistically achievable with the current tools. Please do try this if you’re a tinkerer who is interested in spending the time to iterate on what we have, and find a way to make it better for others, so that - eventually - something exists that actually does make a difference for everyone.

Debugging Our Ambulance

Fri, 08 Dec 2023 00:00:00 -0500

Table of Contents

Debugging Our Ambulance

tl; dr: two developers use standard debugging techniques to fix electrical problems in their ambulance.

Setting The Stage

We had to drop our car off at the dealership last night. In order to avoid walking home in the dark, on roads without sidewalks, in 27°F (-2.7°C) - or just the last two shortly after dawn, we needed to drive the 🚑 Ambulance. Unlike most years, I actually remembered that it had a block heater¹ and had turned it on at the beginning of winter.

Because it was so cold, I went out in the morning and double checked that that the block-heater was turned on. It was. What I didn’t check was the voltmeter².

The Problem

That evening - in the cold, and dark of winter - I hopped into the 🚑, turned the key, and… nothing. Literally nothing happened. I looked over to the voltmeter and understood why. Zero volts coming from the batteries. Nothing to power the ignition.

A debugging we will go

Gather the initial known truths

The ambulance has 2 separate electrical systems. There’s the 12v DC system (normal car stuff) and the 120v AC system (normal “house” electrical stuff).
An Inverter takes DC power from the batteries and converts it into AC power. This is not very efficient and you loose a fair amount of power along the way even with an expensive inverter like the ones they use in ambulances.
A Converter takes AC power and converts it to DC power.
There’s no reason you can’t have an Inverter and Converter in the same physical device.
The voltmeter reads 0 volts.
The system is acting as if there is no power.

We don’t know where the AC in from the side of the ambulance goes. I suspect it’s in our wiring diagrams³ but we haven’t hunted that bit down yet.

Propose Theories

the batteries are “dead”. They aren’t set up as some assume. See footnote.⁴
the batteries are disconnected.
the ambulance isn’t getting power from the house.
- The house plug is bad.
- The cord is bad.
- The ambulance plug is bad.

Choose A Theory And Test It

Eliminate things you can test rapidly.

I started with the second theory - despite it being unlikely - for three reasons: First it could be eliminated in under a minute. Second, because I’d recently replaced the batteries and they live in a slide-out drawer - 🚑s are weird - and its possible one of the leads came loose. Third, because I was already outside and didn’t need to go inside to grab anything to test this. A battery lead being detached is very unlikely to be our problem, because even if it did, each lead is clamped into two batteries. So if it comes off of one post it’s going to still be clamped onto a second one. Two batteries gives us redundancy, reliability, and more available power in an emergency when the engine has stopped running, and thus the alternators aren’t generating any DC power.

The leads were very well attached to the batteries. I couldn’t guarantee that the far end of the leads were well connected because I don’t know where they terminate, but it’s very unlikely that anything has gone wrong there. They’re very thick wires and would need significant clamps to hold them in place.

Work on probable things.

The batteries being dead is the most likely. It’s so likely that we just worked with that as a default assumption, and moved on to the third theory.

The house plug had a self-test light, and GFCI test & reset switches that all seemed to be working. We also had a plug-in AC outlet tester which was easy to grab confirmed. So, it was reasonable to temporarily eliminate it as the problem.

It’s difficult to test if the plug on the ambulance is working because we don’t actually know what it connect to inside the ambulance. It’s probably in our wiring diagrams, but even if we did know, it’s unlikely that we could reach it without disassembling parts of the ambulance.

Next was the cord. Testing that required a multimeter. We couldn’t find our “good one”, but we had an ancient Radio Shack one that still had power. A quick trip to YouTube to make sure we were using it correctly for AC wall power, and we confirmed that the cord was transmitting power. We tested this inside in the basement which was both well-lit, and significantly warmer.

Because we couldn’t easily test that the 🚑 was receiving power via its plug, we had to just assume - for now - that that was still good.

Since we had the multimeter in hand, it made sense to eliminate some things that had just become quickly testable: the batteries themselves. They were - unsurprisingly - dead.

We tested the AC plug on the Inverter (for sending power out). It worked. Since the batteries were completely dead, and the outlet had full power, we could reasonably assume that the power was coming from the cord to the house, which meant that power was successfully entering the ambulance and being used by things in it.

Generate new theories
- State of Existing / Old Theories
  1. ✅ the batteries are “dead”.
  2. ⛔ the batteries are disconnected.
  3. ⛔ the ambulance isn’t getting power from the house.
    - ⛔ The house plug is bad.
    - ⛔ The cord is bad.
    - ⛔ The ambulance plug is bad.
- Evaluating What We Learned
  
  We have to assume that the power system from the socket on the wall of the 🚑 to whatever it goes to is fine. It’s been sitting still for months, and is unlikely to have had a problem. We’re also assuming that the other end of the battery leads are still connected. Both of these are too hard to test, and too unlikely to bother trying.
  
  The batteries being dead isn’t surprising. It explains why we couldn’t start. It also raises two questions
  - Why are the batteries dead?
  - What can we do to give them power?
  Normally, plugging it into the wall is all we need to do to give the batteries a trickle-charge that’s significant enough to overcome the normal phantom draw.
- Another Quick Test
  
  We have a lithium jump start battery pack for the car. It was our belief that it didn’t provide enough power to turn over the engine, but it was something we could test quickly. It’d be great to be wrong about it.
  
  When I connected it to the batteries, the ambulance lit up like a Christmas Tree. Thus confirming that the batteries were well connected to the system. Turning the key “worked”, but as suspected there wasn’t nearly enough power to “turn over” the engine. I left it connected so that it could help the batteries out when we figured out how to get power into them. It drained very quickly. These emergency lithium jump-start batteries work by providing a lot of power throughput, but they don’t actually have a lot of power stored. It’s just a short powerful burst until the engine starts and can take over.
- New theories needed
  
  New theory: Power is making it into the ambulance, but not making it into the batteries.
  
  Batteries don’t have separate “input” and “output” things. DC power is like water. It just flows through the system, self-levels, and leaks out any “holes” (things using power) you may have. Since the batteries were well connected (still assuming far end is good) it meant that the problem was likely to be something in the electrical cabinet.
  
  I believe the batteries also go directly to the starter mechanism, but we’re assuming that that’s good, and investigating questions around getting power into them, not getting power to the starter. We need power to exist before we can bother giving it away.
  
  The problem with this theory is that it is too generic. It helps narrow down the problem, but it doesn’t give us anything specific to test, and the system has thousands of wires, a wall of relays, and many other things.
  
  We went back into the warm, and well lit house to think.
  
  Dachary proposed that we might have blown a fuse. The problem with this is that there are surprisingly few fuses in this system. Because we believed (reasonably) that all the stuff to go from “shore power” to the batteries was in the electrical cabinet, the problem with that theory was that neither of us could recall any fuses in there. One wall of the cabinet has a panel that opens behind the driver’s seat, and we think there are some fuses there. Unfortunately the seats don’t fold forward and it’s a pain to get to even when you can see well. Also, we didn’t believe those fuses controlled anything relevant.
  
  New Theory: blown fuse.
  
  Currently not worth testing, because we didn’t have any likely or easily accessible location to look.
  
  So, we got out the wiring diagrams³.
  
  At this point we’re thinking that the Inverter and Converter are in the same box. However, I’ve been bothered by the fact that it only says “Inverter” on it. If there is a separate converter I don’t know where it is.
  
  Dachary digs into the wiring diagram while I test something I can’t remember - I’ve probably just messed up the order of something here. She finds the Inverter, but it doesn’t mention a converter. The rest of the diagram wasn’t very helpful, but there was a reference to another diagram number though. So, I start hunting for that one. There I find two things: First, a separate mention of the converter, implying that it’s a physically separate device. Second, an indication that it’s wired in via a standard AC plug. That would have to be one of the plugs in the electrical cabinet.
  
  I head back out, and start re-examining the cabinet. As I’m looking around at the outlets and plugs and wondering where the converter could be I notice a large metal box that I’ve mostly been ignoring. It says “converter” on it. 🤦‍♀️
  
  I start examining the converter and notice that it has 3 wires going into it. AC is 3 wires (positive, negative, and ground) and DC is 2. Because a Converter is AC to DC this must be where the power comes in. The connector they used has places you can stick multimeter leads and test if it’s getting power.
  
  New theory: Converter isn’t getting power.
  
  I also notice a single automotive blade-style fuse hidden behind where those wires come in. It’s impossible to tell if it’s blown, and really difficult to access.
- Closing In
  
  I grab pliers to try and extract the fuse, and a multimeter to test if it’s getting power.
  
  I dive back into the cold and dark. It’s getting power! I attack the fuse. It’s blown.
  
  It’s a 30 amp fuse too. That’s a lot. If it hadn’t blown then “Bad Things™” would have likely resulted. E.g. 🚑 + 🔥… and then maybe 🏠 + 🔥.
  
  I stand up and reach into the cabinet with spare fuses⁵, grab a new 30v fuse, slide it in and the whole ambulance lights up again! I check the voltmeter and it’s back at the standard charging & running level of 13v, which means the batteries are being fed power now!
  
  After a couple hours of changing, it started right up.

Summary

Practicing a considered, and well structured approach to debugging is far more efficient than flailing wildly at random ideas that flit through your brain. It’s also very useful outside of software.

At each step of the way I literally stopped and restated what we knew the known truths to be, and ask what new information we could derive from the theories we’d eliminated or confirmed.

While we didn’t do a formal “post-mortem” to the “production incident”, we did create “action items” from it.

Buy a new multimeter. It doesn’t matter that we have a good one if we can’t find it.
Increase the priority of the existing task to measure, model, and 3D print a custom shroud to improve the water resistance of the 🚑’s outside plug. Rainwater in there seems the most likely cause of a problem.

Good debugging and Incident Management procedures help in your everyday life too.

For a good guide to debugging start with “The Pocket Guide To Debuging”, by Julia Evans.

For a good guide to creating your own incident management processes, start with Graceful Disasters, by me.

Afterward

(based on internet commentary)

The electrical systems in modern ambulances are nothing like those in cars, diesel trucks, or RVs. Unless you’ve helped manufacture these things, or have spelunked in the wiring of one first hand, your assumptions about how things work are probably wrong. Additionally, each one is a literal one-off-custom build.

I assure you that it’s very easy for a brand new starter battery to go dead in 6 weeks of cold weather if an ambulance isn’t plugged in. This makes sense if you understand the regulations these must meet to give you the best chance of survival in some extreme environmental conditions. It makes sense if you understand how they’re used by the EMTs and Paramedics.

Trust me when I tell you, that once we get beyond “Electricity 101” and Ohm’s Law, you should throw your assumptions about how this is wired or constructed out the window. We aren’t guessing about how it’s wired. We have ridiculously detailed wiring diagrams for this specific vehicle. Every wire’s insulation says what that specific wire is for. We know how things are connected. We just don’t know where everything is connected. To put it another way. We know that two wires meet at a junction, we just don’t know which part of the wall each junction is hidden behind.

A block heater is basically an electric blanket for your engine. This is especially notable for large diesel engines for three reasons:
1. diesel stops being liquid and turns to a gel when it gets cold enough. They actually change the formula in the pumps just before winter temperatures kick in. A diesel engine uses “glow plugs” to heat the fuel. I don’t know what they look like, but they’re essentially just little electric heaters in the fuel system. They take a lot of power, and a many minutes to make the diesel ignitable on cold days.
2. our engine is so large that even if you do manage to get it started in the cold it takes a long time to heat up all the metal.
3. diesel engines don’t have spark plugs. They combust the fuel by compressing it, which is harder to do when it’s a gel.
↩︎
Ambulances have dashboards with a lot of switches (see below). There’s also a voltmeter (the radial-dial). Unsurprisingly an 🚑 has a lot of electrical stuff going on. Unlike most vehicles there’s a non-trivial phantom draw. It will drain its two AGM batteries if it just sits around for a while. This is acceptable, because it was designed to be used literally every day. It’s also got a 120v AC input on the side (with a weird plug). We don’t drive ours much, but we do keep it plugged in.

The voltmeter is important because if yours is low, the EMTs and Paramedics in the back are going to have trouble using things like IV bag warmers and having lights to see what they’re doing. You want to know early if there’s a problem.

our ambulance dashboard

↩︎
Unlike most vehicles every 🚑 has complicated custom wiring. Every ambulance is custom built. What features you get depends mostly on how much your town is willing to spend⁶. Manufacturers need to keep track of what they put into each one so that they know how to fix it if it comes back for repairs. When we got ours, we called up the manufacturer, gave them our Vehicle Identification Number, and asked them to send us a PDF of the wiring diagram for our vehicle. ↩︎ ↩︎
The ambulance has 2 AGM batteries wired in parallel. There is not a separate “house” battery and “starter” battery. Within the US there are strict regulations about being able to maintain temperature in the patient area of an ambulance. Basically you need to be able to keep it cool in the middle of Death Valley in the summer, and you need to be able to keep it warm in the northernmost part of Alaska in the winter. You’d need a massive battery to be able to power the heating and cooling systems to achieve this for hours on end. Ambulance manufacturer’s don’t bother. Instead they just guarantee that that will work while the engine is running. In my case they accomplished it by using two beefy alternators. ↩︎
Of course we have spare fuses on hand. A) it’s an ambulance with a billion cabinets. B) It would really really suck to be stuck on the side of the road just because you didn’t have a fuse. Especially in a long distance (thousands of miles) trip like the ones we take. B) of course the fuses are right next to the electrical cabinet. Why would you keep them anywhere else? ↩︎
A new Type III ambulance - the big boxy ones with a van shaped front - starts around $150,000. Most towns sell them after they hit 100,000 miles. That’s how we got ours significantly cheaper. ↩︎

Red-Black Initiative

Mon, 30 Oct 2023 00:00:00 -0400

Table of Contents

Overview

This document discusses a new¹ form of managing initiative order for Tabletop Role Playing Games without math. It is, like so many game things, a combination of a number of existing ideas.

Red-Black Initiative (RBI)

Red-Black initiative does away with the annoying numerical accounting that most games start every conflict with. It allows players to work together to pull off exciting team-up moves. The adversaries’ actions are less predictable to players. It’s pretty fast.

Quick Rules summary

Token colors represent sides of the conflict. E.g. “We’re black. They’re red.”
One token for each character on the PC’s side of the engagement, and one token for each adversary, or adversary group.
Shake the tokens up. Dump them out. Work from left to right grabbing tokens and moving them into a row. Alternately, put them in a bag, and lay them out in the order you draw them.
Players decide which character goes when it’s their color. GM decides who goes when it’s their color. When two or more tokens of the same color appear side by side you can declare if they’re acting simultaneously or one after the other.  
Characters entering the conflict after it starts are inserted wherever you are in the initiative when they arrive.

What You’ll need.

In order determine initiative you’ll need tokens with a color for each side of the conflict. I recommend using glass beads, dice, or tokens from a board game. Because most conflicts involve only two sides playing cards work well too. The only problem is that it’s harder to shuffle a short stack of playing cards.

The Setup

For the sake of discussion let’s say that the Player Characters (PCs) are “black” and their Adversaries are “red”, and that we’re using glass beads. You’ll need one black bead for each character on the PC’s side of the engagement. For the adversaries you’ll need one red bead for each adversary, or group of adversaries. The latter is for games that have mechanics for attacking a group of adversaries as if there were a single target.

Put them all together. Shake them up or shuffle them. Spread them out in a line.

Who goes next?

Work through the cards from first to last. If it’s a black card, players decide which character goes. If it’s a red card, the GM decides. When two cards of the same color are next to each other you can decide if they’re going sequentially or simultaneously. Do whatever sounds coolest.

Introducing New Characters to the Fight

Often a GM will have reinforcements coming to a fight who arrive later. If there’s one, just insert a card of the appropriate color at whatever point in the fight they join. You can just stick them at the end, but sometimes it’s just cooler storytelling for them to appear in the middle of a round. If there are multiple characters you can insert all their cards in one block, or you can have the fight one by one. Do whatever makes the most sense, or is going to tell the coolest story.

Characters With Multiple Attacks or “Lair Actions”

Standard characters: Most games just have a character use all their attacks in the same turn. In this case nothing changes.

Characters that can attack during other characters turns: I’d recommend just letting the player manage keeping track of this like they would in any other initiative.

Lair Actions: Personally I like the idea of using a token for each one. As some actions stop being available, remove a token from the appropriate color. Alternately, just have the DM manage it the same way they already do in D&D, or anything else with similar mechanics.

Keeping track of where you are in the initiative

I like starting with a straight row of cards or tokens, then shifting them up a couple centimeters to indicate that that slot has been used.

Once per fight, or once per round?

With physical tokens like glass beads this is very fast. Scoop them up. Shake them up. Dump them on the table. Straighten them out into a line. Since there’s no math or accounting you can easily introduce some unpredictability into the game without a bunch of slow and annoying accounting.

Ultimately this is up to the table. Do what sounds most fun. If you like the unpredictability of not knowing what’s who’ll go when in the next round, then reset initiative every round. If your table prefers having less things to think about, then just set it up at the beginning.

Using beads, dice, or colored game tokens from a tabletop game.

I find this method to be the fastest and easiest because they’re easier to pick up than cards, and I can shake, and dump a handful of beads or tokens faster than I can shuffle a very short deck of cards. I just dump them on the table, and make a line out of them moving from left to right. You could also throw them into a bag and pull them one by one, but that’d be slower.

Meta-commentary

Advantages

Fast.
No math.
Allows players who want to think more tactically to set up cool team-up moves, or sequences of actions that build on each other.
Visually shows how many of your allies or adversaries will be going, and when.

Disadvantages

If your players are very passive you may have problems getting them to say “ok, I’ll go”. On the other hand, this may be a useful tool for encouraging them to speak up, and take action.
Doesn’t work with games that have initiative manipulation mechanics. For example, you couldn’t use this with Savage Worlds unless you prevented players from taking any of the abilities that allowed them to modify when they, or others go in the round.

Example usage

Example using red and blue glass beads.

Worksheet

For those who like something to help organize the chaos of a pile of colored tokens, I made a simple worksheet that looks like this.

Red-Black Initiative worksheet screenshot

Download the PDF or OmniGraffle file.

Inspiration

The biggest inspiration to Red-Black Initiative is Fantasy Flight Games’ Genesys System, and Star Wars games use a similar concept. In Genesys each player rolls, and “Initiative Slots” are assigned based on how well you rolled, but the slots for the PCs are usable by any of the PCs, not the one who rolled the number that generated the slot.

Why “Red-Black” Initiative

…especially if the color doesn’t matter? Because it sounds good, because playing cards are red and black, and because I’m a programmer and “Red-Black Trees” are a thing for us.

License

The text above is distributed under the Creative Commons Zero license. This basically means you can do whatever you want with it and you don’t have to give me credit. I only bother because there’s a chance you may end up working with a company whose lawyers are concerned about you being allowed to use text / ideas someone else came up with.

There has been a ton of creative thinking in around TTRPG mechanics for the past 40+ years. It is not only possible, but probable, that someone else came up with this idea long ago, and I’m just unaware of it. If you know of an older source I can point to, please let me know, and I’ll update this accordingly, and add in any relevant info from their version. ↩︎

Sexism in Tabletop Role Playing Games

Thu, 06 Jul 2023 00:00:00 -0400

Table of Contents

Overview

This post uses a recent Tabletop Role Playing Game (TTRPG) as a concrete example of the problems that still remain within our community. When it comes to including women, it seems that there are many things that “shouldn’t need to be said” but apparently still do. This post will say most of them.

If you’re a guy who enjoys TTRPGs, I ask that you read this with an open mind. If you find yourself feeling defensive, or upset, that’s a sign of internalized sexism or misogyny. It means you’ve got work to do, but that’s ok. We’ve all got internalized, and unexamined biases. The first step in ridding ourselves of them, is realizing they exist.

Diverse perspectives make for better experiences, and TTRPGs are an amazing tool for exploring aspects of our personality, and taking a moment to imagine what it’s like to live as someone else with different perspectives. Women are ~50% of the human population. We need to be including them in our play, especially when that play is imagining worlds that are also populated with women.

Definitions

misogyny: prejudice against women
sexism: discriminatory or abusive behavior towards members of the opposite sex
male gaze: the male gaze is the act of depicting women and the world in the visual arts and in literature from a masculine, heterosexual perspective that presents and represents women as sexual objects for the pleasure of the heterosexual male viewer.

Context

A while ago a backed a Kickstarter for a new TTRPG. The cover had a bit of “male gaze”, but while I don’t like it, i need to accept that this is still a male dominated community, and “sex sells”. It’s not uncommon to have a book that’s all “look boobs!” on the cover but actually pretty neutral inside. I crossed my fingers, and backed it.

What I received in the end made me very uncomfortable. The core ruleset it was trying to convey had promise, but i set it aside because of that discomfort. The other day I picked it back up because it aligned with some of the game development research I was doing. I told myself I could “push through” the “male gaze” that permeated the pages, extract the core info, and never look at it again. In the end I gave up. I was too upset. I was too grossed out.

Even if this game was amazing, I would never feel comfortable asking the women I play with to look at it.

If this came out in the 80’s, that would be the end of it. There was a lot of that back then. But this came out last year. We’re supposed to know better. Even those of us who grew up with Red Box D&D should have learned by now that you don’t treat women like sex objects.

Unfortunately, it seems we don’t know better, and I’ve encountered other recent cases of men in our community getting defensive when you dare to point it out.

It should also be noted that I grew up in art classes. I have seen, and appreciated countless depictions of nude women. I have absolutely no problem with sexy images of human bodies be they male, female, or anywhere in between.

It should also be noted that I am very specifically not addressing issues of racism, sexuality, or gender identity in this.

The game, and its problems.

If I could write this without calling out the game I would. I don’t want to slag it or it’s creator. I want to believe that its creator is a good guy, who just never stopped to think about these problems.

I need to use concrete examples though. Without concrete examples people will just nod their heads and say “of course”. “Of course women should be depicted equally”. My hope is that by using these concrete examples and explaining why they’re bad, some men will learn how their choices can be harmful, and contributing to the lack of women at our tables.

The Male Gaze

This is, by far, the biggest problem. The thing is, “sexy women” aren’t inherently bad. If you want a game filled with depictions of sexy people, go for it. As a species humans are sexually motivated. We think about it. We yearn for it. Most people enjoy seeing sexy depictions of the kind of folks they find sexy, at least when they’re in a safe space and it’s their choice to see them. The problem is if it’s only sexy women. The context you put them in can make it even worse.

So, let’s start with the biggest example. This is a rules-light game with three “archetypes”: Combat, Academic, and Social. Here’s how they’re depicted.

There’s so much to unpack here. The “combat” character is an alien so they may not be “male” but most people would assume “male”. By depicting the female “academic” in a thoroughly sexualized manner we devalue a woman’s ability to be respected for her mind. It says “sure, she may have an education, but who cares! Check out her tits!”

Social, is actually worse once you start to read the text.

A charismatic type would be someone who is outgoing, entertaining, and utilizes their personality to affect the world around them. Entertainers, bards, dancers, and whores would be examples of an entertainer class.

First off, it talks about using their personality to effect the world around them but places it next to an image of a woman who’s obviously doing some sort of sexy dance or pose to effect the people around her. So, the obvious implication is that a woman’s personality is her tied to sexiness.

Then we come to “whores”.

Women are never “whores”. It is an unquestionably derogatory word, and has been since long before this century started. Women may be sex workers, but they are never whores. In the USA, guys who have lots of sex are revered by other men. Women who have lots of sex are looked down upon and called “whores” or “sluts” by everyone.

I should not have to say this, but engaging in sex never makes you a “whore” or a “slut”. We are sexual creatures. It is normal for humans of all genders to want to engage in it.

This negative association of women and sex is also displayed in the “Erotic Arts” Skill.

Erotic Arts The character is adept at utilizing the services of sex, relaxation, and therapy.

The fact that “sex”, “relaxation”, and “therapy” are all considered “erotic arts” is both disturbing and telling. While “sex therapy” is a thing, and sex can be both relaxing and therapeutic, relaxation and therapy are generally very asexual practices. They’re also incredibly valuable practices to mental health. You should be able to relax without it being sexual or erotic. This is even more true for therapy.

This tells us that sex is a tool. The fact that the only sexualized characters in the book are female tells us that sex is a tool that women use. While there are no depictions of relationships in this book, it’s pretty clear that the implication is that women use this tool on or against men.

Comparative Representation

This book follows the not-uncommon trend of visually depicting a handful of archetypical characters in multiple scenes.

The men are always fully clothed, or covered in armor. The only exception is the Orc adversary who is depicted as a more primitive barbarian in an armored loincloth. I am very specifically not going to dig into the racist surrounding that particular trope.

Here’s a typical guy

Here’s the woman who gets most of the images

The other main female character is wearing a victorian era dress with a tight corset pushing up and exposing her cleavage. Essentially every depiction of a woman in this involves prominent cleavage. Even the woman beaten up and laying in a hospital bed in multiple casts and bandages is displaying cleavage.

Again, it’s ok to depict sexy women, but not if it’s only the women who are sexy. Men need to be depicted equally. If sexy people are important to your game then you need sexy people not sexy women. If they’re not important, then don’t emphasize sexiness. Also, having 20 sexy women and one sexy guy is not equal representation. It still says “women are sex objects” not “people can be sexy”.

In the rest of this book I believe there are only 4 other images in the book that don’t show off a woman’s chest or ass. One is a very reasonable depiction of a female doctor. One is an old-fashioned maid. One is a genre mash-up with minimal cleavage.

The last one is a problem.

Context Matters

Yes, this book depicts strong women. However, all the images of a woman doing something dramatic and strong are also images of women flaunting their tits and/or ass¹.

In addition to the many depictions of imaginary characters, there are some depictions of the people playing the game. One is young black man. He’s fairly average looking and - from my perspective - there’s nothing particularly notable about his depictions.

The other is a fat girl.

I have chosen that word, with all of its negative connotations very specifically. In this book imaginary women are sexy, powerful, and always displaying improbable amounts of cleavage. Women in the real world are fat.

To be clear, I actively want more positive depictions of big girls in media. I want to see games that say “Yes, we want all types of people with all types of bodies to play!” Representation is important for everyone, but context matters. And the context here says “real girls are fat and unsexy”. Note that the chest which was nigh-impossible to avoid in all the other depictions of women, is hidden, despite the fact that big girls, by definition, have more boob to flaunt.

All women are weak.

In this book male and female adversaries are depicted as getting beaten up, shot, mauled, etc. There is one depiction of a male hero being hurt, but it’s a combo image explaining a rule where you can undo something bad happening to your character. In other words, the guy doesn’t actually get hurt.

I believe that literally every other image of a hero who has taken damage is a woman.

One can debate if the man in that image was defending her, or simply fighting the dragon, but this image makes it pretty clear.

In this image the man is literally “Taking damage for an ally”. That’s the title of this section of the book. He has jumped in to protect her from the primitive looking orc. Once again, I’m ignoring the inherent racism with the orc here. What’s important for this article is that it’s very clearly showing that women are the ones who need protecting. Women repeatedly show their weakness by getting beaten bloody, while men remain strong and protective.

There are zero images of women protecting men.

There are zero images of fantasy women who aren’t explicitly “sexy”.

There are zero strong female characters depicted who don’t eventually get beaten to a pulp.

Contributors

According to the credits, there were no women involved in the creation, or play-testing of this game. It is painfully clear that there was no sensitivity reading done.

Women need to be included in every aspect of our games.

Wrap-up

It doesn’t have to be like this.

Here’s a random selection of female² characters from Paizo’s Pathfinder game. All of these are powerful looking characters. None of these are powerful because of their sex. They’re just bad-ass looking characters who happen to be female.

Again, there’s nothing wrong with depicting women who are sexy, or are trying to act sexy. But women can’t be defined and thus valued for their sexiness alone.

Summary

I didn’t cover all the problems in this book, both because I’m too upset, and because it’d be “beating a dead horse”.

There is no excuse for this in the 21st century.

I recognize that lots of guys have internalized sexism and misogyny. We take on the values of the people we spend time with. If you don’t spend time with women, or people who care about them, you won’t be aware of your biases. To a degree that’s ok. That’s human nature. What’s important is that once you’ve had those biases pointed out, you acknowledge them, and work on eradicating them.

You’ll never please everyone, but when creating a game for others - or even just a space for others to come and play games - making people feel welcome and comfortable, regardless of their gender is the bare minimum.

I should not have to say this, but women are people. Women are important. Women and men are equal³. Women’s opinions are valid. Women’s needs are valid.

To ignore the needs and comfort of women is to say that they aren’t valid, or valued by you.

We must take women into account when creating games and playing games. We must ask their opinions. We must listen to them. We must make gaming a safe space for them. We need to acknowledge that our personal perspective on what’s “acceptable” or “good” is not shared by everyone. Things that we think are “fine” may make the people around us very uncomfortable.

Everything about this article is depressing and saddening.

Everyone has mothers, sisters, aunts, grandmothers, and/or daughters, and all of those women should feel be comfortable at our gaming tables. Do we really think it’s appropriate to teach our daughters that being an entertainer means being a “whore”?! That sex is a tool they should use against men?! That they can’t be strong without a man to protect them?!

Fuck all of that.

All of that sexist and mysogynistic bullshit has ruined what might actually be a decent game. I wouldn’t know. I would never ask a person I respected to go.

I feel gross for having given money to the creation of this, so I’ve made a donation to Futures Without Violence. The portrayals of women in this book, and books like it always result in harm. I hope that maybe my contribution can help offset a little bit of the damage done by supporting this game’s creation.

If you want to discuss TTRPGs and how we can make them better for women and everyone else, you can find me on mastodon at @masukomi@dice.camp

Yes, there are some depictions of women being powerful where their cleavage is obscured. In most of these the woman is hurt, and there are none where we haven’t already seen that cleavage and don’t have it in our minds. ↩︎
The third character may be non-binary. I don’t know their backstory. ↩︎
Some ass-hole is going to read this and say, “not physically”. Riria Ropata lifted 599Kg (1320 Lbs) in Women’s Powerlifting in the Oceania Championships in Australia. Literally every time a women has beaten the men at combined olympic sports they have divided the competition into male and female categories. Women kick ass physically too. So please, take your ignorant bullshit somewhere else. ↩︎

The Remarkable 2 Tablet

Tue, 04 Jul 2023 00:00:00 -0400

Table of Contents

The Remarkable 2 e-ink notebook

The Remarkable 2 e-ink notebook

Summary

If you are the type of person who already takes a lot of handwritten notes in notebooks you’ll probably love it. Everyone else should probably skip it.

I am the type of person who already took lots of handwritten notes in notebooks, and I am beyond thrilled with this.

Context

I am picky about pens. I am picky about paper. My notebook of choice is the Rhodia Webnotebook with a nice smooth thick lined pen. Sometimes that’s a Lammy Safari fountain pen. Sometimes that’s just a really nice rollerball with heavy flow. What’s important is that I’m not happy with any random pen on any random paper.

I take lots of notes. I have notebooks filled with research and ideas. If i write something with my hand I learn it better. I also derive a lot of benefit from drawing tables and arrows and having annotations on the side and all those things that only exist with handwritten notes.

I hate taking notes on the iPad. I’ve never encountered a “pen” that looked right, or behaved right. Everything looked like crap, and the experience of a stylus on glass is just terrible compared to paper.

I’m also very light sensitive. I don’t like looking at transmissive screens (monitors), but i love reflective screens (e-ink like the kindle).

The Search

For years I’ve been wishing for an A4 (~8½ x 11 inch) e-ink tablet (preferably color) that i could read my many PDFs for role playing games on. Those don’t really exist (yet) and the few that do are over $1k USD and black and white.

For reasons that aren’t important, I gave up and after watching many glowing YouTube reviews of the Remarkable 2, i gave in and bought a used one on eBay.

The Review

The reMarkable 2 is a truly impressive tool for note-taking. That is the only thing it does, and it does it very well.

Writing on this is completely unlike writing on an iPad, or other glass tablets. It’s not as good as your favorite paper, and pen, but it is as good as decent paper and a decent pen.

Why It’s Better Than Paper

This is going to sound trivial, and on a standard computer it kind-of is, but for handwriting it’s amazing.

You can just tap undo. You can select a piece of writing / drawing and move it. Rather than scrubbing out something with a digital “eraser” you can just lasso it and delete. You can copy. You can resize a copy.

When handwriting quickly it’s not uncommon to make a word that’s nearly illegible. You could erase it, like with pencil, and the results are better than erasing pencil or even good erasable pens like the FrixIon line. However, that’s still a lot of back and forth scrubbing. Sometimes it’s just easier to tap the erase selection icon, draw a loop around it, and start over.

You don’t need to worry about wasting paper anymore. Did a thought end half-way through a page? It’s not a big deal to just start the next one on the next page. You’re not wasting anything. There are infinite pages. Similarly, I’ve started something half-way down a page, and wanted to have the rest of the thought together on the same page. I’ll just select the text, cut it from the page, move to the next page, and paste it there, where I’ll have space to finish it off.

Most of this sounds, unnecessary. We’ve all be “getting along just fine without it” for hundreds of years. Trust me. It’s better. It’s way better.

Pens, brushes, etc.

There are a wide variety of choices for drawing tools, and they all “feel” different. They’re also all sensitive to the angle you hold your stylus. As with a pencil or conical-tipped marker, the angle you hold your writing tool at determines the thickness of the line. The amount of pressure you make changes it to. This is true of the iPad too, but on the iPad the result is completely unlike any real pencils or pens unless maybe you’re in one of the premium drawing apps. But, I’m looking for note-taking capabilities, not creating fancy art pieces. On the reMarkable 2 the results are almost exactly what you expect from physical media.

The “Ballpoint Pen”, “Fineliner”, “Marker”, etc. all have 3 thickness levels, and a few “colors” (shades of grey on the reMarkable but color on export). The result is that you’re going to find a line that works for you. The Highlighter works a lot like a real one and the exported PDFs are highlighted in color.

You can draw on this. There are many videos on YouTube that should give you a clue about what it’s like. Speaking as someone who grew up in art clases, I wouldn’t recommend it. Stick with physical media. This works, but it isn’t good.

That being said, you can export the images as SVGs and clean them up in an app like Adobe Illustrator or Affinity Designer. Note that they look bitmappy and terrible when you first open them up. That’s because there’s a low-rez rasterized preview image on top of the vector shapes. Just delete the rastered layer and suddenly everything looks better.

Getting Things On and Off it

Getting files on and off of the device works way better than I expected it to. Turn it on, connect it to your wifi, open the app on your desktop and they just find each other and sync. Add a file in one and it magically shows up on the other.

There’s a Remarkable Connect service you can subscribe to for $3 a month. If you write as much as I do then this is worth it because it means you’ll be constantly backing up your writing to the cloud rather than hoping you remember to sync it manually. It just works silently in the background.

Styluses

reMarkble uses the same Wacom stylus technology that all of its competitors use. This means that you don’t need to buy their sytlus. It’s a perfectly good one, but it’s not your only choice. However some styluses may require following some geeky command line instructions to enable their features. See Gotchas & Warnings.

The one that comes with it is pretty good. Feels a lot like holding a pencil. Spend the money on the one with the “eraser” but be careful with it. That “eraser” is held on by a very thin piece of plastic at the center and can be easily broken if you drop it and it hits something badly.

The nibs you get matter. Most of these styluses seem to use interchangeable nibs. The shape and material of them matter. When I got my Lamy AL-Star EMR stylus the nibs that came with it made it feel much closer to writing on glass. I immediately swapped those out. A week later I noticed that the nibs I was using had already developed a chiseled shape to the tip, much like a pencil. There are metal nibs you can get, but I suspect they feel even less like writing on paper. These cheap 3rd party ones on Amazon work fine for me and only cost $16.

My used one came with a broken eraser, so I got the Lamy Al-Star EMR after watching a bunch of stylus reviews. I like the Lamy, because unlike a real pencil, you don’t need to flip it around to use the eraser. You can just press the button. Unfortunately, you need to install custom software on the tablet to configure it. I’m a programmer, so this isn’t a big deal. It’s well documented, so a non-geek should be able to follow the instructions and get it working, but it’s definitely “sketchy”.

The Lamy is harder to get in the US, so your next best option appears to be the Staedtler Noris Digital. I can’t comment on it, but it’s well regarded.

You can get away with a stylus without an eraser, but I don’t recommend it. You’ll be happier being able to erase in the traditional means and with the selection lasso, rather than being forced to always use the selection lasso. Be warned that there are a lot of styluses that mention they’re compatible with the reMarkable but do not have an eraser and don’t call that out. Read carefully before buying.

Reading PDFs

It does a perfectly good job of loading and displaying PDFs, BUT if your PDFs are 8½x11 or A4 they’re going to be shrunk down, and hard to read unless you have 20/20 vision. If your goal is to have something you can read large PDFs on, don’t get this. Buy a larger tablet from an importer.

Gotchas & Warnings

You absolutely need custom PDFs for notetaking. There’s a ton to choose from on Etsy for around $6 USD. Hyperpaper lets you generate a customized one that’s pretty good, but it’s like $20 and it includes sections I don’t want.

The problem is that unlike a traditional notebook you can’t flip back to an index at the front. Technically you can, but it’s not nearly as fast or easy, and once you get to the index to see “oh this topic is on page 167” getting to page 167 is just a pain. You need a hyperlinked PDF where you can write subjects on lines that you can then click to go to the page where you write the details.

If you want Dayplanner or Date based journaling type stuff there are a ton to choose from. If you just want to take notes that aren’t inherently tied to a calender your choices are more restricted. I have a Hyperpaper one where I just ignore all the date pages, and this one from Etsy which is pretty decent. I recommend buying a few and finding one that works for you. Or, if you’re geeky, generating your own custom hyperlinked PDF.

Assorted quick things you should know before buying:

You can’t search handwriting. You can’t do it in a paper notebook either. Having hyperlinked PDFs solves the findability problem though.
The battery is not replaceable, and like all modern batteries, it’ll gradually loose the ability to hold a charge. For this reason you’ll want to buy a new one. Buying new also gets you a free year of the Connect service.
Compared to the glass of modern tablets, the screen is a soft and easy to scratch. You’ll definitely want a case.
You can make custom “Paper” templates, but loading them requires geekery and you need to re-add them every time the OS updates.
You can make custom sleep screens, but loading them requires geekery and you need to re-add theme every time the OS updates.
Styluses with buttons like the Lamy AL-Star EMR require geekery to make the buttons do anything and you’ll need to re-do it every time the OS updates.
Stylus nibs should be considered a consumable item. Cheap 3rd party ones are fine, but writing with a dull nib sucks in exactly the same way as writing with a dull pencil. Keep some replacements on hand. Just like pencils, they come in different hardnesses. Unlike pencils there’s no obvious standard to rate the hardness, so you just have to buy some different brands and find what works for you.
There are lots of cheap cases / covers for it, but I’ve yet to see one as nice as the overpriced one that Remarkable sells. I’d buy that one myself if I didn’t already have the materials required to make a custom leather one.
The Gestures you use to flip pages don’t always work, at least, they don’t on mine. Sometimes I can flip pages without problems. Sometimes it takes me 3 tries. It’s pretty annoying. The device is good enough in all other respects that this isn’t even remotely going to make me stop using it.
The bottom bezel is larger than it appears. This isn’t a problem, but it’s like the original iPhones where it just felt like a big swath of wasted space at the bottom.

Final Thoughts

This device is absolutely transformative. Literally.

I’ve written probably a hundred pages in it in less than a month. My only regret is that i didn’t buy a new one. If anything happens to mine I’ll buy a replacement without hesitation. I’m somewhat annoyed with the scratches that came on my used one’s screen so i may buy another one anyway. It’s just that good.

Bonus Discovery

If you play tabletop role-playing games (think D&D) this thing is amazing for character sheets. It’s ok that they get shrunk down. What’s important is that you can erase and change the numbers infinitely without mucking up the paper. Make temporary notes. Scratch them out. Whatever. It’s awesome. Great for character building too when you need to keep track of all the points you’re in the middle of assigning to various things.

On Federating With Meta

Mon, 03 Jul 2023 00:00:00 -0400

Table of Contents

tl;dr:

Meta and Google are existential threats to the continued existence of Mastodon (and friends).

An existential threat is a threat to a people’s existence or survival. - The Brittanica Dictionary (editorial)

The best way to guarantee the death of the things we love about Mastodon (and friends) is to allow Meta or Google to gain a toehold in the Fediverse.

If you’re an instance admin who feels similarly, please add your name to the Anti-Meta Fedipact.

An explanation

I see no future in which Meta or Google embracing the Fediverse will not result in eventual “extension” and “extinguishing”. There is more than enough history to go on.

If you have not read it already I’d strongly recommend you read “How to Kill a Decentralized Network (such as the Fediverse)”. Its a story by a Google employee who worked with them when they adopted XMPP (Jabber). If you don’t know already, it was a relatively popular federated messaging service that had a reasonably decent install base but hadn’t taken over the world yet. It supported group and direct messages. Mastodon, meanwhile, is a federated messaging service with group and direct messages and a reasonably decent install base that hasn’t taken over the world yet. The definition of “group” may be a little different but you get the point. Google embraced it, slightly extended it, and then killed it.

Email is a federated messaging service. Unlike Jabber or Mastodon it pretty much had taken over the world before Google made GMail. It’s too entrenched to kill off entirely, but they’ve done a very good job of coming close. Google “embraced” email, then they “extended” it by creating their own modern API that developers could use instead of IMAP or POP to communicate with their servers. IMAP and POP are both terrible to work with by modern standards. People who care enough about email to write an app for it quickly realize that using the GMail API will not only be way easier but also give them better results, and access to millions of potential users.

The end result is that all the cool new ideas that people come up with get implemented in a way that only works for GMail. Because all the cool new things you want to use only work with GMail everyone - even businesses - start signing up for GMail accounts. If it wasn’t for Microsoft - and thus Outlook - being so entrenched I’m convinced email as we know it would be dead.

It’s already started

The leaks from the secret (contents under NDA) meeting between admins of large / significant Fediverse servers and Meta suggest that:

Some large server admins will be offered financial compensation for federating with Meta
Meta would get to set the moderation policy if admins agreed to compensation
Fediverse admins would have the option of including Meta advertisements in their federated feed and receive a cut of the profits from those.

There is no possible way this ends up being good for the Fediverse.

Meta’s moderation policies are crap.
Meta’s ability to moderate is crap.
Meta refuses to provide care for the mental health of the moderators they pay to go through an endless stream of horrific images (torture, pedophilia, rape, etc.) and incredibly cruel words. This article describes just what a terrible job it is.
We explicitly do not want ads in our feeds.

The only good thing is financial support for server admins who need it because Mastodon is horribly inefficient and people are not good about actually supporting their server admins financially. Its understandable since we’ve had services like this for free for so long - because we were the thing being sold.

Going Forward

The only real solution to this is a truly distributed system. Not federated, but distributed. Unfortunately there are no good (IMNSHO) distributed solutions available right now.

Right now, the Fediverse is our best option. We have a very slim chance to ward off the colonizers.

If we want to have any hope of protecting our communities from fascism, racism, and simple advertising we have to do three things:

Refuse to Federate with Meta.
Refuse to Federate with Google.
Financially support our server admins if we can afford to.

What if they do get a toehold?

If Meta or Google get a reasonable toehold in the Fediverse we’re doomed. It’s just a question of how quickly.

First people will connect with friends and family who’ve been stuck in Facebook. Social bonds will be (re)formed. As time goes on those bonds will strengthen, and it will be harder for admins to get away with defederating from those servers without massive uproar from their users. Especially on large servers where the users specifically don’t care about finding a good community of like minded people online.

But what about [insert company here]

Tumblr has promised to add ActivityPub support. They’re not small, and I don’t care at all. There is no evidence to suggest that Tumblr’s adoption of ActivityPub will result in an “embrace, extend, extinguish” strategy or a flood of terrible content. Tumblr seems to be a good actor overall.

Micro.blog added Fediverse support a while ago. Even if we ignore the fact that they’re not big enough to follow that strategy, they’re being really good community members. They’re not forcing their ideals on anyone, they don’t push ads, etc.

Vivaldi (web browser) set up a mastodon server for their users, and integrated it into the browser, making it easy to get online and start participating. But that’s it. It’s just another server. They’re not going to try and warp the Fediverse it into something they can control.

From my perspective, there’s nothing inherently wrong with companies providing Fediverse accounts for their users. Yes, they’re prone to having large numbers of users which means no community and no real ability to moderate, but that’s true of every large mastodon instance regardless of who owns it.

The problem is companies who are strongly motivated to try and control it and have enough users to make that a real possibility.

Github Rubocop Workflow

Mon, 19 Jun 2023 00:00:00 -0400

It took me a while to figure out the correct collection of magical incantations required to make RuboCop run in a GitHub workflow, but ONLY on the files that were changed within the PR. This is a useful configuration if you have a codebase that has not yet been modified to satisfy all your “Cops”. I’ve also included a version of the same file that you can use when you’re ready to have RuboCop run on all non-excluded files.

The result is that rubocop will only block your PR if some of the files touched in the PR don’t conform to your new standards. Once your codebase is

The on: [pull_request] means that it will run when you make the pull request and any time you push to it (with or without force).


# A GitHub workflow to run rubocop, but ONLY on changed files
# honors any exclusions specified in your .rubocop.yml
#
# store this file in .github/workflows/rubocop.yml
# note: the Checkout Branches step is required
# because by default what's checked out is the branch
# that represents the future merging of the PRs branch
# with the target branch.

name: RuboCop

on: [pull_request]
jobs:
  rubocop:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v2
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true
      - name: Install gems
        run: |
          bundle config path vendor/bundle
          bundle config set without 'test tools functional'
          bundle install --jobs 4 --retry 3
      - name: Checkout Branches
        run: |
          git fetch origin ${{ github.head_ref }}
          git fetch origin ${{ github.base_ref }}
      - name: Run RuboCop
        run: bundle exec rubocop --parallel --force-exclusion $( git diff --name-only --ignore-submodules=all --diff-filter=ACMR origin/${{ github.base_ref }}..origin/${{ github.head_ref }} )

Once your codebase has finally been cleaned up to a point that RuboCop is happy with it you can change it to the following. This is strongly recommend because it will catch when code made it through to the target branch without getting checked (merged directly, or a PR that was merged despite failing checks). The time difference is not noteworthy. Spinning up the container and checking out the gems takes much longer than the actual RuboCop run.

# store this file in .github/workflows/rubocop.yml
# this will run rubocop on ALL the files in your repo
# that have not been excluded in your main .rubocop.yml
# rubocop configuration file.

name: RuboCop

on: [pull_request]
jobs:
  rubocop:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v2
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true
      - name: Install gems
        run: |
          bundle config path vendor/bundle
          bundle config set without 'test tools functional'
          bundle install --jobs 4 --retry 3
      - name: Run RuboCop
        run: bundle exec rubocop --parallel --force-exclusion

Converting Apple's Add To Wallet Images

Fri, 09 Jun 2023 00:00:00 -0400

Apple distributes their “Add to Wallet” images as SVGs which is great, but if you want to add it to an email or anything else that has issues with SVG files you’re going to need a PNG (to maintain transparency around the rounded corners). Unfortunately there are a LOT of these images needed to support the various languages.

apple wallet images pr

Converting these to PNGs is not as easy as you’d hope.

Problems I encountered:

imagemagick produces unusably bad images (mostly just black) even though it’s theoretically calling rsvg-convert under the covers and calling that directly works fine.
inconsistent width and height
extra transparent pixels on right and bottom edges

Here’s my solution with comments inline about what I learned along the way. It involves 2 scripts. The first one is in fish shell, just because that’s where i started but you should be able to convert to Bash or whatever you like to use pretty easily.

#!/usr/bin/env fish

for file in (find . -name "*.svg")
  set directory (dirname $file)
  set base_filename (basename $file .svg)
  set new_filename $directory/$base_filename.png
  # -z 10 add zoom. not because we need it bigger, but because
  # it looks WAY better when you add _any_ amount of zoom.
  # -w 884 because if i don't constrain width or height then
  # the results are too varied to apply a consistent cropping
  # percentage
  rsvg-convert -z 10 --keep-aspect-ratio -w 884 -o $new_filename $file
  # convert $new_filename -gravity NorthEast -crop WIDTHxHEIGHT $new_filename
  # image_size.rb is outputting the cropped "WIDTHxHEIGHT"
  #
  convert $new_filename -gravity NorthEast -crop (image_size.rb (identify -ping -format '%w %h' $new_filename)) $new_filename

  # -crop results in foo-0.png foo-1.png foo-2.png (sometimes)
  #   and foo-3.png (sometimes)
  # what you want is in 0.png and the others are bits cropped off ?
  mv $directory/$base_filename-0.png $new_filename

  for n in (seq 1 3)
    # delete the unnecessary files. &> is redirecting STDERR to STDOUT
    # then shoving all to /dev/null because it doesn't ALWAYS generate
    # the -2  and -3 files ?!?!
    rm $directory/$base_filename-$n.png &> /dev/null
  end
  git add $new_filename

end

With a constrained initial width plus a little scratchpad math i was able to figure out that cropping 0.7% from the width & 2.8% from the height (rounded up on both) seemed to get me “good enough” results.

It’s not perfect. Some still have 1 or 2 pixels of transparency at the bottom, and some are cropped a little too much along the bottom (thin grey border missing). But, I don’t want to manually edit 45 files for languages we don’t support anyway. I figure we can go back in and manually edit the handful that are imperfect.

#!/usr/bin/env ruby

# cropper for ... wallet things

initial_width, initial_height = ARGV[0].split(/\s+/).map{|x| x.to_i}
width_hundredth = (initial_width.to_f / 100)
height_hundredth = (initial_height.to_f / 100.0)

width_crop_percent = 0.7
height_crop_percent = 2.8 #2.58

new_width  = initial_width  - (width_crop_percent * width_hundredth).ceil
new_height = initial_height - (height_crop_percent * height_hundredth).ceil

puts "#{new_width}x#{new_height}"

Rounding Things In Tinkercad

Sun, 16 Apr 2023 00:00:00 -0400

Table of Contents

Overview

A Guide To Rounding Corners and Edges in Tinkercad.

Alternately, how I spent way too much time modeling a dice tray.

Rounding corners in Tinkercad is way more trouble than it ought to be. It’s not actually hard, it’s just really time consuming and requires a lot of steps. Once you wrap your head around the general approach you’ll be able to round anything.

This post will take you through the steps required to round the and edges on this simple dice tray.

Step-By-Step

High level rounding:

In most case you can simply stick a rounded thing on top of a rectangular thing and that’s it. For example, most of the walls in this are simply rectangles with half-cylinders laid lengthwise on top of them. That’s the bit you probably don’t need help with.

When you can’t simply build the shape you want, but instead need to round off an existing corner the approach is actually fairly similar. You build up the shape of the cut, cut it out of something, and then turn that something into a “hole”. For example: this image shows the sequence of things I’d do to round off one edge of a cube. I take a cylinder, which has the rounded shape I want, then cut it out of a another cube or rectilinear shape that is at least as large as the thing I want to round off. Then I convert that shape into a whole, and use it to cut off the edge of the cube.

Pro-tip. Make the thing that will be your cutting tool an even multiple of the size you’re cutting out of it. For example. The cylinder is 10mm into the cube I’m going to cut. The cube is 20mm wide. This means that when I use the resulting hole to cut into other shapes I can simply overlap them by 10mm.

The Corners

The corners are the most complicated part of this build. In order to have them curve over the edge on the top, but be flat on the bottom I needed to create a cylinder with rounded edges that were different on each end.

To build the bottom of the corner we take a torus (donut) and stick it on top of a cylinder. It’s much easier to build this upside down and then rotate it.

Note that the “Tube” slider controls the radius of the curved cylinder that makes up a torus shape. Your life will be significantly easier if you can make this a whole number. I wanted a 3mm wide wall, so I used a 1.5mm “Tube” which just made all the future placements of objects much more difficult. If I was doing it again, I’d just make the wall 4mm thick. Change the “tube” setting to be the size you want, then deal with the outer dimensions. Changing the tube radius alters the outer dimensions, so there’s no point in setting those first.

For the bottom we need to add a cylinder that fills the area from the top of each rounded side of the torus. This means we need a cylinder that is the diameter of the outer cylinder, minus the radius of your “tube” times 4. Set a ruler at the corner of the initial cylinder to help you place this inner cylinder correctly. The inner cylinder will be the height of the initial cylinder plus 1x the radius of your “tube”.

So, if we have a torus that with a 2mm tube (radius), and it sits on a cylinder that is 20mm in diameter, and 20mm high, then your inner cylinder will be 16mm in diameter and 22mm tall. To position the inner cylinder move it 2mm towards the center along the X and Y axis.

This picture shows the bottom of our corner with the pieces put together, and with the center cylinder offset. Now Shorten the outer and inner cylinders by at least the radius of your tube, and then shift them back up into position. Copy this shape, and set it aside, so that we can use it as the start of our top corner. Then group these pieces, and rotate it 180° to form a nice flat bottom with rounded edges, and drop it down so that it touches the ground.

Take the copy you set aside, and change the diameter of the inner cylinder by subtracting 4x the radius of the tube. Now it’s 12mm in diameter, and should look like it’s poking through the center of your torus. Convert that center cylinder to a hole. Now, shorten your cylinder by the radius of the torus. Then shift it up so that it’s touching your top torus, and hovering above the ground. and then combine all the pieces of the top here except for the hole. Make sure the bottom and top have different colors so that you can better see what’s happening in the next step.

Bonus points: If you want the inner curve at the bottom to be rounded too, add a half-sphere on top of your hole cylinder, combine them, and rotate it. Make sure that the bottom (the tip of the half-sphere) is the thickness of your floor away from the ground.

Combine the top and bottom pieces, then group everything. The process should look like this.

The next step is to cut away the excess and make it into a corner piece. For this I just take 3 cube holes. Each cube should be 2x the diameter of your cylinder. Arrange them so that they all intersect at the center of your cylinder, and are raised up the radius of your “tube”. Then combine all the shapes. Here’s the before and after.

Now we’ve got our corner piece.

You’re past the hardest part.

The “ears”

There are a couple ways to address this. You can take a rectangle, and attach 3 half cylinders of the appropriate size to the edges. I wasn’t so smart. I built the thing with rectangles and then cut away pieces.

Sooner or later though, you won’t be able to do this, and you’ll need to round off something as shows in the earlier sequence.

The thing worth copying here is the rounded corners. To make these you simple create a disk. This is just like creating the bottom of the corner, except that the height of the inner cylinder is 2x the “tube” radius of the torus it’s going inside. Combine those and you’ve got a disc with rounded corners. The torus you start with should have a diameter equal to the thickness of the thing you’re rounding.

Chop off a square corner from the item where the disk, then slide the disk into place, and combine the things.

Everything Else

Everything else is just a repetition of the techniques outlined above. In order to merge the floor with the corner pieces with the cylindrical bottoms, you just use two overlapping rectangles. It’s important that your floor extends to the middle of the wall. This is so that it will not extend past the apex of the curve.

You may notice that mine are not placed identically relative to each corner. The way my walls are constructed it doesn’t matter, and the resulting gaps are hidden.

A Template For The Leather

I wanted a nice fit for the leather insert. In order to make this I took the final model for the tray, and separated all the pieces. I combined everything except the floors, and then made that into a “hole”. I combined the floor pieces and then cut the hole out of them. This left weird corners. So, I grabbed the cylinder I had used to cut a vertical hole in the corner, converted it to a solid, and moved it, and a copy, into position on each corner that needed to be rounded.

Then I combined them. There was no need to make them taller. It was just easier to move around in Tinkercad if they weren’t the same height.

Now, this template is the exact dimensions of the floor. If you account for expansion of the filament during printing you’ve got a template that won’t fit into the tray because it’s micrometers too big.

This is ok for leather. I placed it on top of the leather I was going to cut, and then angled my blade at roughly a 45° angle towards the center of the piece. This gave me very thin leather at the top, and a bottom of the full thickness. The result is that when I set it into the tray the edges are a hair wider than the hole they’re going into, but they’re also very thin there. This exerts just enough pressure to hold the leather in place without any adhesive required.

The leather I’ve chosen is very soft. This is beneficial in such a small tray because it absorbs most of the impact of the dice. They stop rolling almost instantly, which is good, because they have very little space to roll in this tiny tray.

Conclusion

That’s it. I hope this helps save you from the hours it took me to figure all this out. If you find this helpful, or confusing, please drop a line to me on mastodon at @masukomi@connectified.com or drop me an email at masukomi@masukomi.org.

Kinesis Advantage 360 Pro Review

Fri, 17 Mar 2023 00:00:00 -0400

Table of Contents

High Level Summary

The Kinesis Advantage 360 Pro feels great. The ergonomics are better than the Advantage 2. The Bluetooth is buggy. The on/off switches are terrible. The mechanism for resetting it is worse than terrible. I’m still irked that the wrist wrests weren’t included at that price, and I suspect the Mo Ergo Glove80 is going to be an equal, or even better choice.

The Hope

I have been a fan of the Kinesis Advantage keyboards for a while. There were 3 things that I wished that they’d change.

The escape key and F-keys were not made to the same standards as the other keys.

This is probably fine for the F-keys which are essentially never used, but not for the escape key which is used relentlessly by Vim and Emacs users, and by anyone who knows that you can get out of most any dialog by hitting it instead of reaching for your mouse. I’ve had to buy 2 replacement Advantage 2s because of this failing key.
No Bluetooth.

This sucks if you’re a remote worker, and have a work computer and a home computer. Constantly plugging and unplugging. Yes, I hear you saying there are USB-A Switches, and this is true, but I have gone through multiple of those that just die. They’re almost all cheap Chinese crap, made barely well enough to survive the return window and nothing more, and be so cheap to begin with that it’s not worth the effort of returning anyway.
It’s not a split keyboard.

You spend all the $$$ on a Kinesis Advantage keyboard because you’re someone who cares about ergonomics. At the same time, the keywells being so close together forces you to angle your arms inward to get to them, and then compensate for that by bending your wrists outwards to be inline with the keys.

The Good

It’s got multi-device bluetooth.
They got rid of the terrible F-keys, but left space for an escape key.
There’s a GUI keyboard layout editor (kind-of).
It’s a split keyboard so you can spread the keywells as far apart as you need.
It’s even more comfortable to type on than the Advantage 2
The wrist wrests are magnetically attached and washable.
The Advantage 2 was so light as to feel cheap. The 360 has enough heft to it that you feel that you’re getting your money’s worth. This is of course ridiculous psychological BS that has no bearing on the real usability or quality of the keyboard, but what can I say? My monkey-brain thinks “heavy keyboard == better quality”.
It includes a keycap puller and a handful of spare keycaps.
It’s easy to angle the halves outward, and the metal mechanism feels sturdy.

The Meh

The wrist wrests are magnetically attached, which means that they frequently get shoved off, or shift around slightly as you move.
You can’t buy it in Dvorak.
The documentation is “meh”. It isn’t specific enough in places where I want it to be, and the table of contents in the PDF isn’t clickable to get to the relevant section of the document.
The two outermost columns of keys are oddly unaligned.

The columns thing is weird, and hard to capture in photos. It’s only a “meh” because my fingers can’t tell, but it looks like there’s something wrong with the keyboard, like maybe I didn’t push down those keycaps far enough. Those two columns are shifted down and also physically higher. I’m confident this is mostly to address ergonomic concerns around finger length, but the fact that it’s lifted up too, and exposing the keyswitches to your eye-line makes it “look” like a fuck-up.

The Not Good

The rubber feet aren’t fricative enough. Without a plastic bridge to connect the two halves my left one just kept migrating away from me as the day progressed.
The keycaps don’t have little nubbins to tell your index fingers when your hands are in the correct location.
The wrist wrests not only aren’t included, but are $30 + shipping. I wouldn’t mind $30 for a replacement pair, but when the keyboard itself is $460 this feels cheap.
The Dvorak keycaps are $80 + shipping.
There are spare keys that come with it, but there are no spare unlabeled keys, and there are no spare short rectangle keys.
The plugs for reflashing the firmware (updating the keyboard layout) are USB-C, but the cables that ship with it are USB-C on one end and USB-A on the other.
You can’t daisy chain the halves for charging. You have to use 2 separate cables to charge them at the same time.
You can’t update both halves of the keyboard at once. For all intents and purposes these are two separate keyboards.
The lights under the keys are all white.
They don’t offer a choice of keyswitches except via a 3rd party.

I’m a touch typist, who uses Dvorak. Essentially every keyboard I’ve typed on for decades has had the “wrong” letters on the keys. I figured I could spend $80 for a set of Dvorak keycaps, or I could just rearrange most of the keys on my keyboard and be left with a few keys that were “wrong” (because of no blank spares). I went with that. I’m still finding myself confused by keys that have the “right” letter on them, and don’t believe what I’m seeing. $80 just seemed wasteful.

The cords that come with it are useless to me except for charging because I have some USB-A charging bricks laying around. I can’t update the firmware / keyboard layout with them, because my computer only has USB-C. I think it’s reasonable to say that anyone who’s willing to plunk down nearly $500 to https://www.moergo.com/ be an early adopter of a fancy new keyboard probably has a modern computer. That means one with USB-C holes not USB-A holes.

Regarding the white lights under the keys: before getting the Keyboardio Model 01 I thought that RGB lights under keys were just some flashy gimmick that didn’t really matter. I was wrong. They are amazing. I loved looking down at that keyboard and seeing a gently shifting rainbow. It brought a tiny bit of happiness to me throughout the day. I asked Kinesis about this at some point, and if memory serves, their response was something to the effect of “it was too complicated” which I interpreted to mean “it added complications we didn’t feel were worth dealing with”. Meanwhile, the folks at Keyboardio managed to get that working even though it was a 2 person shop. I know two people who backed the Kickstarter for the Glove80, which managed it, plus the bluetooth.

Choice of keyswitches isn’t a big deal for average consumer keyboards. These are not average consumer keyboards. They cost so much more, and they are bought by people who are picky about the way their keys feel.

The Bad

Bluetooth

The bluetooth is… annoying. Every time close my laptop lid, and then re-open it I have to turn off bluetooth and turn it back on to get the Advantage 360 to reconnect. I filed a support ticket and they said it’s a known issue, and that they can’t do anything about it, because it’s something on Apple’s end. Now, maybe that’s true. Maybe it’s some weird side-effect of the 2 devices pretending to be one. All I know as a consumer is that every other bluetooth device I own reconnects just fine without me doing that.

Power Switches

The power switches are terrible. Not only are they hard to slide, they don’t slide well and have a position where they’ve been moved but aren’t actually moved far enough, and you can’t really tell if it counted or not.

Charge Indicator

There doesn’t appear to be a way to know how much charge each half has. On the Mac there’s a percentage of charge shown in the bluetooth menu, but it’s a lie. I don’t know what it means. Maybe it’s an average of the charge of both? Maybe it’s just the left one? I dunno. All I do know is that I have to just randomly plug in each half to keep it charged because I have no idea what the actual charge is.

When Things Go Wrong

The right and left halves can “loose ‘sync’ with each other”. It can go for weeks without this happening and then have happened overnight every night. It can happen while you’re typing.

The initial fix is to toggle the power switches “in rapid succession” which is easier said than done because it’s hard to tell if I’ve successfully switched my left switch half the time, and you can’t tell if it didn’t work because you failed to switch the switches or because it’s just not working. Once you’re confident you have successfully turned the halves on in rapid succession and it’s still flashing 3 red lights at you:

plug the current half into your keyboard
find a paperclip
find a hole that is literally impossible to see without removing keycaps
double click a button in the hole
drag a new firmware file onto the keyboard half to reset it.

I dunno about you, but in my experience not many people seem to actually have paperclips in their house these days. Worse, there are very few alternate objects that are both that thin, and that rigid. When my keyboard decided to randomly die and need to be reset I honestly thought I was going to be unable to use it for a week until amazon shipped me a box of paperclips. 🤦‍♀️ Fortunately I found one wedged between the bottom and side of a drawer of pens. Also, why double-click? It’s effectively impossible to accidentally stick something in this hole and click it once.

O.M.G. I hate that hole. It is literally the worst implementation of “stick a paperclip in to reset things” that I have ever seen. It shouldn’t require a paperclip in the first place. That would be mean even if paperclips were a thing people still had laying around.

I’ve had to do this 5 times in the past 2 days. I now have a folder on my desktop with the firmware files for each half so that I can easily drag them on to the drive the next time I need to do this.

The Bridge

Inside the box is a long thing box with keycaps, a keycap puller, the aforementioned useless cables, and a “bridge”. The bridge is a cheap, but well designed piece of plastic that snaps onto the support bars of each half and enable you to keep them rigidly attached to each other. It works well. It doesn’t need to be fancier than it is.

However, it’s only ~6" (15cm) long. This means that if you attach it you’re forcing your arms to angle inwards again because your keyboard isn’t wide enough. The entire point of buying this keyboard is to have a more ergonomic typing experience and prevent wrist strain. It’s baffling that they’d put such a short bridge in it, or that they’d only put a short one in. There’s plenty of space in the box for a longer one, and I’d be very surprised if this part cost them more than 25 cents to make. I designed a wider version for those of you with large-bed 3D printers, or who feel like paying too much to have a 3rd party print it for you. It’s the copper colored strip of plastic between the halves in the image at the top of this post.

Modifying The Keyboard Layout

Tweaking the keyboard layout on this thing is geeky as 💩. I’m a geek so I can handle it, but holy crap.

You have to clone a Github repo
Enable Github actions
Give a 3rd party app permission to write to your your repo.
Use a janky UI with poor accessibility
Wait an unknown amount of time for the files to build.
Know that you should look under actions, for a build artifact. Download a “firmware.zip” file.
Unzip it
Find a paperclip to shove in the invisible hole to mount the left keyboard. Oh, but only if it’s flashing, otherwise you can do a key combo. The docs specify paperclip in invisible hole first.
Drag the left file onto it. If you do the right file onto the left you’ll break things. Be surprised that it auto-unmounts itself and causes you to get yelled at by macOS for improperly unmounting a drive.
Repeat 8 & 9 for the right half.

For comparison, when the Keyboardio Model 01 had just been released, I had to edit a geeky file, that was very well commented, and relatively easy for a non-geek to work with. Then run an app to load the file onto the keyboard. That was it. No Github. No secondary build process. No “this half, then that half”. It just worked and worked easily. Having a GUI is nice, but they had the keys laid out in the file to match the keyboard. Later on they built the open source Chrysalis layout editor which is really nice. This was years ago. Ergodox also has a graphical configurator that generates the files you need without you to set up a GitHub repo and GitHub actions.

I was hoping that Kinesis would use Crysalis, or something of equal quality considering they’re not just a team of 2 people, but no. It’s nice that their editor is open source but it’s honestly not very good.

The Conclusion

Overall it’s a good keyboard with minor annoyances. Would I buy it again? Given the market today yes. Once the Glove80 starts shipping…. probably not.

I’m reasonably confident from the photos that the ergonomics will be comparable. It has RGB LEDs under each key. It’s got low profile keys which most folks seem to like better. I’ve played with a keyswitch tester for the keys they’re using, and they feel nice. They offer multiple keyswitch options.

I think the Kinesis may have better build quality, and it looks like the Glove 80 can’t angle outwards like the Advantage 360 does.

It’s honestly not a huge difference, but I really want bluetooth I don’t have to reset every day. I lust after those RGB lights. I really dislike the power switches on the Kinesis, and I outright hate the stupid paperclip reset thing.

Update

3 months later.

I start every day with upset grumbling, as I’m forced to remember that my keyboard doesn’t work when I first sit down in the morning. I then turn off Bluetooth on my laptop, and turn it back on. Kinesis claimed this was an Apple problem they couldn’t do anything about. This is provably false, because shortly after writing this my wife received her Glove 80. It does not have this problem.

If she dares to close her laptop lid and reopen it later, her keyboard continues to work. Additionally, the Glove80 can also tell her how much battery each half has, and which device number it’s connected to at the moment. The reset hole isn’t hidden under keys. The power switches aren’t so tiny and fine as to be more easily manipulated with tools. Updating the keyboard layout doesn’t require you to be so geeky as to configure a GitHub repo and understand GitHub workflows.

To top it off, the extra row of keys means that unlike the Kinesis, the capslock key isn’t in a hard to reach location, and the escape key can live where it’s lived for 40+ years instead of having to steal the location of another key. Currently mine lives where capslock key is supposed to be, which means every time I use my laptop’s keyboard I’m constantly switching into upper case letters and invoking the wrong commands in vim / emacs.

I think the Kinesis is better made. I think the Kinesis is prettier. When it comes to actual functionality and everyday use the Glove80 kicks its ass. I was concerned about the low-profile keys on it, but they’re really nice. I can not, in good conscience recommend that anyone buy the Kinesis Advantage 360 Pro when you could instead buy the Glove80.

Why Tabletop Role Playing Games Need Skills

Tue, 14 Mar 2023 00:00:00 -0400

Table of Contents

Preface

A recent episode of the Internet Office Hours: Role-Playing Games podcast was discussing the question of Skill Checks in Tabletop Role Playing Games (TTRPGs) and if they were actually needed. In designing my game I’ve spent a lot of time thinking about this, and I thought I’d share my perspective.

Skills in TTRPGs

What’s a Skill

Most TTRPGs tend to come in two flavors. Essentially all of them have a collection of core attributes like strength, intelligence, and dexterity. Some also have “Skills”

Some skills are pretty generic, like “investigation”, while some are very specific, like “lock-picking”, but all of them are a representation of things that can be improved with training and practice.

Playing Without Skills

Most games don’t have a “lock-picking” skill, but anyone can attempt to pick a lock. This is generally handled by having the character roll with their most relevant core attribute (Dexterity, Finesse, etc).

This is reasonable, and I’d say actually needed, because you’re never going to have a comprehensive skill list, and there are many things that would be reasonable for a character to do that the player wouldn’t think to list during character creation.

Why That’s Not Enough

Let’s stick with the lock-picking example. In D&D everyone can attempt to pick a lock. It doesn’t matter if the character has ever seen a lock before, or has any clue what a “tumbler” is or how they function in locks. Everyone can pick a lock. Because almost every character has an above-average dexterity, this means that everyone has a decent chance of picking the lock.

This is especially true because the difficulty of a test, in essentially every system, is based on how hard it would be for an average person with a tiny bit of understanding to accomplish a thing. So, it’s a lock with a difficulty of 15 regardless of if you spent your entire life in a tree or spend half of it practicing for the world lock-picking championship.

Realistically, no-one should have any reasonable hope of picking a lock unless they’ve practiced picking locks and understand how they work.

That’s where skills come in.

How Skills Change Things

Some people have been trained in lock picking. Some people can pick locks. Some people are better at it than others, and unless they’ve got a degenerative motor disease it really doesn’t matter how much “dexterity” they have.

Without skills there’s no way to represent this. Without skills, there’s no point in having a backstory that says you’ve trained in archery for your entire life. It’s irrelevant. In many games, someone who’s never picked up a bow, but is an incredible gymnast will absolutely kick the ass of someone with average dexterity who has practice archery their entire lives. Why? Because you’re rolling against dexterity not an archery skill.

Skills make backstory meaningful.

Classes like “thief” are just shorthand for a collection of skills. A “thief” is expected to be able to pick a lock, or a pocket because it’s part of the skill training to become a thief. At least, it is in Swords & Sorcery games.

Classes are a way to get around the need for explicit skills, but it’s only meaningful if other classes can’t do those things. For example, the “fighter” shouldn’t be able to pick a lock, because they’re trained in martial arts, not the ways of thieves. Sure, they can stick a lock-pick in a lock and wiggle it around, but unless it’s a ridiculously trivial lock, they should be guaranteed to fail.

What about Knowledge Checks?

I’ve gone back and forth about the value of knowledge checks. There’s a good argument to be made that the player and / or the Game Master should have an idea of the kinds of things that are reasonable for the character to know.

I went so far as explicitly removing them from my game, and instructing people to simply ask themselves if it’s reasonable for their character to know the thing you’re wondering about, and go with whatever the answer is.

I still think that that is how most knowledge checks should be handled. However, I realized that there are a lot of edge cases that aren’t reasonable, or fun to address that way. For example, pretend you’re a researcher who’s spent years reading old scrolls of arcane knowledge. Have you read every scroll? Probably not. Have you read the one specific scroll about an especially obscure bit of lore? Again, probably not but…. maybe?

What’s more fun? The realistic probability that no living person has read that particular scroll or saying “Probably not, but there’s a slim chance, so let’s roll to find out.” If the dice say you aren’t familiar with it, then you’re no worse off. If the dice say you are familiar with it, then the player gets to describe the circumstances under which they came across this piece of obscure knowledge, and the GM gets to give the players a piece of unexpected, and useful knowledge. A chance for a player to shine, and an unexpected reward for trying.

In this case you might be playing off of an “arcane lore” skill, or the character having a “arcane history degree”. The fighter doesn’t even roll, because it’s not reasonable to expect that their character would have ever been reading through obscure arcane scrolls.

What about Perception & Investigation?

Perception

Perception is interesting. The ability to notice things is a skill that you can practice and improve, but few people have any reason to. Your default is generally “good enough.” If you were a scout, a guard, a thief, or someone who’s profession demanded good awareness you’d likely be well trained at this and better than most. However, I’ve yet to see a game that treats it this way.

Perception checks are generally used to answer two questions “What do I see?” and “Did you notice that?”

I loathe the first with a passion. Just tell the player what they see. If they ask “do I see X?” just tell them. There’s either a chair in the room or there isn’t. It’s not like the chair sitting in the middle of the floor will only be noticeable if they roll high enough. Everyone who isn’t literally blind is going to see the chair.

The second has a lot of value, because you can’t just ask the player “Do you notice the assassin sneaking up on your character?” And it’s no fun to just declare that the guards you’re attempting to sneak past automatically notice you. It’s fine if they’ve got a “notice” or “perception” skill that’s radically higher than your “sneak” skill, but as a general statement there should be a roll to see if you can pull of the attempt.

Investigation

I’m pretty bad at finding things. If there’s something that needs to be found, and I’ve failed to find it, I call in my wife. I’ve got a pretty bad “investigation” skill. My wife has a higher rank in “investigation” than I do. At the same time if I were to rank us on a scale of say, 1-20 I’d put us at roughly the same number. So, eschewing an investigation skill means “just use your intelligence” and now my wife and I are equally good at finding things.

Dogs, on the other hand, aren’t generally considered to be particularly smart animals (relative to humans) but they’ve got really good noses, and are great at finding things once you manage to convey to them what you’re looking for. Being good at investigation, is therefor independent of intelligence. You just need sensory input that’s good enough and a decent strategy for finding the input you’re looking for.

I could practice, and approach the process of finding things in a more methodical way, and then I’d get better, but my intelligence level wouldn’t change. Dogs find things better when paired with a human with a better strategy for investigating. Investigation really is a skill. Deriving it from intelligence doesn’t make a lot of sense.

We need an investigation skill, and dice based checks because of people like me. The thing might be “just inside the closed door” but who’s to say I’m going to think of opening the closet? The roll represents the result of a search. The investigation skill represents how likely I am to do a good job at searching.

We need a mechanism to determine if the thing we’re searching for is there.

The Gumshoe system provides a partial counterargument for this. In Gumshoe if you’re skilled in a thing, and you ask about it at the appropriate time, you find it. If you’re not skilled, you probably don’t. For example, assume your character is a detective who regularly investigates murders. You arrive at the crime scene and ask “do i see blood spatter?” The answer is “Yes, and here’s everything it tells you”. If you’re a professional dog walker the answer is “maybe”. You then roll. Even if you do notice it, it’s not going to mean as much to you as it will to the detective.

Clarification

When I speak about “fighters” and “thieves” I’m speaking about the archetypes. There’s no reason you couldn’t have a fighter who spent their childhood in a house of thieves learning to pick locks. Any character should be able to have any skill so long as there’s a reasonable explanation and it’s something they’re physically capable of doing.

Also, this is about “most” TTRPGs, not all. In Honey Heist you have 2 attributes: Bear and Criminal. You don’t need any more for that game. Lasers & Feelings has just Lasers, and Feelings. People have had tons of fun playing both of these.

That being said, most popular TTRPGs are building on the ideas that started with D&D. Cypher System is radically different from D&D, but like most, it still has core attributes, and skills. It’s a fundamentally good way of describing the capabilities of a complex and nuanced character, who is more than just their core physical and mental attributes. Some games want that level of detail. Some don’t.

Conclusion

We need skills to make characters backstories meaningful. We need them to differentiate characters in a meaningful way. We need them to address the fact that regardless of how smart, dextrous, or strong you are there are things that each of us know how to do that our companions do not.

We need skill checks to address the fact that sometimes you make mistakes, and sometimes your training isn’t good enough, and sometimes you’re just unlucky.

A character that has a skill gives them, and their player, an opportunity to shine. That same character not having other skills gives the other characters an opportunity to shine. We want characters that aren’t good at things, so that they have obstacles. Having skills says “I’m good at this” but it also says “The skills my companions have, that I don’t, are things I’m not good at.” This enriches our characters, and our stories, and also provides the GM with a list of things that they can leverage to let a character shine, or maybe help take the spotlight off of a character who’s been succeeding a little too much.

Update

Added the Clarification section based on comments on Mastodon.

Duct Tape & Baling Wire Methodology

Fri, 10 Feb 2023 00:00:00 -0500

Table of Contents

Duct Tape & Baling Wire
- Premise, and Perspective
- The Methodology

Duct Tape & Baling Wire

A coding methodology for personal projects and proof of concepts.

Premise, and Perspective

Premise

There is a time and place for following “best practices” as a developer. It is not “always”.

Best practices should be followed when…

your code can cause harm, damage, loss, etc.
you are sharing software that people will rely on.
people are paying you for a product that is expected to be “good quality”

In all other contexts following “best practices” are optional, and sometimes detrimental.

Flexible Makeshift Materials

Duct tape is commonly used in situations that require a strong, flexible, and very sticky tape. Some have a long-lasting adhesive and resistance to weathering. - Wikipedia

Its uses are infamous, and as a result, almost everyone has a roll of it on hand, even though it’s rarely the “correct” or “best” tape for any given job. It’s not even the right tape for ventilation ducts anymore.

Baling wire, otherwise known as bale wire, farm wire, haywire, or soft wire is a type of wire used in agriculture and industry for many uses such as mending fences or manually binding rectangular bales of hay, straw, or cut grass. It is also used in many non-agricultural applications such as banding together corrugated cardboard, paper, textiles, aluminum and other materials that are processed in the recycling industry.

Baling wire is sometimes used in an informal, make-do manner as an easy fix. It is frequently referred to as one of the basic repair materials. Typical uses include supporting loose mufflers and patching chain-link fences. Common phrases often include baling wire as an ad hoc, fix-anything material, alongside chewing gum, duct tape, and the cable tie. - Wikipedia

While most of us don’t have a roll of Baling wire on hand, it’s become a similarly generic solution to a wide variety of problems by those who do. Baling wire is a little harder to work with than Duct Tape, but its much stronger, and can be trusted to hold things together for a significantly longer time.

The “Wrong” Tool For The Job

Every time you’ve solved a problem with Duct Tape, you’ve likely used “the wrong tool for the job”. At the same time, it’s rarely a “bad” decision. The “right” tool is frequently unavailable, or inconvenient. The “right” tool frequently involves taking more time, and applying more care and consideration than the problem justifies.

Sometimes a “quick and dirty” hack is absolutely the “right” choice. If you’re having a yard sale, and the wind keeps blowing your sign away, then grabbing some Duct Tape and taping it down is a great choice. It’s a far better choice than canceling the yard sale while you go off and build a waterproof, wind-proof, ground-embeddable, backlit sign holder made exclusively out of recycled materials.

Quick & Dirty != Crap

Quick and Dirty hacks should be applauded, not derided. They are applied when we need to accomplish a goal, and the most important criteria is speed, not quality. It doesn’t need to be pretty. It doesn’t need to last forever. It just needs to hold up long enough to serve a short term function.

Imagine you’re a race-car driver, today is the last race of the season, if you win your team could take home millions. Some important mount in your car has broken. You’ve got a roll of baling wire. You need 2 things: for your car to be ready when the race starts, and for your car to last one more race. You grab the baling wire, wrap the 💩 out of the thing that needs to be held up, and drive! It doesn’t matter if the car falls apart afterwards. What matters is that you’re back in the race.

That is not a crap solution. That is a glorious solution. That solution solved a problem, and gave a team the opportunity to get paid, and possibly become famous.

Imagine your company is trying to decide if they should spend the next 3 months building out some new functionality that sounds cool, but no-one’s really sure about. Spending a week slapping together a proof-of-concept “test spike” with whatever tools you have readily available, is a great idea. It doesn’t matter that it doesn’t scale. It doesn’t matter that it only works on Mary’s computer. It doesn’t matter that regardless of success or failure it’s going to be hucked in the trash. What matters is that it proved or disproved the idea in the shortest amount of time possible.

The Importance of Context

The problem with a Duct Tape & Baling Wire approach to coding is that developers are crap at following best practices even when they know they should. Our egos tell us our code is good and we skip writing tests, or only write perfunctory ones. Our brains suffer from “Recency Bias” and assume that because our bad habits didn’t bite us in the ass the last few times, that they’re an acceptable approach.

Duct Tape & Baling Wire are great solutions in specific contexts.

Again, don’t use this technique when…

your code can cause harm, damage, loss, etc.
you are sharing software that people will rely on.
people are paying you for a product that is expected to be “good quality”.

This applies even if you’re putting together a “Quick and Dirty” proof-of-concept. If it has to talk to the production database, then you better damn well ensure you’re not altering records, or overwhelming the server with expensive queries.

That doesn’t mean that you have to take an “all or nothing” approach. You can build a quick and dirty app, while also following best practices within specific areas of it.

The Methodology

Duct Tape & Baling Wire is an approach to software development rooted in the following ideas:

Sometimes fast is better than “good”.
Sometimes accepting risk, is better than guaranteeing control.
Sometimes “works for me”, or “works for now” is all that matters.

Duct Tape & Baling Wire is…

recognizing that sometimes it’s ok to write “bad” code.
embracing the clumsy, inelegant, nature of a bodge.
choosing easy, and fast, over elegant, and good.
finding and using tools that already do what you need.
not caring that you don’t know how something works.
accepting that if it breaks, you won’t be able to fix it.
connecting things that were never intended to go together.
not worrying about efficiency until you need to.
looking outside your bubble for other people’s solutions.
buying a hammer, instead of making one.
being thankful for the Unix Philosophy.
knowing that sometimes using Duct Tape and Baling Wire is a terrible and/or dangerous choice, and taking the time to do the right thing when it is.

Duct Tape & Bailing Wire is not…

code you want to show off.
appropriate for anything you’re selling.
good for maintainability.
good for collaboration.
acceptable when other people can be harmed.

GraphQL Thoughts

Wed, 08 Feb 2023 00:00:00 -0500

Table of Contents

Intro Thoughts

I’ve been mostly avoiding GraphQL and watching from the sidelines. I’d been forming an opinion but wanted to actually understand it a bit better before really deciding.

Well I’ve just gone through a course on it, and I am very sad to say that my impression has not changed.

GraphQL is, in most cases, a way for teams within your company to avoid discussing their needs with each other. Resulting in massive inefficiencies that are plastered by yet another layer requiring additional maintenance and code. For bonus points, it’s pretty much guaranteed to break because you’re plastering over human communication and coordination problems with technology.

The exception to all this is when you’re building a GraphQL layer to plaster over other companies’ APIs you have no ability to influence. Honestly though, that’s rarely how people are using it.

Promises

Only Retrieve The Data You need

Translation: don’t bother to discuss your needs with the team creating the primary API so that they can create an endpoint that only produces the data you need. Instead do lots of unnecessary calculations in the original API, marshall, and then ship unwanted data over the wire, unmartial, process, and filter that data, to get just the bits you care about.

Fewer requests

Example: Instead of hitting one endpoint, getting a list of objects, and then retrieving each of those objects in separate requests, you can use one GraphQL request.

Translation: don’t bother discussing your needs with the team creating the primary API. Instead, insert additional processing and latency into the system, and convert N requests into N+1.

Get Data in the appropriate shape

Example: The API returns data in structure A, but you need structure B.

Translation: don’t bother discussing your needs with the team creating the primary API. Instead, insert additional processing and latency into the system, and convert N requests into N+1.

Your query’s shape will match the shape of the response

Why is that a good thing? Are you suggesting that It would be better to somehow draw a matrix of values when querying a database instead of using SQL?

How about using query languages that are specific to the domain instead of having no bearing on the domain but having a passing resemblance to the shape of the data coming back.

Moves much of the data filtering and parsing back to the server

Translation: don’t bother discussing your needs with the team creating the primary API. Instead, insert additional processing and latency into the system, and convert N requests into N+1.

An API reference document for people using it

Great, but that’s not unique to GraphQL, and there’s no need to use GraphQL to get that.

Combine data from multiple systems in 1 response

This isn’t bad. However, it does raise a lot of questions around “why” and if it really is a good thing to pretend that it’s one homogeneous thing. I can imagine a number of cases where this is good. I can imagine a number of situations where this is good. They mostly involve lots of microservices which is a thing that lots of companies talk about, few companies do, and most companies that do do regret for a variety of reasons that are mostly not communicating and not thinking about implications of choices in context of the full system.

Subscriptions

Cool. My initial question was “Why is this better than WebSockets?” Turns out, it isn’t. Subscriptions are usually implemented with WebSockets. The “usually” part of that is disturbing as 💩 to me, and raises all sorts of warning flags.

(Implied Promise) Look Ma, it’s almost JSON

Either use JSON or don’t. Don’t use some half-assed quasi-JSON thing that promises familiarity via JSON and then promptly kicks you by leaving out commas and colons half the time. Not all the time… just some of the time.
The Java geeks thought XML was pretty hot back in 2010. They tried rewriting everything in it too. Look how well that worked out.
Use the right tool for the job, not the popular tool. As query languages go JSON, and JSON-like things, are kinda crap.

Counterargument

Yes, but sometimes those other teams can’t give us what we want when we want it.

That’s a human problem that needs human solutions not technology solutions: planning, coordination, prioritization, working together, and being smart enough to not introduce unnecessary tech debt.

If you company’s internal communications are that dysfunctional you should be spending energy on fixing them, not plastering over them with yet another layer of technology that will never solve the fundamental problem. Ditto if the problem is an inability to work together in a coordinated fashion.

Talk to each other. Work together. Don’t try and convince yourself that that’s ever something you can work around with technology.

Notable Things about Pathfinder

Sun, 05 Feb 2023 00:00:00 -0500

Table of Contents

A friend asked what was notable about Pathfinder 2nd Edition in comparison to D&D 5th Edition.

I thought I’d write up my thoughts because he’s not the only one wondering that these days. Note that the following are in no particular order.

Ancestries not Race

Even if we set aside the problematic idea of “race”, your biology only plays a small part who you grow to be. Pathfinder acknowledges this.

Ancestries express the culture your character hails from. Within many ancestries are heritages— subgroups that each have their own characteristics. An ancestry provides ability boosts (and perhaps ability flaws), Hit Points, ancestry feats, and sometimes additional abilities.

Ancestry can be thought of as “species” most of the time, whereas “heritage” is more about the environment you grew up in. Your biology provides biological advantages and disadvantages. So does the environment you were raised in. Ancestries also provide “feats” you can take as you level. For example, a Dwarf could take “Dwarven Lore”, or various things related to familiarity with stone as a result of growing up underground.

The book comes with 6 common fantasy ancestries. However, if you include all the additional content (see below) there are 31 Ancestries to choose from.

Backgrounds are more meaningful

In D&D Background is mostly just about providing some story flavor for your character. It doesn’t really have much mechanical effect. In Pathfinder each background gives you 2 ability boosts, as well as skills that you are “trained” in.

Skills

While your character’s ability scores represent their raw talent and potential, skills represent their training and experience at performing certain tasks. Each skill is keyed to one of your character’s ability scores and used for an array of related actions. Your character’s expertise in a skill comes from several sources, including their background and class.

You can get better at your skills over time, and they’re actually specific things that not every character has. Each skill has a level noted as untrained, trained, expert, master, or legendary. They’re specific and interesting. For example under Acrobatics we have “Tumble Through” (allows you to try and move through an enemy space), under Arcana there’s “Borrow an Arcane Spell” which lets you “borrow” a spell from someone else’s spellbook during your day’s spell preparation.

Feats aren’t just abilities

Feats do give you new capabilities, but they also serve to add more flavor to your character. “Hobnobber” lets you gather more information through conversations. “Lie to me” lets you trip up people trying to deceive you. “Impeccable crafting” means that your crafting skills are so good that a successful Specialty Crafting roll is automatically a critical success.

Character Creation is easy

While the number of options is potentially overwhelming to a new player, they guide you through the process step by step, and also explain what every aspect of the standard character sheet is for. As you are choosing aspects of your character they tell you exactly where to put it on the character sheet and what numbers go where and where they came from.

The Archetypes

For each of the primary classes Paizo has created an “Archetype” character. These are the characters you see being heroic in all the Pathfinder art. These characters serve not only to give you concrete examples to point to while learning the game, but they’re also all actual characters that beginners are encouraged to play.

So Many Classes

Wizards of The Coast hasn’t put out many classes for 5th edition. Pathfinder’s core book has the same 12 classes as D&D, but if you include the additional content they’ve released there are 21 possible classes. These are all available for free online.

To me this is notable because there’s obvious demand from players to be able to express cool ideas for their characters that don’t quite fit into the existing classes. People are constantly homebrewing D&D classes, but as a DM I don’t want my players to use them, because I don’t know if they’re even remotely balanced. They could have glaring flaws that make them annoying to play, or completely overpowered relative to everyone else in the group. I don’t want to have to spend hours trying to figure out the potential long-term consequences of the choices of someone’s random homebrew.

Pathfinder’s classes are by folks who do this for a living. There’s a reasonably good chance that even if they have faults, they’re not going to have a significant effect on your fun. More official classes, means more options for players to express their ideas without accidentally causing problems.

You Don’t Need To Buy Books You Don’t Need

You should probably buy the core book, but if you wanted to play a character with the Oracle class, you could just look it up online. The Archives of Nethys has all the official content online. Paizo has released everything under the OGL so it’s completely legal. Yes, Paizo would like you to buy their books, but they don’t seem interested in trying to convince anyone to buy an entire book just to get the one new species or class that you want even when you don’t care about anything else in it.

Details Details Details

Many D&D players feel a bit overwhelmed when they see the size of the core book. It’s more than twice as big as the D&D Player’s Handbook & the D&D Game Master’s guide. The main difference is that Paizo is giving you everything you need to play. They’re not trying to trick you into paying more by splitting it into 2+ books. They’re not hiding GM info from the players. Everyone is an equal participant and they’re not being greedy.

Much like the overwhelming size of the book, the rules can feel overwhelming to new players too. There’s more of them and you can do more on your turn, and everything’s more detailed, and, and, and… D&D’s authors tend to be very imprecise and ambiguous in how they describe things. This feels less overwhelming, but it means that you’re going to have a lot of debates at the table trying to figure out what the hell the authors meant or if they even considered the implications of this thing being used under these circumstances.

Pathfinder’s authors on the other hand have taken the time to explain everything very clearly. You’re not going to have many table debates where everyone’s trying to guess at the intended meaning of a rule, and if you should use that, or what it says even if it doesn’t make sense. Instead, you’re going to just look at the rule, read it, and do what it says. Pathfinder asks for a tiny bit more work up front, in order to let you understand everything better while playing. At the worst you’ll take a moment to look up a rule, and then go on, rather than look it up, and have a debate about it.

Bookcraft

The Pathfinder 2e Core book is, in my opinion, the best example of good bookcraft in the Tabletop RPG world. On the edge of the every right page is a section guide with the current section highlighted, so you can easily flip through it. Iconography is used throughout to help convey inportant information quickly. For example, there are icons next to abilities / spells that take more than one action to perform that make it clear if it takes 2 or 3 actions (Pathfinder has 3 actions per turn). The way they use headings and colors also makes it very easy to visually scan a page. It’s just an excellent job that every TTRPG publisher would do well to emulate.

The World

The canonical setting is called Golarian. It feels rich, and well thought out, with different peoples and spread across the world. In many ways it’s a collection of common fantasy tropes that have been spread out over the lands so that you can choose the type of common fantasy thing you want to deal with and stay in an area that’s centered around that idea.

For me Glorantha (the setting for Runequest) feels so detailed and specific that I enjoy reading about it, but am uncomfortable playing in it because I know I’d be getting something “wrong”. Golarian (Pathfinder’s) meanwhile feels, to me, that it’s been described well enough for me to have a basic familiarity with a given area, but not so much that I feel like I’m “doing it wrong” when I start improvising things about it.

I wouldn’t be surprised if there were just as many, if not more, details available for Paizo’s world, but somehow Paizo’s stuff comes across more as “hey, here’s an option if you want it” rather than “This is the way the world is!”. The core book contains roughly 30 pages giving you a basic overview of each of the main areas with half a page of description and an inspirational image.

The supplemental books are written in such a way that it’s easy to take the content and use it in other worlds, which makes them really valuable even if you don’t play Pathfinder.

All The Colors of the Rainbow

Paizo has fully embraced modern thinking about race/species, gender and sexuality. Two of the archetypes are canonically in a lesbian relationship. There are gender neutral characters. They specifically encourage the use of pronouns.

That being said, some of the stuff has been around for a long time. Rise of the Runelords (one of the more famous Adventure Paths) came out for Pathfinder 1st edition in 2007, and sometimes the heterosexual assumptions are revealed. It’s been updated for 2nd edition rules, but I don’t think Paizo has bothered to have a sensitivity reader take a look at it.

The Adventure Paths

Pathfinder offers something I wish every TTRPG publisher would offer. They call them “Adventure Paths”.

Every month, the Pathfinder Adventure Path brings you a new installment of a multi-part series of interconnected quests that together create a fully developed plot of sweeping scale and epic challenges.

With two complete campaigns every year, Pathfinder Adventure Path offers a diverse and ever-growing catalogue of themes, challenges, and play experiences. - Paizo.com

It’s somewhere between a magazine subscription and a Patreon. You subscribe and every month they send you the next installment in a 6 month campaign at a 30% discount. They get a constant stream of money to stay in business, the world gets bigger, and you subscribers get more content to run for their players. These are also high quality, high production value adventures by professional game designers that Paizo will then sell separately.

What about Starfinder?

Superficially Starfinder looks like “Pathfinder, but Sci-Fi”. The reality is more nuanced than that. First, it’s actual sci-fi, not “let’s give your sword swinging fantasy characters a spaceship” like Spelljammer.

“[Paizo creative director James Sutter] cites the Star Wars, Alien, and Guardians of the Galaxy franchises among the films he and his team drew from for Starfinder, which is set thousands of years in the future of Paizo’s blockbuster Pathfinder franchise. Firefly and The Expanse also make the list, along with the comic book series East of West and Saga. - Vice.com

Starfinder shares its setting with Pathfinder, set in its far future after Golarion, the planet that Pathfinder was set on, had mysteriously disappeared in an event called “The Gap”. The history of the planet during the disappearance is lost to all races, preventing players from returning and interfering with previous events in the Pathfinder timeline, while also acting as the foundation of Starfinder’s own timeline. Because Starfinder shares its past with Pathfinder, races and monsters of the Pathfinder setting persist in the Starfinder universe alongside new alien races from other worlds. Magic remains a part of the game’s mechanics, often intertwined with high-level technology. In the time since the Gap, allied races formed an alliance called the Pact Worlds for diplomacy, trade, and technological sharing, with Absalom Station as their focal point for these activities. An organization called the Starfinder Society, based on Absalom Station and other planets, was established to seek out pre-Gap technology and any information that may have explained what happened prior to that event. - Wikipedia

The game was released roughly 1 1/2 years before Pathfinder 2e. As a result, Pathfinder benefits from a fair amount of additional gameplay and rules refinement before its release. Like pathfinder

What Next?

Maybe watch this Video by The Rules Lawyer discussing his “10 Reasons Pathfinder is Easier To Run Than D&D 5e”. If you’re even remotely interested in D&D style gaming you should totally pick up a copy of Pathfinder 2e.

Pathfinder 1st Edition was an obvious, unabashed rip-off of D&D 3.5 when Wizards of The Coast got greedy upon the release of 4th edition. Pathfinder 2nd edition feels like Paizo asked itself “What would it look like if we updated with everything we’ve learned since then.” Basically, the same thing the D&D folks did, but they took the same lessons and applied them differently, and created their own thing with Pathfinder 2nd Edition.

Want to learn about how to play? Check out this episode of the RPGBOT.podcast where they discuss How to Play Pathfinder Second Edition (Part 1). Part 2 gives an example of character creation.

Obligatory Disclaimer

I’m a mechanics geek. I read tons of TTRPG books, but only play a few. I haven’t gotten Pathfinder to the table yet, and I definitely haven’t played it from 1st level to 20th. That being said, I have read a lot of TTRPGs and I have a ton of respect for what I’ve read in Pathfinder.

I’d choose Pathfinder over D&D any day of the week. D&D’s ambiguities drive me nuts. As a DM I hate the way 1st level characters are hard to keep alive. I hate that once characters get past 10th level combat just feels like the DM is making up bullshit rule exceptions for the monsters to be able to stay alive for more than two rounds against players. “oh it’s a ’legendary action’”. Arrgh.

If given my druthers I wouldn’t choose either though. There are so many amazing games out there that aren’t just another take on the core mechanical ideas D&D came out with decades ago. Cypher System is one of the most elegant games every written. FATE is so flexible and good. We are truly in a Golden Age of TTRPGs.

If you want to play Pathfinder I think you’ll have a blast. If you’re just looking for something “not D&D” Pathfinder is a great choice, but there are lots of other great choices that might be a better fit for your group. If want some help finding something ask me on Mastodon.

Don't Overthink Your PKM

Sat, 14 Jan 2023 00:00:00 -0500

Overview

It’s important for all knowledge workers to have a Personal Knowledge Management System (PKM). That doesn’t mean you need a fancy tool, or a complex process. Sometimes, the “stupid simple” solution is the best one.

To that end, I wanted to talk through my wife’s system. It’s an important example because her choice to specifically not use any of the fancy purpose built tools has resulted in a better solution for her needs.

For context: she’s a Developer Educator. This is a fancy way of saying she documents APIs and writes code. Her job is to help other people understand how to use various libraries and tools.

Her Process

When she needs to look up a piece of information twice, she records it.
When she finds herself repeatedly performing the same task, she automates it.

There’s no hard number of times here, and the “automation” can be trivially small.

Her PKM

There are two primary kinds of information in her PKM:

documentation on how to do something
code snippets that she’ll want to reuse

Her Needs

Easy access to the information without having to switch contexts / apps. She is working in VS Code when she needs to access this information.
The code snippets need to be in a form and location that makes it easy to bring into her apps.
She needs to be able to share these snippets & instructions with the people she mentors, and people new to the project.

That’s it.

VS Code…

has reasonably good search functionality
lets you easily browse directories
has good Markdown syntax highlighting

So, all of the “personal knowledge” she needs to “manage” is stored in a collection of Markdown files in a hierarchy of folders that makes sense to her 🧠.

She checks those files into a git repo, which she regularly pushes up to GitHub. Having the files in GitHub means she can easily link her coworkers to a relevant page whenever needed. It also lets her link to a specific line or paragraph within a document, and gives her another backup location.

It’s a nice, simple, and elegant solution.

Summary

There is a plethora of apps to choose from that do a good job of managing collections of Markdown documents. There are even some specifically for developers, but…

The content would no longer be available to her within VS Code.
She’s satisfied with the search and browse functionality it provides.
She has no complaints about the UI she has to use to find the information she needs.
They’d hamper her ability to share.

Her simple system is perfect for her 🧠, and her current needs. It also includes a simple process for deciding what to capture, and what to take further action on.

People get caught up in searching for “the perfect tool” or “a better tool”. Developers sometimes get sucked into the idea of writing a better tool… Sometimes the simple solution really is the best one.

Her solution is not the right solution for my brain or my needs. But that doesn’t matter. What matters is that, we each figure out what’s right for our brains. Start simple, and don’t chase shiny objects.

Other People's Personal Knowledge Management Isn't For You

Sun, 08 Jan 2023 00:00:00 -0500

Table of Contents

“Personal Knowledge Management” (PKM) feels like a lot of “bullshit” to many people. In this, I will speak to the idea that PKM isn’t bullshit. It’s just that other people’s ways of managing knowledge, just aren’t designed for your brain. They may sound like bullshit, but if it’s working for it’s creator, it’s totally valid.

…a great proportion of the variance in “knowledge management” effectiveness across individuals is genetic. Individuals blessed with high degrees of industriousness and orderliness will build sophisticated media diets, note-taking systems, and automated archiving pipelines much more effectively than those less blessed with these traits.

Next, these naturally organized people realize they’re sitting on a valuable commodity, which they can sell to less industrious and orderly people. Some random nerd who just loves organizing all his little files decides to christen his idiosyncratic personal routine with a catchy name, package it as the best method for helping anyone get organized, and then thousands of less organized people pay him to learn it. - Justin Murphy “Personal Knowledge Management is Bullshit”

Justin’s sentiment is valid. It touches on some real “bullshit”, but this line of thinking is fundamentally flawed. It fails to grasp the incredible variance in human minds. Many of the people who’ve designed successful systems haven’t done so because they’ve been “blessed with high degrees of industriousness and orderliness”. Many of them are as a reaction to significant losses in the “genetic lottery”.

Knowledge Management As A Survival Trait

Let me give you an example from personal experience that I’ve seen repeated again and again in others. People with ADHD have incredibly bad memories. It’s not just that their memories are bad, it’s that they’re implausibly bad by normal standards.

Memories form around interesting things. An event is “interesting” on a chemical level, if there’s some dopamine involved. No dopamine, means no interest. No interest means your squishy greymatter decides it isn’t worth remembering. This is an oversimplification, but the point is, we are literally disabled and lacking one of the primary tools required for knowledge work.

As a result, every knowledge worker you meet with ADHD is essentially guaranteed to have an impressive system. It may not be efficient, or logical, and they’re probably not even aware that that’s what they’ve done, but it’s there.

I don’t spend time building knowledge management systems, and tools because I like organizing information. I build them because I’m fucked without them.

It’s not you, it’s me.

It’s not that other people’s systems are “bullshit”. It’s not that people with impressive PKM systems are inherently more organized than you. It’s that your brain, and their brain, are different.

The deep and urgent sense that we’re all drowning in information and distraction has created a massive market for anything that claims to solve this problem.

He’s right, and he’s right that most of those tools are unlikely to work well for your brain. That doesn’t mean there isn’t value in them.

Zettlekasten, for example, is an interesting innovation in knowledge management. It has some rabid fans. The short version, if you haven’t heard of it, is that you build up a collection of small ideas with free-form linking to each other. No folders. No time wasted organizing.

The method originated with paper note cards. These days there are many easy-to-use tools for folks who like Zettlekasten. Many of the popular note management tools have Zettlekasten related functionality built in.

The reason I mention it, is that the Zettlekasten process 100% doesn’t work for my brain. That doesn’t mean it’s “bullshit”, or useless. There is great value in the idea of having a system that makes it trivial to link from one document to another (see also, the internet). I believe that if your notes aren’t linking to each other you’re missing out on a huge piece of value.

There’s great value in the idea of focused notes, but the separation of those notes into discreet chunks is a problem for me. There are too many simultaneous thoughts in my brain (ADHD). If I was constantly pausing, even momentarily, to create new notes I’d loose the thread of what I was trying to express. This means I lean towards tools that make it easy to group thoughts in malleable hierarchies.

Those individual chunks are focused notes. I can use an auto-generated table-of-contents to find them. As content becomes too much for one document I can break things out into multiple documents and cross-link.

Surviving The Torrent Of Information

Many of us feel overwhelmed by the information torrent we live in. Our brains did not evolve for this. Our jobs, none-the-less require us to deal with it.

As a programmer I’m expected to stay up to date with the latest technology options and trends. I’m expected also put in a full day of work on whatever projects they’re paying me for. Meanwhile there are millions of people discussing and releasing software that may or may not be useful to me.

It’s literally impossible for me, or anyone else, to meet all those expectations. Doubly so if you want to actually maintain your mental health and have a life outside of code. I have two choices. Develop a process to help me attempt to stay up to date with things, or fall behind.

Falling Behind

I’d argue that “falling behind” is not only a valid strategy, when applied strategically, but one that can make your life better.

Ignore the things you don’t need

I’ve been a web developer for a long time now. My primary tool of choice for building interactive web sites is Rails. There are two major aspects to Rails: the back end, and the front end. The back end is all the stuff you can’t see. The database interactions. The gathering of data for reports, etc. The front end is similar but it’s a collection of tools for generating the actual web pages you see.

Every few years the core Rails developers come up with some fancy new way of generating web pages that is objectively better than the old way. Yay progress. Each new way is notably different from the last.

Meanwhile, I’ve been working on codebases that are either too outdated to use the new hotness, or don’t even use Rails’ front-end.

My employers want me to “Stay up to date” with the latest Rails functionality, but there’s a huge chunk of it that would be a complete waste of my time to pursue. I can’t use it. Knowing it won’t help me in my personal or professional projects. When it’s relevant, but not something we can use, it just becomes depressing.

Learning it in depth would have been functionally useless, and emotionally depressing. So, I chose to ignore it. Then the Rails devs came out with another bit of “new hotness” and the old stuff I didn’t learn became obsolete. Then it happened again.

Yes, I am at a disadvantage compared to others when I do need to make something with an HTML front end. Accepting that has enabled me to really focus on doing great back-end work. Back-end work is important to me, interesting to me, and valuable to my employers. They’re perfectly happy to have other people who are experts in front end stuff do great jobs there while people like me focus on doing back-end work.

The point is that it doesn’t matter what other people tell you you need to stay on top of. It doesn’t matter what information they claim you need to have. You are the person doing your job. You are the person best suited to determining if that information would actually be useful to you.

I’m not suggesting you ignore the things other people tell you are important. I’m suggesting that you consider their suggestions within your own personal context. Focus on the ones that will help you. Allow yourself to “fall behind” on the ones that won’t.

Less is more

Every time you make a decision to actively ignore something that won’t help you, you lessen the torrent of information. It’s like standing in a rushing river, and then suddenly being able to divert some of it. You no longer have to fight as hard to stand up. You no longer have to filter so much of it to find the tasty fish.

Observe, Try, Steal, Refine, Repeat

Barring a total collapse of society, the torrent of information will not lessen within our lifetimes. No-one has a good handle on the problem. Few people comprehend the variety of human thought patterns. They don’t understand that their techniques aren’t applicable to everyone.

The techniques you and I have developed so far, for dealing with this likely have a lot of room for improvement.

The best we can do is to keep our ears open for things that work for other people. We can try out the suggestions that resonate with us. We can steal the pieces of them that actually work for us. We can refine our process with what we’ve learned, and repeat.

Yes, this is someone telling you that there’s some information out there that you should be paying attention to. That irony isn’t lost.

There are two advantages this type of information has that many of the others do not. The first is that learning how to better organize your knowledge is explicitly a tool for helping you. No-one will argue that you shouldn’t get better and oraganizing your knowledge.

The other is that I’m specifically referring to knowledge management techniques not tools. New techniques are rare. Truly innovative techniques are even rarer. Meanwhile, there will continue to be a constant stream of new tools. They’re not even someone’s “idiosyncratic personal routine with a catchy name”. They’re someone’s idiosyncratic implementation of a poorly understood idiosyncratic personal routine… with a catchy name.

I’m not suggesting you should try and stay up to date with Notion, or Roam, or whatever comes next. I’m suggesting you should try and keep an ear out for how people are using their fancy tools. This is, admittedly, harder. Fortunately there are people like Tiago Forte who are putting out lots of great content about techniques, not tools.

This takes many forms:

organizational techniques
note taking techniques
learning techniques
information processing techniques

It’s a deep rabbit hole, but you don’t need to go down it if you don’t want to. Just pay attention to the people who are and listen to what they report back.

What Now?

As I said, don’t focus on tools, and don’t believe that anyone else’s specific process is going to work for you. Focus on high level techniques and approaches.

For How to think about capturing and organizing information I’d suggest Tiago Forte’s Building A Second Brain is a good place to start. The book is very much about approach not tools. The first two chapters are going to convince you of the value of keeping and managing your info. You can skip them entirely if you already believe that.

I’d also recommend checking out this YouTube playlist of his which does a great job of showing a collection of radically different, but equally valid, approaches for capturing and organizing information. Each one is tailored to the brain of its creator.

Define a process for yourself. If you’re not sure where to start, start with Tiago’s C.O.D.E. + P.A.R.A. technique. It’s described in his book, but there’s a pretty comprehensive summary here.

Mastodon Ownership

Wed, 21 Dec 2022 00:00:00 -0500

Overview

A group calling itself “Mask Group” has purchased three of the largest mastodon instances.

Mastodon users, especially people on those servers, should be very concerned.

Why?

There are some things you need to consider about mastodon to understand why this is very concerning.

Large Mastodon instances are expensive to run.
Mastodon is not a good platform for large advertisers for a number of reasons.

This means that by buying a large mastodon instance you are signing up for a very large ongoing cost in a system whose current state is adverse to profit generation for the owners. If we assume the purchasers are not complete idiots there are 2 solutions to this problem.

Follow the Microsoft playbook of “embrace and extend”.

People don’t like switching servers. If you buy all the big servers you have a functionally captive audience. Disabling the ability to move your account to another server is easy, and gives you an actually captive audience. They won’t want to loose all the connections they finally just built up again after moving to Mastodon.

If you control the servers that millions of Mastodon users rely on and can’t easily escape, you can also show ads to millions of Mastodon users. You can also start doing all the uncomfortable tracking that many of us came here to get away from.

Massively Disrupt Mastodon itself

Elon has made it clear that he really, really doesn’t want anyone migrating to Mastodon. Your account will be suspended if you dare to mention mastodon.com.

“tens of thousands of dollars a month” for each of a handful of servers is a rounding error to someone as rich as Elon Musk. He probably earns that much in interest in the duration of a sneeze.

What if Elon, or anyone else keeps buying up the largest instances, waits until they have a simple majority of the mastodon user base, and then simply shuts them off?

People can’t migrate their accounts, and millions of people loose confidence in Mastodon. Especially if the people behind “Mask Group” are never exposed. You can’t blame Elon, or anyone else. It was just some “mysterious group”.

“Mask Group”

Seriously. These purchases are nonsensical unless combined with plans that only hurt us. Combine that with an entity calling itself “Mask Group” and you don’t have to be a conspiracy theorist to connect the dots. They put it right there for all to see.

Servers Currently Affected

mstdn.jp
pawoo.net
mastodon.cloud

What’s the answer?

Small servers with people who you either know, or who are organized around an idea or world-view that works for you.

Once a server exceeds the number of people a human can reasonably “know” (Dunbar’s Number) a number of problems emerge.

Some people feel Anonymous. Penny Arcade explained this problem well:

penny arcade
They can’t be a community of like-minded people, because they’re too big to be a unified group.
They’re also really difficult to moderate because you always have some problematic elements who don’t adhered to your server rules because they don’t care or don’t feel they apply to them. See also issue number 1.

Summary

If your server is bought by Mask Group you should run away before you can’t.

If your server is large and you’d like to be with people of a similar mind, move. If you like the chaos of a large one… stay, but keep an eye on who’s running it.

Stux has promised not to sell mstdn.social but I find it hard to believe that a concrete offer of a billion dollars wouldn’t sway him. That’s beyond life-changing money for most humans. That being said, it’s unlikely anyone would really offer them $1B for a million users. So, if you want a big server, I’d stick with theirs.

Rewriting Hey

Sun, 18 Dec 2022 00:00:00 -0500

Table of Contents

Overview

“Hey!” started as an Interruption Tracker, and now supports Time Tracking too. It has been through 3 iterations: Chicken Scheme, Crystal, and now Raku. This post is a high-level developer’s diary of what I wrote, why I rewrote it, and what I learned along the way.

In the Beginning

Once upon a time I was a tech lead, team lead, and eventually principal engineer. My days were filled with interruptions. They were making it impossible to get anything done, and more importantly to me, they were a source of a lot of stress.

I decided that if I was going to get a handle on the interruptions I needed to understand them. I needed to know when they were happening so that I could plan focus time. I needed to know who was interrupting me so that maybe I could talk to them about it. I needed to know why I was being interrupted so that I could find things I could document better to preempt those interruptions.

It started out as a little Chicken Scheme script that grew organically. It quickly became a hard-to-maintain hairball of code.

But it worked, and it was good.

Final Totals

~1300 lines of Scheme
~2500 lines of JavaScript (mostly library stuff) to support some fancy “graph it via the web” stuff that never really worked out well.
~1000 lines of HTML to hold the JavaScript graphing stuff.
GitHub Repo Here

Writing in Chicken Scheme

I love Scheme. It really works for my brain. Chicken Scheme is one of the better schemes. It’s got a large collection of useful libraries. It also transpiles to C (or JavaScript actually). The end result is a fast tiny binary. As a bonus, you can generate C files so that your libraries can be called from almost any other language.

As an example, my private_comments API web server runs in less than 7MB of RAM and I didn’t even try to make it small.

Unfortunately figuring anything out in Chicken Scheme felt like pulling teeth. There’s a ton of documentation, but it’s mostly useless. It assumes a ridiculous amount of knowledge and doesn’t explain anything. It feels like “Here’s the method signature. Have fun figuring out what it does.”

Getting anything done in Chicken Scheme feels like a major accomplishment. It’s also incredibly draining because it’s so damn hard to figure out if you’re new. It’s not the language’s fault. The language is trivially easy, like all Schemes. It’s the documentation.

These days I use Chicken Scheme very strategically. For example, my CLI heatmap generation tool is written in Chicken Scheme because I wanted something very fast. I also liked that folks could use the core library in any other language if they felt like dealing with their language’s C interface.

Delusions of Sharability

I should also note that I was working under a mistaken belief. I believed that it would be possible to generate a binary for an OS that I could just hand to someone without them having to know anything about Chicken Scheme, or Go, or whatever it was written in.

The truth is, you can’t. It’s theoretically possible. If you could fully statically link a binary, you’d have no worries. Unfortunately it turns out that that, practically speaking, that’s impossible on macOS. They really, really want you to use dylibs. Excluding apps with a “hello world” level of complexity, I’m not sure you can do it.

I spent a lot of time and energy trying to make this happen, but ultimately had to abandon the hope.

Crystal Lang

I’m a Ruby dev by trade, and Crystal is, essentially, just a compiled ruby with Static Typing. Or, it was at the time. These days it’s added concurrency and parallelism and is growing into its own thing.

I wanted to rewrite it in a nice, organized, maintainable way. At the time Crystal was still pre-1.0 volatile, and didn’t have a ton of users or projects. There were, and I think, still are, multiple ORMs (Object Relational Mappings) competing with no clear winner.

Unfortunately, they were very immature tools. So, I took one that I thought was good, and added in relations like “has many” and “belongs to”.

I thought. I planned. I organized. I Object Oriented the 💩 out of it. I wrote and used a sparkline library for Crystal. I wrote a CLI bar chart library for Crystal.

I added a CLI bar-chart graph of interruptions by hour so that I could easily see when I was being interrupted.

$ hey report interrupts_by_hour
Interrupts By Hour:

                                          ▁
                                          █
                                 ▁     ▁  █
                                 █     █  █
                                 █     █  █     ▁
                           ▁     █     █  █  ▁  █
                           █     █     █  █  █  █
                           █     █     █  █  █  █
                           █  ▁  █     █  █  █  █
                           █  █  █     █  █  █  █
                           █  █  █     █  █  █  █
                           █  █  █     █  █  █  █
                           █  █  █     █  █  █  █
▁  ▁  ▁  ▁  ▁  ▁  ▁  ▁  ▁  █  █  █  ▁  █  █  █  █  ▁  ▁  ▁
00 01 02 03 04 05 07 07 08 09 10 11 12 13 14 15 16 17 18 23

Honestly? It was pretty damn good.

But then, my life changed. I was completely burnt out from the constant interruptions. I was having random Panic Attacks over trivial things. My wife was burnt out too. We quit our jobs, cashed in the 401k and lived off of savings for the better part of a year. It set back our retirement, but gave us enough time to begin recovering.

I didn’t need Hey! anymore, so I wandered off.

Final Totals

~1600 lines of Crystal in the core tool (including tests)
~300 for the bar chart lib
~50 for the sparkline lib
~400 for the cli table generator
~150 lines for the custom arguments parser
~300 lines of additions to the DB library (mostly macros)
Total ~2800 lines of Crystal
GitHub Repo Here

Writing in Crystal

Crystal’s a great language. I have nothing bad to say about it. I happily supported them on Open Collective for a long time. If you want to see what I think is a pretty well designed Crystal app, go look at oho. It’s the world’s greatest tool for converting colored terminal output to beautiful HTML. I’m pretty proud of it.

These days though, Crystal isn’t my happy-place. I’ve spent too many years in Ruby. I want something different for my personal coding.

Fast-Forward…

Fast-forward from 2016 to December 2022. I’m unemployed again, like so many of us (Hire Me!), and while I’m actually getting a lot done, I don’t feel like I am. I’m being too hard on myself, and not giving myself the credit I deserve for accomplishing the things I have. I decide to start time tracking. I figured if I could look back and see how I actually spent the day I could have a better feeling for what really happened. “I didn’t get anything done today on my work, but that’s because I spent a ton of time on all these other things that needed doing.”

It turns out, I was right. In addition, the act of tracking my time makes me think about how I’m spending it, as I’m spending it.

I didn’t want to write a new time tracker. I just wanted to track my time. I knew there were multiple, good, off-the-shelf CLI time trackers.

I tried using 3 of them, but they all frustrated me for one reason or another. Some tools wanted me to interface with it in a way that felt awkward or annoying. Some had annoying technical things.

Watson came very close, but every time i needed to backdate a timer i had to type in explicit 4 digit 24 hour time. E.g. 08:30 not 8:30 and 18:47 not 6:47. It’s a little thing but I was doing it at least ten times a day and it annoyed me every time. Also, the ability to edit a timer was just broken.

Then I realized… I already have a time tracker that works with my 🧠. It just doesn’t support end times.

I checkout the Crystal repo. I compile. It goes 💥. It goes 💥 here. It goes 💥 there. It goes 💥 everywhere. The language has changed in notable ways which break my code, and break the code in libraries I was depending on.

In Crystal’s defense, it was 0.33.0 when I ported Hey! to it and they were very clear about the fact that things would be changing before they hit 1.0.

The compiler was very helpful in telling me what changes to make. Eventually though, I hit a case where it was complaining that I wasn’t implementing a method defined in an abstract class, and I definitely was. At that point I gave up. I just don’t have the emotional spoons to go fixing problems I didn’t create in a side-project that I didn’t even want to write in the first place. I don’t particularly want to be writing in Crystal these days anyway.

Maybe the Chicken Scheme version?

Chicken Scheme has moved from v4 to v5 in the intervening years, but Chicken’s upgrade is relatively painless. I’ve already done it for a couple of projects. It’s mostly just a matter of changing some import statements.

20 minutes later and I’ve got a working version of Hey! It’s a worse codebase, but it complies!

Hack. Hack. Hack. Bug. Bug. Bug. I’m fighting with Chicken Scheme again.

“Arrgh! I do not need this. This isn’t even a good codebase to begin with.”

So, I step back. I ask myself what the bare minimum feature set would be that would be good enough to use and not annoy me:

the ability to start and stop a timer
the ability to tag a timer
the ability to backdate a timer because I frequently forget to start or stop them.
no !@#$ 24hr time.
a log of time spent.

That’s not actually that much…

And then Raku

I create a new directory and start hacking. I’m still new to Raku, but overall I’m loving it.

I started by writing about ~250 lines of ugly-ass no-apologies code. I had one goal: get it working in the shortest possible time. 250 lines gets me a DB layer and the ability to start and stop timers (no backdating).

I try to run it. It goes 💥, but that’s to be expected. I have no tests & I’ve literally never compiled it. To my great surprise, the bugs are all little things like missing commas or semicolons. There’s nothing notable.

This is huge. If a Raku newb like me can write ~250 lines of code and not have any notable bugs, it means they have done a damn good job of putting together a language.

I’m chuffed. I keep hacking. Along the way, I’m noticing that lots of little nice-to-have’s are trivial to add while I’m there.

I don’t bother with an ORM. I don’t bother with any OOP (Object Oriented Programming). It’s just a collection of functions that query a SQLite DB with raw SQL and pass the resulting hashes around.

The ecosystem of libraries gets me nice things like time durations as strings “2 hours and 33 minutes” or “2h33m”, and pretty tables. The pretty tables are my fork of another library, but I’m not including that in the totals because I didn’t write it for this project.

I still don’t have the command line graphs implemented, and it looks like I’ll have to port that from Crystal. There isn’t a Sparkline library yet either, so add another ~300 lines of code before I’m done.

Final Totals

~800 lines of Raku
~100 lines of bash_unit tests
~300 lines of future code
Silly levels of satisfaction
GitHub Repo Here

Writing in Raku

Notable things: I wrote precisely zero lines of code to process the command line arguments in a natural language fashion. I wrote zero lines of code to generate or wire up the CLI help doc shown below. Raku gave it to me “out of the box”.

It took me about 5 lines to include a starter db with the package, check if you need it, and put it in place. That’s a combination of the language having a concept of resources in a bundle, a library that understands XDG Base Directory stuff, and my XDG::GuaranteeResources library that combines the two.

Raku’s still got a very small community, but they are “knocking it out of the park” with useful libraries. And the language has been incredibly well thought out. I have complaints, but they’re all nitpicks.

Maybe it’s just that I started my professional programming career with Perl5. Whatever the reason Raku really works for my 🧠.

Usage:
  hey start [<start_args> ...] -- Start a new timer
  hey stop [<stop_args> ...] -- stop an existing timer
  hey log <number> <duration> -- see a log of recent timers
  hey log-interrupts <number> <duration> -- see a log of recent interruptions
  hey running -- lets you know if there are any timers running & what they are for
  hey <name> [<start_args> ...] -- Record an interruption
  hey kill timer <id> -- Remove an unwanted timer.
  hey kill <name> -- Remove an unwanted person / thing from interruptions

    [<start_args> ...]    optional time adjustment, project(s), & optional tags
    [<stop_args> ...]     optional id, and optional time adjustments (e.g. 4 minutes ago)
    <number>              number of duration units
    <duration>            duration string. E.g. minutes, hours, days, etc.
    <name>                name of person / thing that interrupted you
    <id>                  the id of the timer to delete.

Reflecting on the rewrites

Looking back at all this work. I find myself coming to an interesting conclusion. With regards to code written specifically for you:

I believe that choosing subjectively good technology is more important than objectively good technology.

You have limited time to work on projects for you. Don’t spend them in languages you don’t love. Write them with tools, and languages you do love. Write them with tools that are exciting you. Rewrite them when you’ve moved on and you want to use them, but the idea of maintaining the old stuff is just draining.

99% of the tools you write for you will never be looked at by anyone else. Even less of it will be used by someone else. Don’t worry about what’s “good”. Do what makes you feel good.

Chicken Scheme made me feel good. Sometimes it still does. Crystal allowed my to do good things quickly, but it was never Joyful to me. I’m long past the days of Rubyish syntax being Joyful. I like it. It’s good, but I’ve written many many thousands of lines of it and the wonder and joy of it has worn off.

[UPDATE] Since writing this I’ve thought a lot about the choices we make when coding specifically for ourselves vs coding for others. The result is the Duct Tape & Baling Wire Methedology.

Was it worth rewriting all those times?

100%

The first rewrite (Crystal) was in a language I was enjoying, but more importantly it was desperately needed. The original codebase was spaghetti. It had grown without planning, as so many tiny-but-useful tools do.

The second rewrite (Raku) was because I didn’t have the emotional spoons to deal. Fixing problems someone else created, in a tool i didn’t want to be writing, in a language I didn’t want to use… ugh. I didn’t need that.

However, this rewrite also ended up reinforcing my thoughts about how awesome Raku is, and teaching me some new tricks.

If you liked that…

If you found that interesting, you’re probably the kind of geek who writes a bunch of useful command line tools. If so, you should check out TooLoo. That’s my Open Source tool that helps you document your tools. Find them later. Use them more.

P.S. What about the email app with the same name?

Hey! was created before the email service. I figure this project is never going to become popular enough that I’ll have to worry about brand confusion. ;)

How To Receive Twilio Messages In MongoDB Atlas Functions

Mon, 12 Dec 2022 14:12:15 -0500

Overview

There's plenty of documentation about how to send an SMS via Twilio, but very little about how to receive one. Receiving one in a MongoDB Atlas Function involves an extra complication. By the end of this post you'll know how to receive a text in Twilio, and have it successfully interact with your MongoDB Atlas Function. I'll also cover a couple nice-to-have's in Twilio that you'll probably want to set up anyway.

I'm hoping, that you'll discover, like I did, that this Serverless Function in the Cloud stuff is actually pretty easy.

Data Flow overview

The thing you need to know about interacting with Twilio is that it wants instructions from you in XML format. They've done a great job of not only making that XML simple, and documenting it, but also making libraries that make it trivial to generate without ever thinking about XML.

Twilio also makes it really easy to interact with external systems. You just plug the URL of a remote webhook into the appropriate, easy to find field, and you're good.

The problem is that MongoDB Atlas Functions only allow you to return JSON or EJSON. So, even though you can easily generate the XML you need in your Atlas Function, you can't return it. And, to complicate matters, what you tell the function to return, isn't actually what the function returns.

So, let's walk through setting this up. I'm going to skip over the bits that are well documented by Twilio and MongoDB, and focus on the bits that aren't.

Configuring Things in Twilio.

Twilio appears to have two forms of functions in the cloud: "TwiML Bins" and "Functions". You can find both if you click on "Explore Products" in the sidebar of your "Console". Once you click into it, be sure to click the three dots to the right of "TwiML Bins" in the sidebar and choose "Pin to Sidebar". You'll be glad you did.

Rejecting Voice Calls

I presume that most users don't use the voice functionality, so you the first thing you need to do is to refuse voice calls. Like everything else, you do this by giving Twilio instructions in its XML format (TwiML).

Create a new TwiML Bin and call it "Reject Calls".

Here's what it needs to contain.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Reject />
</Response>

Next, go to Phone Numbers > Manage > Active Numbers and click on your phone number. There are two sections "Voice and Fax" and "Messaging". Under "Voice and Fax" You'll see "A Call Comes in". Choose "Twiml Bin" from the first pull down, then your new "Reject Calls" from the second.

I didn't bother with anything else here. I didn't set a "Primary Handler Fails" method either because if they can't talk to their own system, I don't expect them to be able to talk to anyone else's.

You're now done with worrying about calls. Let's move on to the Atlas Function.

Your Atlas Function

First you'll need to create a cluster, and an App Services App. The MongoDB docs can guide you through that. Once you've done that, you go into the App Services App you created, click on the cluster you want to work with, and then click "Functions" in the left sidebar. Then click "Create New Function". Give it a useful name. Make sure the function is not private, and that authentication is set to "System".

npm Packages: You won't need the "twilio" npm package. It just makes life difficult here because of the JSON response. If you're like us and don't want the risk of storing someone's phone number you'll want to hash it. Click "Add Dependency" and add the "crypto" package dependency.

Now, let's make the function. This functions is where your real work is going to happen. In the example below I'm showing you only the core bits you'll probably want to copy. After that I'll give you an example of some input to test it with in their console.

// This function is the endpoint's request handler.
// NOTE: MAKE THIS async TO SAVE HEADACHES
exports = async function({ query, headers, body}, response) {
    const db = context.services.get("MY_LINKED_DATA_SOURCE").db("MY_DB_NAME");
    // we're going to hash the user's phone number because
    // we don't want the risk of storing that personal info

    const { createHash } = require('crypto');

    async function getOwnerObj(db, hashedPhoneNumber) {
      const collection = db.collection("NAME_OF_COLLECTION_WITH_PHONE_HASH");
      // below: phoneHash & ownerId are field names within our data
      // your names may be different
      const query = {"phoneHash": hashedPhoneNumber};
      const projection = {"ownerId" : 1};

      // Use findOne() to retrieve a single document from the collection
      return await collection.findOne(query, projection)
    }

    function cleanPhoneNumber(phoneNumber){
      // our app is US only so the phone numbers will start with
      // the US country code: +1
      // you may not want this, or may need a different regex
      return phoneNumber.replace(/^\+\d/, "");
    }

    function phoneHash(phoneNumber) {
      // it's a good idea to add in some "salt" here.
      return createHash('sha256').update(cleanPhoneNumber(phoneNumber)).digest('hex');
    }

    // --------------------------------------
    // BEGIN procedural code
    //
    // Raw request body
    // This is a binary object that can be accessed as a string using .text()
    const reqBody = body.text();

    // For a full list of parameters they send
    // check out https://www.twilio.com/docs/voice/twiml#request-parameters
    // We only care about who the message came from, and what the message was.
    const { From, Body } = JSON.parse(reqBody);

    // Set up the default data you'll return
    // I've decided to go with HTTP Status Codes, because they've already
    // got something to address most situations.
    var responseData = {
        "status": 200, // 200 if everything goes as expected
        "message": null // the message we'll return to the user
    };

    // hash the phone number, find a matching entry,
    // return it.
    // NOTE: we have to await the response, even though we already
    // awaited the response inside the functions we're calling.
    const ownerObj = await getOwnerObj(db, phoneHash(From));

    if (ownerObj != null) {
        // OK we have a user. Yay.

        // insert your message processing logic here.
        // if anything goes wrong, change the status code
        // in responseData
        // the message will be whatever message you want to return
        // to the user. Note that outbound texts are VERY rate limited
        // in twilio so, only respond with a message when you need to.

        responseData.message="it worked and i found a user";

    } else {
        responseData.status = 403;
        responseData.message = "No registered user with that phone number.";
    }
    return responseData;

};

Notes & Things to change

Note

The default exports function is not async. Be sure to change that.

It looks like you're returning something like this:

{
  "status": 200,
  "message": "my response SMS text"
}

BUT, what you're actually returning is more like this.

{
  "status": 200,
  "statusText": 'OK',
  "headers": {...},
  "config": {...},
  "request": {...},
  "data": {
    "status": 200,
    "message": "my response SMS text"
  }
}

Whatever JSON you chose to return will be stored as the value of the data key in the object that's returned.

Things to Change in the code above

MY_DB_NAME
NAME_OF_COLLECTION_WITH_PHONE_HASH
MY_LINKED_DATA_SOURCE (this defaults to "mongodb-atlas")

Change those to the relevant values. If you're unsure, there are a ton of videos on getting up and running with Atlas Functions "in 10 minutes". Just be aware that they used to be called "Realm Functions". Here's a video from MongoDB that should get you going.

Deploying Your Atlas Function

There's a tab for settings. There are two notable bits for now.

Authentication should be "System" for now.
Make it NOT be private.

You can change these later based on your needs, but for now, this setup will make testing WAY easier.

Deploying is trivially easy. Just save your function. That's it.

Unfortunately, we can't actually talk to it yet.

HTTPS Endpoint

Click "HTTPS Endpoints" in the left sidebar.
Click "Add an Endpoint"
Give it a "route" In our case I made it /tell because our app is called "Tell Remmy" but it really doesn't matter. The general public is never going to see this URL.
Turn on "Respond with Result" If you don't do this you won't get any data back.
The Return Type should be JSON.
Select your function by name.
Don't muck with authentication. If you need to, muck with it once you've gotten things working.
Copy the URL under "Operation Type". Save it somewhere for reference later.

Testing Your Atlas Function

There are two ways to test your function. Once you've got the HTTPS Endpoint set up you can easily test with Insomnia or Postman. "Deploying" your function is so fast, that I find it easier to test by actually hitting the endpoint, and just shoving useful debugging info into the returned JSON.

You can also test on their "console". I'll cover both.

The following assumes you've used the code above, and had a record in the DB with a matching phone number hash. You can also just comment out the code that interacts with the db and just return anything that isn't from that function if you want to just test fast and leave DB stuff for later.

Testing With Insomnia / Postman

Create a new POST request. Paste in the URL you saved when you made the HTTPS Endpoint.

Tell it to use a JSON body / payload. Here's my test one. It's got a couple extra keys in it that you'll be getting from Twilio, but not the full set.

{
"From": "+11234567890",
"To": "+15558675310",
"Body": "an example text message from the user",
"numMedia": 0
}

Run it. See what comes out.

Error messages are half-way decent but don't contain line numbers.

Testing with the Console

Under your function editor is a JavaScript console.

Here's some test input for it:

const textFunc = function(){
	return '{"From": "+11234567890", "Body": "an example text message from the user"}';
}

const request = {
	"query": null,
	"headers": {},
	"body": {"text": textFunc}
}
exports(request, {})

Note that body.text is a function. This is to simulate the real post body that you'll be receiving, and need to call .text on to get the JSON passed in from Twilio.

Stick that in the console, and click Run.

> result (JavaScript):
EJSON.parse('{"status":{"$numberLong":"200"},"message":"it worked and i found a user"}')

Note that if you end up with a problem in your code, console.log(...) is not going to be as helpful for debugging as you'd expect. It will only output anything if the function doesn't encounter any errors. Because of this, and because of the fact that the console is so very tiny with my large font size, I generally don't bother using it.

That's it.

Your Atlas Function is live, working, and callable from Twilio, or anywhere else.

Teaching Twilio To Talk To Atlas

Back in your Twilio console, click on "Explore Products" in the sidebar. Scroll down until you find "Functions and Assets". Click it, and then pin it to your sidebar for easy future access.

You'll need to create a service. This appears to be some sort of grouping of functions. I don't know, and I don't care. I just called it "FooProxy" where "Foo" is the name of the app in MongoDB Atlas that this function is acting as a proxy for.

Click into your new service, and click "Add +" > "Add Function"

Here's what your function should look like:

const axios = require('axios');

exports.handler = async (context, event, callback) => {
  // Create a new message response object
  const twiml = new Twilio.twiml.MessagingResponse();

  //twiml.message("bogus");
  //return callback(null, twiml);

  const instance = axios.create({
    baseURL: "THE DOMAIN NAME OF YOUR ATLAS FUNCTION'S URL",
    headers: { 'X-Custom-Header': 'Twilio' ,
               'Content-Type': 'application/json',
    },
  });

  try {
    // axios#post(url[, data[, config]])
    // const {status, message} = await instance.post(
    const mongoResponse = await instance.post(
      "EVERYTHING AFTER THE DOMAIN NAME OF YOUR ATLAS FUNCTION'S URL",
      {
        "From": event.From,
        "Body": event.Body
      }

    );

    if (mongoResponse.status == 200){
      // remember, or response is in the .data portion of the
      // big wrapper MongoDB Atlas put around it.
      const myStatus = mongoResponse.data.status;
      const message = mongoResponse.data.message;

      // maybe change something if myStatus != 200
      twiml.message(message);

    } else {
      // note: this is MONGO's status, not yours
      twiml.message(mongoResponse.statusText);
    }


    return callback(null, twiml);
  } catch (error) {
    // As always with async functions, you need to be sure to handle errors
    console.error(error);
    // Add a message to the response to let the user know that something went wrong
    twiml.message(`We received your message, but something went wrong 😭 ${error}`);
    return callback(error);
  }
};

Notes & things To Change

We'll need to insert the URL from your MongoDB HTTPS Endpoint into your Twilio Function. It probably looks like this:

https://us-east-1.aws.data.mongodb-api.com/app/cluster-name-abcd/endpoint/my_path

Replace "THE DOMAIN NAME OF YOUR ATLAS FUNCTION'S URL" with "https://us-east-1.aws.data.mongodb-api.com" , or whatever's at the start of yours.

Replace "EVERYTHING AFTER THE DOMAIN NAME OF YOUR ATLAS FUNCTION'S URL" with everything after that. In this example it'd be "/app/cluster-name/abcd/endpoint/my_path

In the instance.post method call, you may want to change the data you're passing on. For us From and Body was the only info we needed, so it's the only info we're passing on. You can always add additional fields later.

Deploying Your Twilio Function

Save it.
click "Deploy All"
Go back to "Phone Numbers" > "Manage" > "Active Numbers"
Click on your number.
Scroll down to the "Messaging" section
Under "A Message Comes In", choose "Function" and choose your function from the resulting pull-downs
Click Save.
Note that they've replaced your function with a webhook url. Don't worry about that. That's normal.

After the first time you just need to "Save" your function and click "Deploy All" to update it.

Testing Your Twilio Function

Go back to your function. "Functions And Assets" (in the sidebar) > "Services" > Click on your service.

Click "Enable Live Logs" below your function. Text your phone number. You should receive the contents of the "message" portion on your phone.

If you don't get a message, and don't see anything happen in the live logs it could be two things:

Live logs simple isn't working. Sometimes it just doesn't. Reload the page.
An error occurred.
1. click "Monitor" in the Sidebar.
2. click "Logs" > "Errors" > "Error Logs"
3. Do not choose "Last Hour". It's broken. Probably a time-zone bug for anyone not in UTC.

If you see an error in the logs, click into it. The most important part is the "Response Body". Almost everything else was useless for me.

If your receive a "not delivered" message from your phone it's probably because you're still on the trial and it will ONLY let you interact with it from your phone number and no other ones.

Note that the macOS Messages app does NOT send from your phone number as far as Twilio is concerned. I haven't investigated what number it is.

Either way, your choice is to just use your phone, tell twilio about another phone number, or just start paying them. I just used my phone until I got everything working and then paid them so that others could use it.

Handling MongoDB Outages In Twilio

Sooner or later, MongoDB's servers will go down. That's what servers do. Twilio's will too, but there's not a lot you can do in Twilio if Twilio's servers are down.

Let's set up a TwiML Bin to handle what we hope will never happen, but probably will.

Create a new Twiml Bin. This one we'll call "Service Failure Fallback". Its contents should look like this.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Oh No! Our Servers are not feeling well! Please try again in a few minutes.</Message>
</Response>

Then go manage your active phone number again, and under the call to your Twilio Function, that calls Mongo, associate your "Service Failure Fallback" TwiML Bin with the "Primary Handler Fails" operation.

Now, if MongoDB Atlas goes down your users will receive a text response with a message that you chose.

Summary

In the end it's pretty easy. It's just complicated by the JSON only responses of MongoDB Atlas Functions. If MongoDB eliminates that restriction, and stops wrapping responses with additional stuff, we can eliminate the Twilio Function entirely, and just use your Atlas Function's url as a webhook in Twilio. We'd also be able to use the twilio npm package in Mongo.

If you've got questions, feel free to ask me on Mastodon.

I used AI to generate products & write copy for my store

Tue, 06 Dec 2022 00:00:00 +0000

Table of Contents

Quick Summary

I used Midjourney to generate art that I threw on t-shirts, coasters, and almost everything else RedBubble offers. Then I used OpenAI to generate copy for it, and combined that with a handful of custom scripts to generate a product site called Bed Bath & The Beyond.

It took about 40 hours of work to put all that together for 13 products, but that will be faster next time. In the end, this is a surprisingly viable option, and the only real restriction on profit is how much effort you’re willing to put into marketing what you make.

It started as a joke…

A friend threw this out on Mastodon.

screenshot of mastodon posts

For a giggle, I asked Midjourney for “UNSPEAKABLE HORRORS AT UNSPEAKABLE PRICES. ALSO, BATH MATS.” and this came out

And they looked “real” enough that I wondered if I could actually make a “cool” bath-mat.

lovecraft & tentacles bath mat

A little editing, and I’d extracted it from the “bath mat”, and thrown it on Redbubble.

the same image on a floor pillow

That’s when things started to spiral out of control.

The work Begins…

Generating images

I spent that night working through images on Midjourney. It was hours of work, but as I was being pretty lenient with Midjourney I was able to get usable results pretty quickly. At the bottom of this post is a screenshot of the stream of images I generated. I’d put it here, but it’s really long. ;)

Prepping images

Then came the editing. By default an upscaled image from midjourney with a 3:2 aspect ratio is only 1536 x 1024 which is fine on your screen, but not so hot for printing.

Fortunately, I’ve actually got a background in print and fabrics are not a high-resolution, or high-fidelity medium. So, upscaling artifacts shouldn’t be a big deal on most things. I’m a bit unsure about the comforters and shower curtains though. Because of this, the acceptable resolution is much lower. Also, RedBubble has this handy page that suggests resolutions for each of their products.

Combine that with Pixelmator Pro’s ML Super Resolution and the upscaling went pretty well.

Most of the images required very little editing.

RedBubble

At this point I’ve sunk at least 10 hours into the process. I’ve made two or three product pages on RedBubble for them. Creating the RedBubble product pages was … work. There’s just no getting around it. It’s a time sink.

In their defense, it requires a lot of subjective human decision making. They’ve also done a ton of work to help folks to promote things. For example, when I click on “Download Images” on the Desk Mat for Billy and Gog’s Grand Adventures I get this excellent collection of promo images to use to promote it.

screenshot of desk mats

Upload, choose, set default colors, save, see what you missed, edit the page to tweak default fabric colors again, repeat.

The site

Hugo is my default static site generator. It’s fast, it’s easy, and I’m familiar with it. So I start making pages, and it… is… taking… forever.

The process was

grab the product url
make a markdown link
choose 2 or 3 items to highlight
download images of the image on those products
make a markdown link to each of those product pages
embed the image in the page with a markdown link to the product page around it.
come up with some witty title and ridiculous copy for the page

I punted on the last one. The process doesn’t sound like much when you say it, but in practice it was hugely time consuming, mentally draining, boring, and soul sucking.

Know Thyself

I knew that if I forced my way through, I could finish the 13 or so products I had. I also knew that I’d never add anything else to the site if I did. I’d definitely not make another site if some other entertaining idea came along.

So, I wrote some code. We’re talking ugly, get it done, do the first thing that’ll work kind a code.

Along the way I discover that for some reason Firefox doesn’t bother to store session cookies in its SQLite cookie database, and it turns out I need session cookies. So, right click, inspect the network call to their GraphQL API (totally undocumented) and “Copy as curl”.

Then write a bash script to read in the clipboard, extract the cookies and throw them into some ancient Netscape Navigator format that curl apparently knows how to handle. This file doesn’t need to be regenerated for …. days? I dunno.

Then copy the url for the product promotion page (the one with links to downloadable images) and run that through another script that extracts the product id, gives it to curl, which utilizes the new cookie file, and hits their GraphQL endpoint to extract the JSON (same stuff as on the web page). It’s more JSON than I need but refining the query would have been wasted time.

Run that JSON through a third script (this one in Raku) that presents me with a list like this. Now I just need to scan the RedBubble promo page to find images I want to use, and type in their numbers.

...
[33] Shower Curtain
[34] Spiral Notebook
[35] Sticker
[36] Tall Mug
[37] Tapestry
[38] Throw Blanket
[39] Throw Pillow
[40] Transparent Sticker
[41] Travel Coffee Mug
[42] Wood Mounted Print
[43] Zipper Pouch
[44] iPad Skin
[45] iPad Snap Case
[46] iPhone Skin
[47] iPhone Snap Case
[48] iPhone Soft Case
[49] iPhone Tough Case
[50] iPhone Wallet
Choose some items (comma separated):

The script considers my choices, downloads the default product image, runs it through imagemagic for resizing, takes my original artwork, resizes that, asks me for the name of the product and ….. voilà I’ve got a markdown file with all the soul-sucking grunt work done for me.

And yes, I have a way to add new products without overwriting the page.

That Sweet Marketing Copy

I never lost sight of the fact that this was, ultimately, a joke. I expect to, over time, make tens of dollars from this. If we consider my hourly rate it’s very unlikely this thing will ever pay for the labor that went into it.

So, because I’m not going to get rich on this, and I’m probably going to get a Cease and Desist letter from a Megacorp who likely lacks a sense of humor and thus shan’t be named. I’m not worried about “real” copy.

However. We’re a day and a half of work into this thing and frankly my ability to write entertaining micro-fiction about each of these is… shall we say, “diminished”.

But along the way I’ve been keeping my friend’s discord ( the one responsible for this stupidity ) in the loop. There someone points to an article about using AI for marketing copy, and I remember that I’d seen a bunch of hype about OpenAI on Mastodon lately. I don’t really want great “marketing copy”. I want creative stories, that happen to also be marketing copy.

So, I make an account there, and see what comes out. I started by creating some copy for this image, which I imagined having come from some old children’s book.

Elouise offers flowers to a tentacle montster

Folks… Text AIs are good.

OpenAI text output screenshot

In the end I edited the Elouise Makes A Friend text down to this:

This image from Elouise Makes a Friend is a timeless reminder of friendship and kindness. It shows Elouise bravely offering a flower to the Tentacle Monster, who in turn offers a kind smile. Whether you choose a the sleeveless top, the throw pillow, or a coffee mug, this image will comfort you and remind you of the power of friendship.

Bring this touching moment from Elouise Makes a Friend into your home. Our products featuring this image are perfect for gifting to that special someone, or for yourself.

Everything required heavy editing, but that didn’t matter. It’s radically easier to edit two to three paragraphs of copy than to come up with some ridiculous story that you then have to edit anyway.

Over time, I got better and guiding the AI, and increasingly impressed with what it would come up with. For example, I let it create almost everything on the About page.

Final Thoughts

Knowing then what I know now, would I do it again? 100% It was fun. I’m ridiculously proud of it, and I genuinely want many of the products.

Would I recommend it to others?

Yes, but with caveats. You really need tooling to get from “I threw something on RedBubble” to “I have a site for my products”. Otherwise your brain will melt. I guess you could outsource that work, but the profit margin is so small here that that’d just put you farther in the hole.

There are some existing tools on GitHub but a quick glance suggested they might be abandoned, and frankly it was faster to write ~100 lines of Raku than figure out and tweak someone else’s stuff.

Also, I really need to find a prettier template. I’d hire someone to make one but there’s no way this thing is going to cover the cost of my time to make it, and I’m not currently employed (hire me!) so that’s not going to happen.

Will I add to the site? Almost guaranteed. You can Follow Bed Bath & The Beyond on Mastodon to see the latest items as I add them.

Maybe? It’s kinda crap, and could use a lot of refinement, and frankly not many folks have realized the joys of Raku yet so it’s probably not in a language you want to poke anyways.

What’s my favorite?

Lovecraft & The Octopus. Something about this just tickles my funny-bone. Also it looks unreasonably good on everything I put it on. I can not explain it. Like, how can you not want this ridiculous clock?

a clock with an image of lovecraft and a giant octopus thing behind him

So Many Images

Working With AI Image generators is like herding cats. This is, honestly, a surprisingly small number of images to get 13 usable products. See A Journey With Midjourney if you’re curious about the process.

Some of these are good, but I haven’t gotten around to incorporating in the site yet. A handful of these are pixelated, because I’ve got another blog post idea involving them… maybe more t-shirts. ;)

Holler if there’s anything there that isn’t on the site, that you’d actually buy. I’ll add a page for it. I’m @masukomi@connectified.com

midjourney image stream screenshot

Twitter Employees Should Take the Severance

Wed, 16 Nov 2022 11:21:55 -0500

Musk has given the remaining employees an ultimatum: come back to the office, sign up for 'hardcore' work, or take 3 months severance and get out.

Acknowledging that there are some people who can't really say "no" because of visa issues, or other complicated home situations….

Aside from them, who would say "Yes! Sign me up for 'hardcore' working hours…

for a boss who regularly fires people who politely correct his lies about your work,
in a place where morale is going to be "in the shitter" for a very long time
in a place where incredibly important sections of the staff have been fired
in a place where you can't trust the boss's claims from day to day
where 40hrs probably won't be enough. It's not 'hardcore'
where all protections have been removed for communities who need them
where the boss fired the Ethical AI team
where the boss is anti-trans, and racist
where there's no hope of a stock pay-out
where daring to take time for mental health, or sickness, or caring for a loved one, will most likely be seen as "not being a team player"
where you have to come into the office even though the boss doesn't
where the boss is actively running the company into the ground faster than anyone believed possible
where the boss has already explicitly said they might just go bankrupt
where the boss has scared off all of next year's pre-booked advertisers (~15% of income)
where the boss has explicitly said it might go bankrupt.
where the interest on debt was unaffordable before the acquisition and now is radically worse
where the company is likely to have millions of dollars in fines for violating EU regulations

Twitter Employees: You're smarter than that. TAKE THE MONEY AND RUN.

A Rebuttal to Scaling Mastodon is Impossible

Mon, 14 Nov 2022 10:28:47 -0500

Armin Ronacher wrote that Scaling Mastodon is Impossible

I'd like to offer a rebuttal. As someone who's been doing professional web development since 1995, with most of that time being spent in Rails jobs, or doing Rails work on the sidelines, I think i have a pretty good perspective on the situation. For those who don't know, Mastodon is written in Ruby on Rails.

Decentralization promotes an utopian view of the world that I belief fails to address actual real problems in practice.

Email. E. Fucking. Mail.

Email serves a very real problem. It has been decentralized (federated) since the start, and most people would agree that the following are all important features of email, even if they don't personally take advantage of them

being able to have an email address at your domain / your company's domain.
being able to have email that isn't being mined by a company to show you advertisements
being able to add as many accounts as you want without having to pay more or register more
being able to create aliases for your email address
being able to create "catch-all" email addresses. E.g. <anything>@example.com
not having to pay arbitrary additional fees for storage, or anything else, because some company decided to make more money off of you.

Decentralization makes all of these possible.

Yet on that decentralization wave a lot of projects are riding from crypto-currencies [1], defi or things such as Mastodon. All of these things have one thing in common: distrust. Some movements come from the distrust of governments or taxation, others come from the distrust of central services.

I think that's a significant misunderstanding of why Mastodon exists. Mastodon's early days were supported by the work, and participation of lots of marginalized people (mostly queer folk of various flavors). You wouldn't be wrong to say that it was created because of "distrust", but if so you'd be arguing that it was a distrust of the centralized platforms ability, or their unwillingness to protect marginalized communities, which is completely true.

Mastodon servers are a collection of communities, we do what no centralized system can do. We protect ourselves. There are simple too many bad actors in the world for any centralized server to moderate them effectively. On top of that you have the differences in "acceptable" between different social groups. No single corporate / non-profit / human entity can possibly hope to fairly enforce all acceptable social practices across all social groups.

Even if they could, it's a brutal job that decimates the mental health of the folks that have to do it every day. I've never heard of a case where Twitter, or Facebook has actually worked to protect them or compensate for the horrible things they're forced to see.

In my mind the discussion about centralization and decentralization completely misses the point of the intended outcomes. Centralization or decentralization should really be an implementation detail of the solution to an actual problem.

Agreed. There's way too much "it's federated" talk when convincing people to join Mastodon. The "federation" part is not only something your average person doesn't understand, but also something they don't care about. Average users don't care that email is federated. I've been using it for decades and I've never seen an email host promote the fact that it's "federated" as a reason to use it.

What are we trying to solve?

Let's ignore Twitter for a second and let's talk about software engineering. Specifically dependency management. I think dependency management is an interesting proxy for the problem here and there are some lessons to be learned from it.

Wait. What?!

I've thought long and hard about dependency but uh… I'm not seeing this connection.

The first concrete point they seem to make is this:

…as time went on, a lot of these packages [people depended on] went away because the hosts they were hosted on shut down. So the first cracks that showed up just was an effect of things ageing. People walk away of projects, in some cases die and with that, their server bills go unpaid and domains eventually lapse. Some companies also go out of business. SourceForge did not really ever die, but they had financial challenges and made their hosting page ever more hostile for the installers to give access to the uploaded tarballs.

Sounds like a strong argument against centralization, and a good argument for taking personal control of the things that you rely on, and are important to you. Or, to put it another way, don't rely on others when it's something you care about. A centralized system is not something you control, so if this is important to you, you can't rely on centralized systems.

The second thing that became apparent over time was also that decentralized services came with a lot of security risks. Every one of those hosts allowed the re-publishing of already existing packages. Domains that lapsed could be re-registered by other people and new packages could be placed there.

Have you heard of a centralized system that hasn't had a security issue? Have you heard of a centralized system where someone's account wasn't stolen? Either hacked, or given away by the company because they believed someone else deserved it more or had a better claim to it.

Most of the major centralized platforms have had issues with certificates expiring, or forgetting to renew some domain. So… I'm not sure how this is relevant to the discussion. Everyone is provably bad at this. When a centralized system screws it up it affects millions. If I screw it up on my Mastodon server 8 users are affected.

Obviously there are nuances here and it's clear that central services come with risks, but so do decentralized services and they don't have clear upsides.

Clear upsides:

you control your destiny
you account doesn't exist at the whims of an algorithm
you can protect your friends
you don't have to do anything if some company goes out of business
if your dependencies suddenly come with requirements / expectations that you don't agree with you can change them.
- In the case of Twitter (for example) you don't have to worry about terms of service that are 10 meters long, read by no-one, bind you to things you don't agree to, and change regularly.
- In the case of open source libraries changing their license, you can either not upgrade, or switch to a different package, or fork it and maintain the old license.

On decentralized systems in particular I encourage you to read Moxie's take on web3 which outlines the challenges of this much better than I ever could. In particular it makes two very important points, namely that people don't like self hosting (at scale) and that it's easier to move platforms than (decentralized) protocols.

Yes, people don't like self hosting. Yes, it's easier to move platforms than to invent and implement a new protocol. Neither of these are relevant. They're straw-man arguments.

The vast, vast majority of people participating in the Fediverse aren't self-hosting.
No-one needs to invent and implement a protocol. It's already been done.

There is also a proxy war going on about freedom of speech and expression and the desire to create safe spaces.

Sure. That's happening everywhere. However, the centralized platforms fail at both. They can't have true free speech because it is fucking dangerous, and their advertisers don't want to spend there money in a place that is supporting Nazis. They have utterly failed at creating safe spaces for anyone

So really before we talk about centralization and decentralization, I think we actually need to understand what we want to accomplish. And really I think this is where we likely already disagree tremendously. Mastodon encourages not just decentralization, but federation. You can pick your own mastodon server but you can also communicate with people on other instances. I will make the point that this is the root of the issue here.

I failed to see what exactly he was ultimately saying was the root problem but…

I have been using this for a few weeks now in different ways and it's pretty clear that this thing is incredibly brittle. The ActivityPub is a pretty messy protocol, and it also appears to not have been written with scalability in mind much. The thing does not scale to the number of users it currently has and there is probably no trivial way to fix it up.

The protocol is, provably, scaling just fine. The thing that's failing to scale is the Mastodon server implementation. It's written in Rails which has a horizontal scaling strategy (throw more servers at it) and depends on Sidekiq for background processing of messages which is… let's just say folks have differing opinions of its ability to scale, but regardless of what you think about that, there are other options for managing message queues that have existed for decades, and are provably more efficient and scale amazingly well. Scaling servers horizontally is something that requires significant sysadmin know-how.

On top of this is the fact that literally every social networking server for the Fediverse (Mastodon, Pleroma, etc) are all designed for "communities". A server of tens, or hundreds of thousands of users is not a community. This greatly exceeds Dunbar's Number of roughly 150 individuals. It's literally too large of a group for humans to maintain stable social relationships with.

So, even if we set aside the technical issues, it's not good at that scale because it's not supposed to be good at that scale. When you start getting thousands of people who are following tens or hundreds of thousands of other people you loose the ability to moderate effectively. You can't protect your community because there are too many messages coming in from too many sources. You end up needing moderation teams, and the bigger you get the more impossible the task becomes. Except it's worse, because Fediverse instances are managed by volunteers not corporations. No-one's being paid to validate reports of abuse, mediate disputes, or look at cruel racist bile.

Communities don't scale. It's a human problem not a technology problem. This doesn't mean that decentralization isn't a good solution to the technological problems, and this doesn't mean that decentralization as a technical solution doesn't scale. Email disproves this trivially. It works great, even under the ridiculous onslaught of billions of automated spam emails every day, decentralization works.

… there is the belief that you can somehow create a coherent experience into a “whatever”. Whatever it is actually. My first mastodon instance was de-federated by accident from my current instance.

That sucks, but it's not like centralized solutions don't regularly delete or suspect accounts by accident, so I'm not sure how it's relevant to the discussion. If anything it's another argument for community based administration because these mistakes happen far less often at the individual instance scale than it does at Google / Twitter / Facebook scale. Plus, there's no "an algorithm decided I was bad and suspended my account". It's literally not a thing. Sure, it could be but it isn't now, and you would never have to join a server that implements that crap to participate in the Fediverse.

I moved to that instance though because many other hackers in the Open Source space did, and unlike Fosstodon it seems to allow non English content which I do care about quite a bit. (After all my life and household is multilingual and I don't live in an English speaking country.) Yet that instance still defederates qoto and I'm guessing because qoto permits unpopular opinions and does not block servers itself.

So first you found a community that wasn't a good fit. Then you found one that was. Congratulations. Now you're asserting that your old one is blocked (not actually defederated) by your current one because of unpopular opinions. This means your community is successfully enforcing its values and protecting its members. Congratulations. The ability to protect your community is a feature, not a bug. I should not be forced to see crap from people I disagree with because some company doesn't have the cajones to block them because of some BS argument about "free speech", or because they don't have the human resources to investigate the BS.

Federation makes all of these questions play out chaotically and there is no consistency. My first experience of being on Mastodon was in fact that I got shitposted at by accounts on poa.st. The n-word was thrown at me within hours of signed up. Why? I'm not sure. So moderation is something of an issue.

So, your experience was exactly the same as the experience many people have on Twitter. However, instead of recognizing that moderation is always reactive (you moderate after someone causes problems not before) and that you had a real person you could reach out to you complain about it in a post about how Mastodon doesn't scale? Many, many thousands of people have reported racist behavior on Twitter and had zero response from moderation. Frequently the people being attacked are the ones who get their accounts suspended because of false reports. This doesn't happen on Mastodon. The admin is a real person who cares about their community and just blocks the offenders, or if there are too many of them, blocks their entire servers.

The abuse you suffered will always exist because anonymity, and pseudo-anonymity beget abusive behavior. It's a human problem. In a decentralized system like Mastodon there's a real person who's volunteered to help protect the people in their community from stuff like that. In centralized systems, you're typically screwed.

We clearly won't come to an agreement across all of mastodon about what acceptable behavior is, and there is no central entity controlling it. It will always be a messy process. I guess this is something that Mastodon will have to learn living with, even though I can't imagine what that means.

Sure, but it's not something "Mastodon" will have to learn to live with. It's something humans will have to learn to live with, if they want to participate in online communities. It's no different in a centralized vs decentralized system either. The only thing that changes is how much power a community has to protect itself.

Unlike Twitter which was a public company with a certain level of responsibility and accountability, Mastodon is messy legally speaking as well. It's not above the law, even if it maybe wants to be, and instances will have to follow the laws of the countries they are embedded in. We already know how messy this is even for centralized services. But at least those enterprises were large enough to pay lawyers and figures this out in courts.

So. In a centralized system when their shirk their responsibility they can bury you with a horde of expensive and talented lawyers who will make you go broke or go away. In a distributed system there are individual humans responsible for the servers who can be held accountable and generally don't have the resources to bury you in legal fees. So, again, a strong argument for decentralized solutions. Also, a strong argument for communities that can actually police themselves as opposed to crossing your fingers and hoping BigCo will do it.

For large mastodon instances this might turn into a problem, and for small instances the legal risk of hosting the wrong thing might be completely overwhelming. I used to host a pastebin for a few years. It was Open Source and with that others also hosted it. I had to shut it down after it became (by a small percentage of users) used to host illegal content. In some cases links to very, very illegal content. Even today I still receive emails from users who beg me to take down pastes of that software from other domains, because people use it to host doxxed content. I really hard a hard few weeks when I first discovered what my software ended up being used for.

This is again, an argument against centralized systems. It's also an argument against large Fediverse instances too. The problem is (pseudo)anonymity, not decentralization or centralization. Companies like Twitter & Facebook & Google can't keep up with the volume of illegal content they host. A small community can. Also, don't allow anonymous people to use your resources if you're not willing to let them do bad things with it. Mastodon servers don't have to be wide open to the public. If you do open yours to the public you can put very strict rules on participation and you can easily limit the number of incoming people. You can require approval, or you can simply turn off self-signup when the number of folks goes beyond your ability to manage.

If you look at a mastodon server as a community (as designed) then you can easily keep an eye on the new folks, and their behavior, and kill their accounts if they violate your community's rules.

… then there is also the issue of what happens if someone popular joins the instance.

That's a symptom. Not a problem. Someone famous joining your instance unexpectedly is a symptom of you not managing your community or regulating sign-ups. If you want to have an open server that's fine, but you need to recognize that if you choose that (it's an active choice not a passive one) then you are opening yourself up to that option.

You can, of course, balance this by saying "hey, my server is open, but if you have millions of followers I will ask you to pay for some of the server costs, or I will boot you" Folks with millions of follows can, generally, afford the cheap monthly fee to get their own damn server anyway.

Imagine you're a rather small server and suddenly Eli Lilly and Company joins your instance. Today they have around 140K followers on Twitter and they are a publicly traded company. First of all with an account that large, every one of their posts will cause a lot of load on your infrastructure. Secondly though, they are a very interesting target to attack.

In order to do this i have to

Imagine I decided to allow corporate accounts on my server. Why, the fuck, would i do that?!
Imagine corporate accounts with over a hundred thousand followers would want to join a random server instead of just setting up their own (trivially easy to do, doesn't require IT skills).
Imagine I wouldn't ask them to foot the bill for the additional resources they were using

So yes, if I imagine a series of highly improbably decisions 2/3's of which would be me choosing to invite or accept harm, I could find myself in a "bad" situation.

But you don't even need to be that popular to be worried about what your instance is like. People put a lot of trust into Twitter accounts over the years. I had plenty of exchanges over private DMs with people which I really would not want to be public. Yet how do I know that my instance operator does not really like to secretly read my communication?

You know this can, and does, happen on the centralized systems too, right?

C.O.M.M.U.N.I.T.Y I don't know how many times I'm going to have to say this. A mastodon instance is a community. If you don't trust that community don't join it. Do i trust the thousands of Twitter employees to not to ever read DMs? No. Fuck no. Do I trust a community of people organized around principles I agree with? Probably.

Also, this is a fucking straw man argument. Don't say things in DMs that are sensitive and secret. At least Mastodon has the decency to warn you every time that your DMs aren't encrypted. Seriously though, why, the fuck, would an admin want to spend their time trolling around in the DMs? Maybe if you're on a server filled with trolls who get their jollies off of being mean to other people. If, on the other hand, you're a trans woman who's joined a server that's all about protecting and supporting trans people… odds are that they're not going to look at your private stuff.

On top of this. Mastodon has no interface to do this. You have to directly muck about with the database. A massive portion of Mastodon instances are hosted on servers run by masto.host, and you know that they don't offer? Direct database access. I couldn't read my members DMs if I wanted to. I guess I could ask for a copy of my backup and then point a database tool at whatever he sent me but… This is a bullshit argument.

Do I know if my instance operator could even keep the communication private in the light of hackers?

Again with the straw-man arguments. Twitter can't. Facebook can't. Google can't. The whole point of a hacker is to steal secret information, and there's no such thing as an unhackable system. So no, a Mastodon admin can't but neither can anyone else.

I'm sure over the years thousands of credit card numbers, token access credentials or passwords were exchanged in Twitter DMs. Imagine what a juicy target that would be on Mastodon servers.

This is, yet another, argument for decentralized servers. Hacking Twitter gets you millions of accounts. Hacking my Mastodon server gets you 8. Exchanging illegal information in DMs has nothing to do with if your server's been hacked or not.

Mastodon is getting some traction today, but Mastodon is around for a long time. And with that, may of the problems it had over the years are still unresolved.

Like Facebook, and Twitter, and Google, and everyone else.

He provides a bunch of examples that I've already addressed but…

Or that the most controversial and replied to issue is about optionally disabling replies to posts like on Twitter.

Twitter has refused to give abuse moderation tools to people without the verification for years. They also regularly refuse to give people who are targets of abuse verification. I'm intentionally ignoring the $8 verification WTF that is currently going on. So again, straw-man argument.

Don't use Mastodon if you don't like Mastodon's features. There are other Fediverse servers out there with different moderation options. If you don't like what features a Centralized system offers you you're screwed. If you don't like what features your Fediverse server offers, you can choose another one and still participate.

Or that there are popular forks of Mastodon with different goals than Mastodon who can't get their changes merged back.

Why do you think they should?! That implies that Mastodon developers should have to accept whatever random features some other group of people thinks are good? Should Twitter and Facebook do whatever random suggestions other people like? There are millions of folks in the US who believe we should remove the separation of Church and State. Should we do that?

No-one should be forced to make their software have whatever features other people want. This is especially true when the forks / competitors with the features you want exist and can be used. Jesus fuck-me. For example, Hometown is a great fork that has a wonderful feature of letting people message only other people on their server. Mastodon isn't interested in that feature. That's fine. If that feature is important to you join or start a Hometown server.

This is one of the most important reasons why decentralized is better. You can still participate even if you don't agree with the way one piece of software on the network works. You can choose the features you want. If you want to be on a server with better moderation features. You can. There's literally nothing stopping you. You want to be on a server with better human moderators? You can.

To be honest, code is simple in comparison, but actually making Mastodon scale technically too will require changes if it wants to absorb some of the larger users on Twitter.

Sure. Step one. Use Pleroma. It handles vastly more connections for any given quantity of server resources. It's built on the Erlang Virtual Machine which was developed to handle digital switching of phone calls. However… the better solution is don't make huge instances. You can't have a huge community. You can't protect a huge community. You can't please a huge community.

The problem isn't a technological one. It's the human decisions that are the problem. You talk about back-pressure, but if your system is being overloaded because Bob decided to make a bot that follows ten million accounts, or Mary has ten million followers then boot them or ask them to pay. This isn't hard, and there are already solutions available that'll let Mary have a relatively cheap instance that can handle her ten million followers.

In my mind a better alternative to these two extremes of Twitter and Mastodon would be to find a middle ground. A service like Twitter is much cheaper and easier to run if it does not have to deal with federation on a technical level. An Open Source implementation of Twitter that is significantly cheaper to run than a Mastodon host that can scale to larger user numbers should be possible.

An open source version of twitter that scales either has to be federated OR you're building a twitter competitor, and trying to encourage millions of people to join your new network. The latter is arguably brain damaged. The former already exists. Mastodon is an open source twitter clone. Pleroma is an open source Twitter clone that scales really effing well.

Ideally at least some of these communities would try to be run like non profit foundations, then maybe they have a chance of hanging around.

You mean, the way many mastodon instances are already run?

A “Not Twitter Foundation” that runs an installation of an Open Source implementation of a scalable micro blogging platform is very appealing to me

It makes no sense to simultaneously bitch about Mastodon not accepting features some community members want them to have and say you want some centralized platform that's guaranteed to not accept features some community members want. You're also complaining about not having the features you want.

These aren't compatible ideas. Either you want access to the features you want (distributed system which offers choice) OR you want to let someone else decide what's acceptable and "good" for you.

You either want to be part of a community that can protect itself, or you want to cross your fingers and hope that some central organization will accomplish a task that's literally impossible due to issues of scale.

And then let the market figure out if that foundation does a good job at running it, and if not someone else will replace it.

Do not fucking bring capitalism into this discussion. That's what got us in this mess in the first place.

The Fediverse scales just fine. It's not supposed to be a collection of massive servers. It's supposed to be a collection of communities. The tool isn't broken if its user misuses, or misunderstands it.

Here's a practical example. Check out Bonfire. It's a Fediverse server option and literally all of their features are about answering the question of "What does this community want"?/ I can't comment if the software is any good, but it's a great example of how Fediverse servers are all about supporting the needs of "a community" not the whole fucking internet.

A Journey With Midjourney

Thu, 03 Nov 2022 00:00:00 +0000

Exploring an Idea With Midjourney

I haven’t seen anyone talk about what it’s like to try and work with Midjourney, or any of the other Image AIs. No-one has shown just how much work it takes to get from an idea, to the beautiful output we keep seeing.

This post will take you through the journey, from a spark of colorful and strong Native American imagery, depressed cyborgs, to visions of Muslim women, in a dry and trying future.

I’ll explain my thoughts along the way, and how I crossed notable thresholds in the process.

Legal

Just in case anyone gets any ideas: The images in the document are all distributed under the Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 license, with the exception of the first one which is copyright it’s author (moon.goat.616) and is used under Fair Use.

The Spark

Yesterday I saw a truly impressive image of a Native American person in the Community Feed.

This was created by user moon.goat.616. That link will only work if you’re a Midjourney subscriber.

Midjourney doesn’t let you directly recreate other people’s images, but it will let you see what prompt the entered into the system to generate it. Most of the time, copy-pasting their prompt will generate absolute garbage. This is because the pretty-pretty they generated was typically the result of many iterations and tweaks.

This doesn’t mean the prompt is useless. They’re incredibly useful, because you’ll discover new keywords that help guide the AI in a direction you want.

Every now and then, the prompt just works…

That was, really surprising. I was tempted to start working with that, but as a privileged white person I don’t feel particularly comfortable making representations of Native American women. There are so many things I can’t speak to with knowledge or authority.

But the colors were so amazing. “What about a depressed android in those colors?” I thought.

So, extracted all the keywords, removed the stuff that pointed it towards Native American imagery (“tribal outcast”) and replaced it with “depressed android. sitting. slumped. against wall.”

Depressed looking? ✅

Android? kindof.

I was looking for less… human looking things.

Maybe if I try “rubot” instead of “android”

Shit… that’s not how you spell “robot”.

Interesting but… really hard to parse what’s going on.

Back to “cyborg”, but I added “salvage” and “junk”. After a couple iterations I got this

Now we’re talking!

Depressed looking? ✅

Cyborg? ✅

A bit… too human looking. I was really hoping to generate images with boxy looking robots but I’m loving the color work, and there’s something about these women. I decide to see where I can take this.

It took about four simple iterations to get to that. There are a handful of other good images from that work too.

Grand total, I’ve spent about 20 minutes. It’s at this point I finally break free from this fascinating thing and go back to my actual task. I had only opened midjourney to find an example of something to show someone on discord.

…

That night, drained from fighting with buggy libraries and systems I decide to relax by playing around with Midjourney again.

I start again with 2 tasks in mind.

I want those vibrant colors I started with. This stuff is great, but it’s muted in comparison.
I want actual mechanical looking robots, not women with various doo-dads attached to them.

I start with the first task. Adding vibrancy.

I add “Intense color” to the prompt (it already had “vibrant colors”). And feed it one of the good close-ups to start with.

I go through four more iterations, selecting for color and face, and then I make a mistake.

I decide to feed it one of the past images as input, but I choose a 4-up image instead of a single image.

Cool! Not what I want, but man, look at those left two! That’s awesome.

I backtrack, and instead feed this into it as a guide.

And now I’ve got my vibrant colors

Alas, if you look closely you’ll note that I’ve lost all the detail. There are two other problems.

they don’t look like androids at all
my brain is raising warning flags about the future of those boobs.

A few iterations later and the boobs are definitely a problem. I really like this image though.

I should probably point out that Midjourney’s people have worked really hard to keep porn out of the system. You will almost never see a nipple in Midjourney art. I believe they trained something to find and get rid of nipples in the training material before before training on it.

I’m pretty sure she’d have nipples if not for that.

A few tweaks later on and I managed to get a version without the boob-windows in the outfit but rest of it just wasn’t as good.

You’ll also notice that the backgrounds have started to change. They looked like they were hinting at walls, and corners, so added in “distant cityscape” and that really helped. Keep an eye on the backgrounds as we progress.

There were a lot of boobs along the way so I also decide to explore what happens if i lean in to what it’s obviously trying to do. My thinking is if i try and guide it, instead of fighting it, we might get some interesting results.

We’re obviously far from our starting point of “robot” but I’m enjoying what’s coming out of it. So, “couture outfit” gets added to the mix. I’m thinking lots of “couture” fashion has dramatic boob things, but actually manage to cover the boobs.

A handful of iterations on that and I realize that I got what I asked for and I really don’t want it.

So, I backtrack, and keep feeding chosen pieces of output back into the system. I add in “4k. hdr.” to see if we can bring out a bit more realism.

This is… amazing.

I love, how the city is emerging from the background, and how the blue and orange are contrasting her against the sky.

Her hood gives me an idea though. Its got enough fabric that it could be a hijab that’s been let down. What if I add “Muslim” to the mix? Might that counter the boob factor too?

No. No it will not.

This plus future iterations I’m not going to show lead me to believe that in the future muslim women will decide to keep the hijab, but rebel against the male oppression by showing their boobs at every available opportunity.

Really though, it just means that the only thing Midjourney knows about muslim women is that they have covered heads.

BUT… the city!

Also, note that the color palate has changed. I can only assume that this is because a lot of the training material involving Muslims is from parts of the world that have a lot more desert.

I eventually get one with a great head, but the boobs have become ridiculous. Like… runway supermodel combined with eccentric designer stuff that… just… just no.

So, I edited an image, cropped it to just the head, and fed that in as source material plus the prompts.

My friends… the algorithm wants boobs.

But… I’m iterating. I’m combining. I’m tweaking… I’ve replaced “depressed” with “optomistic” and it hasn’t helped much. It isn’t until a while later that I realize that it’s spelled “optimistic” and thus the bad spelling was just being ignored. Also, it’s just not a great keyword. I didn’t want to go all the way to “smiling” or “happy”. I liked the vibe of these.

I add --no chest (“boob” is a restricted word) and try “metal chest plate”. The latter does nothing useful. The former helped get rid of some of the more egregious boob images.

we veer a little into the Anime too

From here on it’s just a matter of taking generated images and feeding them back into the system with the same keywords, to “restart” the process and focus it on specific aspects. I could have started mucking with the keywords to change things but I liked the direction it was going in.

I try to direct it more towards dark skin by using “tanned”. I try and avoid “dark skin” because it’ll quickly trend towards African look instead of middle-eastern.

There are a few other, nice images from this, but this journey has taken four and a half hours of work, and the generation of at least a hundred images. I need some sleep.

Things of note

Photorealism

It should be noted that with the exception of the first two images none of these are even remotely photo-realistic.

This is pretty normal in my experience. Getting something that looks “real” seems to be largely a question of how much content already exists in the world that involves that stuff, and looks real when it goes into the training system.

Note that we went from painterly, but very close to photo, to something almost impressionist in one step, and never really came back.

I’m confident that it’s possible to push this series towards photorealism, but that wasn’t my goal. It’d also take a lot of work.

Hands

The hands are… problematic. The hands are problematic in all the image AIs. If you see normal looking hands in an AI generated image it either means the person edited the image, or they were exceptionally lucky.

There were a lot of images along the way with floppy spaghetti arms, detached hands, and forty-gajillion fingers.

Creativity

I’ve heard a lot of comments that implied that creating images with AI was just a matter of creative problem solving around choosing words to use in prompts. Anyone who has used these systems knows that isn’t true. The creation of these images wasn’t a matter of me constantly tweaking and perfecting a set of words. The words at the start and the words at the end barely changed. I didn’t leave out any notable changes in the prompt, and the changes I did make were very minor.

Working with an AI is a more a matter of trying things until you find a style you like, and then encouraging it to go in a direction. It’s like working with a river. You can’t really control it, but you can encourage it to help you achieve a goal.

Sculpting marble is literally “just” a matter of choosing what pieces to cut off of the block. It’s “just” a piece of “creative problem solving”. You don’t need to be creative. You don’t need to be an artist. You just need to choose what pieces to remove.

If you believe that, then well… I hope you at least enjoyed the pictures.

Welcome to a new, and amazing, tool for artists.

Private Comments & Your Security

Sun, 23 Oct 2022 00:01:00 -0400

Summary

While leaving “private comments” on a repo can be incredibly useful, it can get you into trouble if the wrong person sees them and disagrees with what they see. This post goes into the problems, consequences, and things that tools that provide this functionality need to do to protect their users from accidental harm.

Some Context

A while ago I wrote a tool called “Private Comments”, which allows you to leave “private comments” on a codebase that aren’t actually in the codebase. Imagine leaving little “breadcrumbs” for the future you that are actually attached to the relevant lines of code, and go away when that code changes, but reappear if you need to look at the relevant past version of it. It can be used for you, or shared with your team.

That’s Private Comments. It’s a teeny little server that runs on your computer, takes up almost no memory (~7Mb) and essentially no CPU (~0.0% at idle), and a plugin in your favorite editor¹ talks to it and records or shows comments when appropriate.

Sensitive Content

There are two types of sensitive data in Private Comments.

The content you write.
1. This could be sensitive in the sense that it contains comments that, if exposed publicly, would violate your NDA. For example, leaving a comment which summarized how a sensitive process works.
2. This could also be sensitive in the sense that when you give someone a blank notebook labeled “Private” and tell them they can write anything in it without others seeing, it’s just a matter of time before they write something that others would take offense to.
Metadata about the repo and its files the name of the repo, and the path to the file you’re commenting on could be incredibly valuable to hackers. As such, Private Comments goes out of its way to never store this information. So, we can mostly ignore this problem.

Consequences

Focusing in on the content you write:

1.a. is pretty easy to address. Just don’t store your comments anywhere that violates your company’s security policies. It doesn’t matter who sees it, because all the people who can see it have signed the same NDA as you.

1.b. is the problem, and it’s a problem in multiple ways. Let me lay out the ways I see comments being stored that could get a person in trouble if their coworkers saw it.

You leave notes about things others find obvious, self evident, or ridiculous to even consider leaving a comment about.
You leave “too many” comments.
You leave comments they disagree with.
You leave frustrated, disparaging, or unkind comments.

Depending on who finds these comments, their feelings about you, and their current state of mind, the results could range from simply lowering their opinion of your capabilities, to you getting fired. If you’re working on a client’s codebase it could be you and your team loosing the contract.

Keep in mind that developers generally have a low opinion of comments in code, and the comments stored in Private Comments are the things that you’ve decided shouldn’t even be a public comment.

On top of this, most devs don’t value the concept of Private Comments, and most folks in American society (and many others) are terrible about understanding and empathizing with neurodiversity, or people who see the world differently from them.

For example: I have ADHD. As a result, my memory is terrible. Like, ended up with a nail through my nose because of how bad it is. However, when someone finds out I’ve forgotten something important, I’m blamed. I “didn’t care enough”, or “must not have been paying attention”. There’s no consideration for the fact that my brain is physiologically different.

As a result of this poor memory, I leave myself a lot of notes. I then forget that I’ve left myself those notes. Thus Private Comments so that the notes I leave myself about code are in the code where I need to see them. Even though my comments tend to be purely factual, there’s essentially no positive outcome to anyone else finding my comments.

Protections

Because of these issues I see it as critically important that Private Comments are never stored in the repo that you’re commenting on. I don’t care if you use Private Comments or one of its competitors². I do care about you getting screwed over by a tool that accidentally reveals your private thoughts to others. I don’t care how innocent those thoughts are. They can still be perceived badly by others, and used to hurt you.

It’s important that Private Comments, or any tool like it that you consider using or creating must:

Never store comments in the same repository or folder structure.
- Your “private” branches can get accidentally pushed.
- Your “private” files can get accidentally added to commits.
Support encrypted comments

That’s it really.

PC takes the additional step of never revealing metadata about the files you’re commenting on, but it could be argued that that’s overkill.

The system must allow you full control of your comments, and make it impossible for those comments to accidentally become shared with the code, even if they’re not in the code.

Note: To date none of the Private Comments editor plugins support encryption. It wouldn’t be hard to add symmetric encryption in the plugins if that was important to you. The server doesn’t care what text you’re storing as a comment and has no idea if it’s encrypted or not.

Supported Editors: At the time of writing there are currently Private Comments plugins for Emacs, and Vim. The Emacs plugin is good. The Vim plugin works, but is more of a proof of concept, because VimScript is evil. Writing plugins for it is very straightforward because most of the functionality lives in the server. You just need to send HTTP request to store and retrieve them, and display the results. Check out The README and The API Docs. I’m very happy to help anyone attempting this. Contact info here, but I’m terrible about email. ↩︎
Alas, while I’ve found 4 competitors (so far) they only exist as Emacs plugins. ↩︎

Recording & Sharing Terminal Sessions

Tue, 11 Oct 2022 16:57:00 -0400

This post describes how to make high quality recordings of terminal sessions that can be replayed in the terminal, or shared on the web. I’m defining high quality as recordings with zero typos, and relatively controlled timing between commands.

to see an example of the type of output I’m talking about.

Why? Videos and gifs take up a lot of disk space, don’t age well as display technology improves, and are problematic for folks low vision requirements.

With the techniques below you can not only share examples of usage on your web pages, but within your tools themselves.

Goal(s)

record terminal session for demonstrating functionality
replay said recordings locally on a terminal
share said recordings online
have that recording look good

Bonus points:

editability
same file for terminal and web sharing
not having to do get everything perfect again when you need to record and updated version.

Tools

Its a live (itsalive)

same core idea as “doitlive” BUT with some additional functionality like being able to spit out a whole line, and drive interactive things like vim.

source code (GitLab)

What It Does

create a file of commands to be executed
have doitlive execute each of those commands as you type keys
always perfectly, and quickly typed
easy to control timing
allows you to pause and take control
- thus actually doing it live in the middle of your script
- can pause with the ##@pause comment which is useful immediately after a script that needs you to interact with it.
skip forward / back
allows you to spew out the rest of a line with CTRL+e
supports comments!
- both comments for the viewer (start with #) & comments for the presenter (start with ##)
allows you to have scripted newlines with no input
Presenter View!!! you can see how you’re progressing through your script, what came before, and what’s coming up next. All in a separate terminal.

problems

it’s actually executing the commands.
if you’re in the wrong dir, don’t have the commands the script needs installed, etc. it’ll blow up
doesn’t support comments, so you can’t inline commentary for recordings
not shareable because others would need the same things installed, sometimes in the same places, and what you’re doing may be specific to data on your system.
it doesn’t directly handle, or record, interactive stuff So, for example, you can have it execute a script, but if you have to navigate around the resulting output with arrow keys, it won’t record that. However, during playback it won’t interfere with you doing that. Until the interactive script exits you are actually doing it live, not just pretending.
during playback you’re literally just mashing keys. one keystroke per character output to the screen. So, if you’re recording the playback of your recording (see below) you’ll actually be recording gibberish. However, unless people are viewing the source code to your recording they won’t be able to tell.

Notes

It will start playback in the default shell. If you want to specify a particular shell to playback with set the shell environment variable to the executable for that shell. E.g. SHELL=/opt/homebrew/opt/bash/bin/bash itsalive recording.sh

I keep my bash shell nice and minimal for recordings, but my day-to-day stuff is in fish.

doitlive

What it does

create a file of commands to be executed
have doitlive execute each of those commands as you type keys
always perfectly, and quickly typed
easy to control timing

Problems

Same as itsalive’s problems.
because you’re just mashing keys things that you may have pasted in real life are typed in character by character. this makes you look like an amazing typist, but it does take longer, because unlike itsalive there’s no key combo to finish off the line in one stroke.
because of its lack of ability to pause & resume playback interactive things can be a little problematic.
because of its lack of presenter mode it is harder to time things well during recording.

Notes

I keep my bash shell nice and minimal for recordings, but my day-to-day stuff is in fish.

script (unix command)

old unix command BSD version (macOS) and Linux version are different. Linux needs scriptreplay. macOS version you can just point the same tool at a file and say -p to “play” it back.

What it does

records what you type and what came out
records the timings (or not)
the file could be run on the command line by others for downloadable examples.
- I believe the format is the same on BSD and Linux

Problems

no way to convert these files directly to SVG or GIF or asciinema files (AFAIK)
it’s nigh-impossible to get the timing right, and not show off bad / slow typing
editing of content or timing is not really possible
- technically you can do it with teseq which is … not a joy
  - Recording of How to edit here (9 min)
  - script -> file -> teseq -> new file -> editor -> reseq
  - editing with teseq is doable, but the file format is not very easy to work with.
  - one thing it can do that’s useful is edit timings

Asciinema

You can self-host (just needs the .js and .css files), or upload your recordings to Asciinema.org. Who knows how long Asciinema.org will continue to exist though.

What it does

records what you type and what came out
records the timings
stores a format that can be shared via a web page
stores in a format that can be replayed in a terminal

Problems

editing is not possible.
- content or timing

Power-up Combo

how to make sweet looking recordings without typos or weird pauses.

figure out exactly what commands you want to execute
create a file itsalive (or doitlive) with those commands My recommendation is to use itsalive though because of the ability to record comments to yourself and the viewer.

Note that it’s not going to be recording timings, or edits or anything like that. It just records the commands you enter, and the file is only those commands, so it’s really simple.
add asciinema rec <filename> to the start of it so that it starts asciinema recording
add a ##@pause comment in your script and then type ^d to exit asciinema without seeing the word exit typed out.
launch itsalive myfile.sh or SHELL=/path/to/shell itsalive myfile.sh
launch the presenter view in a separate terminal itsalive presenter_view
click back into your original terminal but keep presenter view visible.
Watch the presenter view not the real terminal. As you mash keys it’ll show you your progress against the characters in the line. This makes it trivial to hit CTRL+e at the right point to make it look like you pasted, or to quickly finish off long lines for any other reason.
mash keys / hit return at appropriate times to move through the steps of the script
Party.

Now you’ve got a shell script for itsalive and an asciinema file to do with as you want. You probably don’t need the doitlive anymore, as it’ll likely produce different results when run months, or years, in the future, but maybe it’ll be useful to use as a starting point when you need to make a new recording for an updated version of the tool.

Real World Example

Here are the things I used to make some documentation for my git link-to-commit script.

What follows is the bash file that I ran with itsalive. Things of note:

Lines starting with ## are notes to myself because I’m watching the presenter_view as I run it.
The # lines are comments that will be included in the output.
The blank lines are significant, in that they actually cause a return to be emitted as if you hit return on the terminal.
I’m kicking off the asciinema recording from within the itsalive script so that the recording does not include me kicking off the itsalive playback.
The first ##@pause line is because the first invocation of git link-to-commit is going to require me to interact with a pull-down, so I need to pause the playback.
The second one is because I haven’t figured out how to make it emit a CTRL+d to stop asciinema’s recording. So I need to have interactive control over the terminal. I could have had it type exit but that would have been ugly.

Getting the timing right is still a bit of an art. The presenter_view really helped, but I needed to re-record a few times to get all the interactions and timings smooth enough. So, I just started the script off by having it delete any prior recordings (if present).

rm git-link-to-commit.asciinema 2>  /dev/null

## MOVE FAST AFTER THIS
asciinema rec git-link-to-commit.asciinema
git log -n1
# generate a link
## remember to mash then ^e when you get to the hash
git link-to-commit 2a15b8dea0ae606dedb8335e1c3106342e2d79ed
##@pause
##  ^r to RESUME playback
# skip the "choose a repo" step
## remember to mash then ^e when you get to the hash
git link-to-commit -o origin 2a15b8dea0ae606dedb8335e1c3106342e2d79ed
## EXIT ASCIINEMA
##@pause
## HIT ^d
## EXIT itsalive
exit

Demo

The final result.

Raku Signature Errors with Arrays & Hashes

Sat, 01 Oct 2022 00:01:00 -0400

A quick post to help future Raku geeks understand a couple of confusing error messages:

expected Positional[Array] but got Array

and

expected Associative[Hash] but got Hash

These are conceptually the same problem. If you’ve received one of these errors it means you’ve double-specified your parameter by using the @ or % and Array or Hash.

A parameter of Hash %foo says “I would like to be passed something that implements Associative and has a Hash in it.” (a Hash of Hashes). Likewise Array @foo says “I would like to be passed something that implements Positional and has an Array in it”. Yes, that sounds backwards. No, I can’t explain why.

To solve this for hashes you either need to specifiy Hash OR you need to use %, but not both. To solve this for arrays you either need to specify Array OR you need to use @, but not both.

# This won't work
sub bad-hash-signature(Hash %foo){
  say("this will error when passed a simple Hash");
}
# Solution 1
sub good-hash-signature(%foo){
  say("hash was " ~ %foo.raku);
}
# Solution 2
sub alternate-good-hash-signature(Hash $foo){
  say("hash was " ~ $foo.raku);
}

Now, to be extra pedantic, “Solution 1” will allow anything that implements the Associative role. If you really want to lock it down to only accept Hash you need to go with “Solution 2”. The same idea applies to the Positional role and arrays.

Mirroring With Gitea

Mon, 26 Sep 2022 00:00:00 +0000

Table of Contents

Overview

Following on the heels of my last post on why you should (not) self host your git repos, I went ahead and used Gitea to set up a local mirror of all my repositories, and all the repositories I don’t want to loose access to.

The results were surprising, and after reading this, you might want to do the same. This post will be a qick overview of how I did it, some tips that’ll help, and what I learned as a result.

Installation was pretty straightforward. I grabbed my old Raspberry Pi 3B and followed this spectacualar step-by-step guide for installation for installing Gitea. Afterwards a friend pointed out that I could have just installed installed it on our Synology with a Docker image.

The Goal

My goal was two-fold:

I wanted a backup of all my repos. Many of them only existed in GitHub.
I wanted to delete every fork I’d made just to guarantee I had a copy.

The Process

With that in mind I started working through my list of repositories¹. Gitea makes it trivial to mirror a repo. You just choose “new migration” from under the “+” menu, and then click on the service you’re migrating from. There are 3 things that can make your life easier here if you’re importing lots².

Bookmark the form that comes up after choosing a service to migrate from.
If you’re going to be importing a lot you’ll probably want to use a personal access token (GitHub docs). That way you won’t get rate limited by the API, unless you’re migrating (not mirroring) something with many thousands of issues.
Use a clipboard manager. It doesn’t remember your API key so you’ll be pasting it into every form, along with the URL of the repo you’re importing. I use Maccy, and I would recommend it.

For each repo in my list of repos on github, I’d make a couple quick decisions.

for things I authored
- If it was something I am either maintaining or may poke in the future I’d just grab the url and tell Gitea to mirror it.
- If it was something I wandered off from years ago, and am unlikely to ever touch again, I’d mark it as archived.
for the backups of other people’s things
- I’d click through and see if i’d added anything, or if it was just an old copy.
  - If I’d added something, and the original repo hadn’t been touched, I’d mirror my fork.
  - If I’d added something, but the original had moved forwards some significant amount I just abandoned my changes, and mirrored theirs.
  - If mine was just an ancient copy of a repo that’d moved on, I’d go to the parent repo.
    - If the parent repo was archived I’d just tell Gitea to import it but not bother mirroring. There aren’t going to be updates.
    - If the parent repo indicated that it too was a mirror, I’d follow that back to the source repo and mirror that instead.
    - After successfully mirroring I’d delete my copy.

The Learnings

(In no particular order)

First off, Gitea is really impressive. Those devs have done a great job and should be proud of what they’ve built.

Along the way, I discovered that many of the repos that I’d forked had moved on significantly. I had copies that were so old they probably wouldn’t run with modern versions of things. They were also frequently missing lots of new features and bug fixes.

While this isn’t terribly surprising if you think about it, the notable learning is that that’s never going to be a problem again, because Gitea is mirroring them and regularly polling them for updates. If they disappear I’ll have the latest copy before they went away. Github doesn’t give me that option.

I’m not the only one forking repos just to have a copy. Multiple times I clicked through to the parent repo, and got curious. I’d see hundreds of forks, click into the insights page and see that essentially no-one was hacking on it except for the original authors. I guess lots of folks have gotten burned when they discovered that some repo they’d starred or bookmarked was gone when they went to check it out again.

Mirroring isn’t something you can turn on later in Gitea. You must set a repo up as a mirror from the beginning.

Gitea can’t mirror everything. Some repos (like this great command line time zone tool) always error out. Gitea provides no information as to why it failed to clone them down too. I think I encountered three repos like that. Also, I can’t figure out how to clone anything from Sourcehut³. Even when I tried to clone repos manually their http links for cloning always error.

I realized that if i don’t just mirror the tools that I author, and want backups of, but also mirror the repos of tools that I need to reference the source code of regularly then I have a single place I can search for only stuff that’s relevant to me. For example, it’s not uncommon for me to know that one of the libraries I use frequently has a piece of functionality, but not remember which library. Searching Google or Github would be frustrating, because there are just too many responses. But now, I can just search my Gitea install.

The experience of doing this was very cathartic for me. I now know that I have up-to-date copies of all the useful tools I care about. I was also able to delete about 100 repositories from my list of repositories on Github. Now, if a future employer checks them out, they’re almost all things I have actively worked on to some degree. It’s also nice to know that from now on I have a trivially easy way to mirror any useful tool I care about. No more ancient frozen it time forks, and no more bookmarks & stars that cease to exist.

My next step? Going through all the repos I’ve bookmarked, but not forked, and see which of those are worth mirroring.

Before working through your list of repositories, be sure to sort them by name. Mine were sorted by recency and that made things a little harder towards the end. ↩︎
For a sense of scale I ended up mirroring or migrating 169 repos into Gitea. ↩︎
In addition to having a visual style from the 1990’s, and having UX from hell, Sourcehut appears to also just not fucking work as a git host. I don’t understand why anyone uses them, nevermind why anyone pays for them. ↩︎

Do (not) Self-Host your repos

Sat, 24 Sep 2022 00:00:00 -0500

Once upon a time, GitHub was a successful geek enterprise. Then Microsoft bought it, and folks started arguing that you should abandon ship. You should self-host your repos they say.

I 100% agree, and 100% disagree. Let me explain.

GitHub’s been a benevolent host. When they bought NPM they went from being a de facto piece of internet infrastructure to an actual piece of critical infrastructure. At this point you may as well argue that we should sever our connection to the electric company.

But there’s a difference between needing the electric company and ignoring the fact that sometimes the power goes. Usually it’s temporary. Days isn’t uncommon in wintery climes. But every now and then, it’s more. In the case of internet SAAS apps, it’s sometimes permanent.

Why You Should Self-Host

The biggest argument, of course, is backups and continuity of service. If something hapened and you lost access to your GitHub account right now, what would you loose? If you maintain a project with many users and contributors, what would it do to your community, and your work?

GitHub isn’t just where your Git repos are hosted, but where all the metadata that surrounds them. This means years of Issues, Pull Requests, wiki pages, and frequently the project’s web site.

I’ve derived a ton of value from old tickets on GitHub projects. They regularly answer questions, and provid workarounds. The takedown off a popular repo could be a huge loss.

GitHub suspends accounts, and deletes repositories for a variety of reasons. If yours targeted for seemingly “no reason” it wouldn’t be the first.

Even if you believe it won’t, or can’t, happen to you, there’s another reason reason to consider self-hosting: Lock in. Right now (September 2022) GitHub is very good about letting you export everything. As far as I know, there’s no data you can put into GitHub that you can’t also get out via their APIs. In theory.

Our migration has been in the process for a while, but every time we run it we find that our attempts were missing some data, so we need to re-run to fetch missing data, if we had higher limits it wouldn’t take so long to find these issues. Github doesn’t provide tokens with higher limits, so we have to work around that. We even had people with [GitHub Enterprise] subscriptions ask, and they got the same response.

Gitea on Mastodon

Gitea is an open source GitHub alternative, whose creation started out on GitHub. Eventually, the software got really robust, and they decided to host their own repo and issues. The problem is, they’ve got over 20,000 Issues & PRs they want to export. Thousands of those are still open, and the longer it takes them to cut over, the larger those numbers get.

To be fair, 99% of GitHub users wouldn’t have this problem. We don’t have projects that are popular enough, but companies who use GitHub do, and there’s no advantage to GitHub to help large projects or customers leave. They may even consider locking that metadata down to guarantee they stay.

What about GitLab and other Competitors?

You can apply the same reasoning to GitHub’s hosted alternatives. Plus, none of them are as financially successful as GitHub. They’re far more likely to go out of business, and screw everyone who uses them.

Why You Shouldn’t Self-Host

Right now it’s incredibly improbable that you’ll have your account suspended. The stories of suspended accounts are rare. Most of them seem to be from government action,or “Terms of Service” violations that most geeks react to with “Yup. Seems fair.”.

There’s also the fact that self-hosting is work. But let’s set that aside for the moment. Let’s pretend there’s some magical free button you can click that takes care of everything. Boop. You’re self-hosted now.

Let’s also assume you’ve got a project that’s popular / useful enough to get Issues and the occasional Pull Request.

How is that going to happen on your new site? Well, first they’re going to need to set up an account on your server. Are they going to think it’s worth it? Worth it enough to give their email to yet another stranger? If they want to submit a fix / feature, is it also worth it to figure out how to fork it in this not-GitHub? Worth it to figure out how its PR equivalents work? These probably aren’t hard, but every little difference they have to navigate is another reason to not bother.

And then there’s discovery. GitHub isn’t only the default place to look for code. They’ve also got massive “website authority” in Google. It doesn’t matter if you’re the only place hosting your thing. Any project on GitHub that’s remotely similar to your search terms is likely to come up before your site.

But, even if you’re ok with all of that. There’s an even bigger reason you shouldn’t self host. A reason we shouldn’t encourage folks to self host. Sooner or later you’ll get sick of bothering, or you’ll die. One is guaranteed. The other has lots of historical precedence.

I’ve bookmarked thousands of useful web sites over the years. A huge chunk of those have been useful, and insightful blog posts about development. Hundreds of them don’t exist anymore. Mostly because the person who ran them simply didn’t feel like bothering with it anymore. How many millions of others have poofed out of existence?

But, a repo isn’t some just random thoughts. Almost every repo contains some useful tool or library. Sooner or later, someone’s going to need tha. There are thousands, probably millions, of little repos out there containing the only bit of code in existence, that solves that particular problem. Sometimes they’re just the only thing that solves it in that particular language. When you stop hosting it, for whatever reason, that useful tool ceases to exist. Even if it’s “just a port”. That’s a lot of work that someone will need to recreate, and debug.

So what’s a geek to do?

Before I answer that, let me note that this bit gets into implementation strategies. If you just came for the question of “should I, or shouldn’t I?” you can stop reading. Thanks for making it this far. Good luck whatever you choose.

–

So, what to do…

Short short version: If lots of people rely on your project, then mirror your code to a large competitor and accept that you may loose access to your issues, PRs, etc. . Stick a note in your README so that folks know where to find your mirror before lightning strikes.

If you’re like most open source developers, you’ve got some repos that are mostly ignored by the world, and receive essentially no issues or PRs. No-one’s going to be stressed if your repo disappears for a week. So, Install Gitea on your computer. Tell it to mirror your repos and forget about it. Or, just clone the all locally and set up a cron job to regularly pull down changes.

Longer version: I think that depends a lot on what, if any, metadata exists in your GitHub repos. Most devs have small repos that are mostly just used by them. If this sounds like you, then simply keeping an up-to-date copy of them on your home computer could be fine.

Things are different if you maintain some repo that other people actually care about enough to make issues, or even contribute code to.

In that case my personal advice is to host your stuff on Github, but have it mirrored to a second system. Ideally you’d want all your issues, PRs, etc. mirrored to it. But as far as I know, that’s not actually something you can do. It’s easy to keep the code synced to a mirror. It’s the metadata that’s a problem. To be clear, I’m not saying it’s not technically possible. I’m saying, I don’t think anyone’s actually written the code to keep those synced between GitHub and any open source alternative. It’s a hard problem because Issues, PRs, comments, and just about everything else can be edited.

So, that leaves you with regularly backing up your stuff. I’m going to assume you’re not someone with ~10k open & closed issues, plus another ~10k PRs like Gitea. So, exporting your issues is probably something that’s actually doable. Exporting. Not syncing. However, the more things you have to export, and the more frequently you want to back it up, the more likely you are to hit your rate limits.

If you go this route, you’ve got two options. You could use something like the gitea-github-migrator that can export everything. Tools like that are made to create a new repo in GitHub alternatives, not sync to them. You’d be constantly churning, deleting old repos and setting up new ones.

A better solution might be something like github-issues-mirror which can download all your issues as JSON files. Keep that running in the background and if worst comes to worst you can write an importer for wherever you’ve been mirroring your code.

What am I going to do?

I think I’m going to install Gitea on my Raspberry Pi. I’ll tell it to mirror all my repos, and all the repos of useful tools I want to always have a copy of. I do maintain some repos which are somewhat useful to other people if GitHub deletes them. No-one will be screwed, and I can take my time in uploading a backup somewhere else. I’ll stick it in the basement with the router and back it up to our NAS, which backs up to B2.

Syncing Homebrew Installs

Wed, 07 Sep 2022 00:00:00 +0000

Those of us who love the command line, have a tendency to install a lot of useful utilities, and want them available on all our computers. On macOS we tend to use Homebrew. This document serves to describe three ways to generate a useful file to solve that problem.

As I see it there are 3 basic approaches to syncing your homebrew utilities across machines.

I don’t care about the details, just make it work.
I would like a simple installation document that
- lists what I’ve installed
- what each is for
- can be used to install the same things on other machines
I would like an efficient installation document that
- lists what I’ve installed
- what each is for
- can be used to install the same things on other machines
- won’t waste time trying to reinstall things already installed
- can handle post-install tasks, and make sure they only get run once.

This pots will address each of those, in order.

I don’t care about the details, just make it work

run brew bundle dump
- creates a Brewfile document in the current directory.
copy that to the other machine
cd to the same directory as the Brewfile on the new machine
run brew bundle

That’s it. You’re done.

I’d like a simple installation document…

The following script will generate a documented bash script called brews.sh which you can then sync across machines via whatever your normal method is. The downside to this is that rerunning it on a synced machine after adding one or two entries is going to be really slow. Also, there’s no good way to include post-install setup and have it still be idempotent and not break things. Post-install setups should generally only be run once, not every time you load the file.

The file will look like this:

#!/bin/sh
brew tap charmbracelet/tap
brew tap d12frosted/emacs-plus

# Strip or convert ANSI codes into HTML, (La)Tex, RTF, or BBCode
# http://www.andre-simon.de/doku/ansifilter/ansifilter.html
brew install ansifilter

# Official Amazon AWS command-line interface
# https://aws.amazon.com/cli/
brew install awscli

# Clone of cat(1) with syntax highlighting and Git integration
# https://github.com/sharkdp/bat
brew install bat

#... and so on

Here’s the script that generated it (presumes you’re runing in bash / zsh shell)

echo '#!/bin/sh' > brews.sh;
brew leaves --installed-on-request \
  | grep --color=none "/" \
  | sed -e "s/\(.*\)\/.*/\1/" -e "s/^/brew tap /" \
  | sort -u \
  >> brews.sh;
brew info $(brew leaves --installed-on-request) 2>/dev/null \
  | grep --color=none -A2 "==> [^[:space:]]\+:" \
  | grep -v -- "--" \
  | sed -e 's/==> \(.*\):.*/brew install \1/' \
    -e '/^brew install/!s/\(.*\)/# \1/' \
  | ruby -e 'lines=STDIN.each_line.to_a; (2..(lines.size - 1)).step(3){|n| puts "\n#{lines[n - 1]}"; puts lines[n]; puts lines[n - 2]}' \
   >> brews.sh
chmod u+x brews.sh

I’d like an efficient installation document…

This is basically the same idea BUT it adds in 3 bash functions at the top, which make rerunning this much faster and allow you to do post-install setup if any of the things you’re installing need that.

Start by creating a new file called brews.sh and adding this to the top of it. I’ll explain how to use them at the end of this section.

#!/usr/bin/env bash

# NOTE TO FUTURE ME
# run the following to extract the relevant info to manually append to this
# brew info <some_command> | head -n3

##############################
# BEGIN FUNCTIONS
function maybrew() {
	if ! is_installed $1; then
		install_or_die "$1"
	else
		echo "-- Skipping $1 (installed already)"
	fi
}

function install_or_die() {
	brew install $1
	echo ""
	echo ""
	echo "-- Installing $1"
	brew install $1
	if [ $? -ne 0 ]; then
		echo "problem installing $1"
		echo "exiting"
		exit 1
	fi
}

function is_installed() {
	if brew ls --versions $1 > /dev/null; then
		# the package is installed
		true
	else
		# the package is not installed
		false
	fi
}
# END FUNCTIONS
##############################

Next we’ll run a script that’s almost identical to the last one, except instead of calling brew install foo it’s going to call maybrew foo.

brew leaves --installed-on-request \
	| grep --color=none "/" \
	| sed -e "s/\(.*\)\/.*/\1/" -e "s/^/brew tap /" \
	| sort -u \
	>> brews.sh;
brew info $(brew leaves --installed-on-request) 2>/dev/null \
	| grep --color=none -A2 "==> [^[:space:]]\+:" \
	| grep -v -- "--" \
	| sed -e 's/==> \(.*\):.*/maybrew "\1"/' \
	-e '/^maybrew/!s/\(.*\)/# \1/' \
	| ruby -e 'lines=STDIN.each_line.to_a; (2..(lines.size - 1)).step(3){|n| puts "\n#{lines[n - 1]}"; puts lines[n]; puts lines[n - 2]}' \
	>> brews.sh
chmod u+x

Once again, you’ve got a brews.sh file that you can sync, and append to over time.

The Three Functions

maybrew takes a package name as an argument and asks homebrew if it’s installed. If not, it attempts to install it. The script will die if it fails, because you’ve got bigger problems to sort out at this point.
install_or_die takes a package name, and installs it or dies. called by maybrew
is_installed performs the fastest test i could find to determine if a homebrew package is installed. This is what you’re going to want to use if you need to do post install setup.

Usage

maybrew

Just call it with the name of a package: maybrew foo
install_or_die

Just call it with the name of a package: install_or_die foo
is_installed

Use this in an if statement to test if something’s been installed. If not, install it, and perform whatever post-install things the given script needs. For example, here’s how i use it to install fzf

if ! is_installed "fzf"; then
	# install it
	brew install fzf
	# now do post install setup for fzf
	y | $(brew --prefix)/opt/fzf/install
else
	echo "-- Skipping fzf (installed already)"
fi

An explanation

For those of you who think those scripts look like dark magic, and would like to understand how they work, here’s a breakdown. For everone else, you can stop here. Good luck.

# DO NOT RUN THIS ONE. IT WON'T WORK
# There isn't a way (that i know of), to continue a line ( \ ) AND
# have a comment before the next line.

# create a new file with a "shebang line". Unix reads the first line
# of the executable and if it starts with `#!` and a path it will pass
# the contents of the file to whatever executable lives at that path
# the  `> brews.sh`  tells it to send the output of echo to a new file
# named brews.sh
echo '#!/bin/sh' > brews.sh;
# `brew leaves` outputs the minimal list of things to install
# to regenerate your setup. Their dependencies will fill in the gaps
# BUT that's not necessarily the list of things you specifically
# told it to install. `--installed-on-request` should be just
# the list of things you specifically told it to install.
brew leaves --installed-on-request \
	# if the line has a / in it, it means its a package installed from a tap
	# and we need to run `brew tap` on them before we can install them
	# so i'm trying to extract the taps. This isn't perfect, but it seems to work.
	# `--color=none` is to compensate for anyone who has their grep configured to
	# highlight matches (like me).
	| grep --color=none "/" \
	# strips off the last slash and everything after it
	# foo/bar/baz becomes foo/bar
	# then replaces the start of the line with `brew tap`
	| sed -e "s/\(.*\)\/.*/\1/" -e "s/^/brew tap /" \
	# sort the results and only include unique items
	| sort -u \
	# append the output to the brews.sh file
	>> brews.sh;
# `brew info` optionally takes multiple lines of input.
# If you do this it's way faster than calling brew info
# on each item that `brew leaves` returns individually.
# so that's what we're doing. HOWEVER this always produces
# errors and warnings on my machine that you can't do anthing
# about so `2>/dev/null` instructs it to take everything printed
# to Standard Error and shove it into a black hole.
brew info $(brew leaves --installed-on-request) 2>/dev/null \
	# this is a long piece of output, but we're looking for the
	# lines with package names. Those can be identified by
	# the fact that they all start with this (but with the appropriate
	# package name)
	# `==> package_name:`
	# extract those lines with `grep` using a regexp that asks for
	# lines with ==> followed by a single space, and 1 or more non-space
	# characters and then a colon.
	# we also want the 2 lines that follow.
	# the first line afterwards is the short description of the package
	# the 2nd line afterwards is the url where you can find it.
	# for example:
	# ➜ brew info git | head -n3
	# ==> git: stable 2.37.3 (bottled), HEAD
	# Distributed revision control system
	# https://git-scm.com
	| grep --color=none -A2 "==> [^[:space:]]\+:" \
	# each section is separated by a `--` line.
	# get rid of those lines with `grep -v`
	# this is problematic because shells can't tell the
	# difference between an argument of -- and "--" so
	# it interprets the -- as the start of a command like
	# `--color=none` from above. So, we use a common Unix
	# idiom of passing JUST `--` which is generally interpreted
	# to designate the end of the options to the command.
	# now that it knows the next thing won't be an option,
	# we can give it the thing we actually want it to search for "--"
	| grep -v -- "--" \
	# the line with the ==> is the one with the command name
	# perform a regular expression capture for the stuff
	# after the space and before the colon (the command name)
	# then replace the line with `brew install <captured text>`
	# `\1` just means "the first capture group".
	| sed -e 's/==> \(.*\):.*/brew install \1/' \
	# take every line that DOES NOT start with "brew install"
	# The `/!s/` bit is the pice that makes this magic work
	# capture the entire line, and then print out a #
	# to make it into a comment, and then the whole captured line.
	-e '/^brew install/!s/\(.*\)/# \1/' \
	# things are in the wrong order.
	# as you can see in the `brew info git` example above, its
	# 1. command, 2. description, 3. url.
	# I want the 2. description, 3. url, 1. command.
	# this would probably be a nightmare in bash, so i just
	# did a ruby onliner that reads everything from Standard input
	# into an array, iterates over the array jumping 3 ahead each time
	# (it's always a set of 3 lines), then prints out the lines
	# in the order i want with an extra newline before the first one
	| ruby -e 'lines=STDIN.each_line.to_a; (2..(lines.size - 1)).step(3){|n| puts "\n#{lines[n - 1]}"; puts lines[n]; puts lines[n - 2]}' \
	# append it all to the brews.sh file
	>> brews.sh
# make the file executable.
chmod u+x brews.sh

On the "problem" with AI generated art

Sat, 03 Sep 2022 00:00:00 +0000

There has been a lot of uproar about the “ethics” of AI generated art from tools like MidJourney, Stable Diffusion, and Dall-E. People talking about “theft” and “copyright infringement” and how artists should be paid for “stealing” their styles.

This blog post intends to break down the ridiculousness of those claims with simple logic, and historical counterarguments. I’ll show how the uproar is ultimately just an emotional knee-jerk reaction by people ignorant of the reality of art, illustration, and these AI systems.

For context, I’m speaking as someone who owes their childhood and early adult life to the visual arts. My mother was an artist. She literally lived with, and studied under, Picasso. Her works hang in multiple museums. She taught privately, and at many colleges, including Harvard. I personally spent years as a Graphic Designer. When I wasn’t making brochures for people I was making graphic art for myself. Since then I’ve become a programmer, but I’ve never stopped thinking about art, and I am grateful for what art has done for me, including, but not limited to putting a roof over my head, and feeding me.

The biggest, and most frequent argument is that artists should be paid for the “style”. This is a purely emotional reaction based in ignorance of many, many things.

First, copying the style of other artists is literally the core functionality of an art student. Studying the work of those who have gone before us and succeeded is how we learn anything efficiently. You want to learn how to capture light? Go study Rembrandt. Attempt to replicate his pieces until you intuitively understand the techniques he used. That is to say, learn his stuff until you can make things that look like Rembrandt made them. Want to learn another technique? Go find another artist who’s great at it and repeat. This isn’t juts good advice. This is literally what they instruct you to do at art school. It’s what every generation of artists have done.

At a simpler level, think of all the kids drawing anime style art. They are literally copying the style of people who are good at the art they like. Nobody is yelling at them that they should pay Toei Animation Co., Ltd. for not only “stealing” Sailor Moon’s style. Toei isn’t coming down on them demanding money when they grow up and start making their own Anime or Manga in a similar style.

As I said, the core functionality of an art student is studying other artists, learning their style, and incorporating it into their own experience and expression. This is literally what tools like Midjourney do. They study other art styles, learn from them, and learn to create new things based on what they’ve learned from all the styles.

Why then would this be acceptable practice for a human, but not for a computer? It’s literally the exact same thing. Is it because computers are “better” at it than humans?

Saying they’re “better” at it is bullshit. For generations there have been master forgers who have not only replicated the style of master artists but their paintings down to the brush-strokes. They can do it to such a degree that the “experts” have been fooled. Mostly, they have just replicated the style of another artist meticulously, and sold “newly discoverd” paintings by them. A computer can learn more styles well than the average artist, but I assure you they’re still not “better” at replicating it than a master forger.

Keep in mind that creating a master forgery is 100% legal for a human. If the forger didn’t try to claim it was someone else’s they’d be probably praised for their incredible talent. Alas, artists are paid crap, so they’re better off pretending their work is someone else’s and never receiving credit for their years of practic and incredible skill.

So, again, why is this acceptable practice for a human, but not for a computer?

Artists have used the best technology available to them since the beginning. The pinhole camera came into use around 300BC to trace the world. They added a lens to it in the 1500s and called it a Camera Obscura. In 1806 the Camera Lucida was invented. John W. Audubon (son of the famous Audubon) used it to reduce the size of his fathers folio of prints to a more affordable size. Literally used to copy the style, color, and everything else to the most exacting details possible at the time. None of these technologies are illegal, and no-one is yelling that they should be. If the argument is that technology shouldn’t be allowed to facilitate the replication of someone else’s style then surely these are ever more forbidden, because they are made specifically to replicate the exact thing you’re looking at.

The most “cogent” argument I’ve heard for why this shouldn’t be allowed is that illustrators will go out of business. This is exactly the same argument illustrators used when we started being able to print photographs. Guess what, we still have illustrators. “Ahh but this is different! because…. computers!” Just. No. Anyone who claims this doesn’t know what they’re talking about. They don’t know what it means to be a professional illustrator, and they don’t know what modern AIs are actually capable of.

An illustrator is paid to convey a specific idea. They’re paid to interpret what the client is asking for, and translate that through their style or a style of the client’s choosing, into a piece of art that reflects what they asked for. Yes, clients dictate style all the time. What the client rarely considers is that they’re also hiring the artist for their experience both in knowing what kind of things work to convey the idea visuall, but in what types of things the target audience will find acceptable.

As a general statement, clients have no fucking clue what they need, only a vague sense of what they want, and frequently ignore the advice of the expert they’ve hired to produce a useful illustration, before trying to pay them too little for their services.

So, let’s take a look a the current state of the art. It’s not clear to me who generated the following but you can find the originals here.

Let’s look at what they asked for.

Gigantic extraterrestrial futuristic alien ship landed on the kingdom of julius caesar, roman historic works in brand new condition, not ruins, hyper-detailed, artstation trending, world renowned artists, historic artworks society, antique renewel, good contrast, realistic color, cgsociety, by greg rutkowski, gustave dore, deviantart

And here’s what they got

Things they asked for but didn’t get:

an alien ship (giant or otherwise)
roman historic works in brand new condition (frequently no roman works at all)
not ruins
something that looked like it was made by “gustave dore”
something that looked like it was made by “greg rutkowski”
realistic color

So, the digital illustrator has utterly failed to capture the design in every meaningful way.

It did, however, produce cool images. This is not even remotely atypical.

The thing is, describing an image is exceedingly difficult. If a picture is worth “a thousand words” it’s only because we have enough shared context to understand all the implied things that are left out of those thousand. To describe an image to a computer in sufficient detail as to actually get what you’re imagining would require tens of thousands of words, because computers don’t have an understanding of what it is to be human. Furthermore, they don’t understand language… Like, at all. They’re exceptionally bad at extracting meaning. Witness the dumpster-fire of the results above. Witness the sentence “dumpster-fire” and how it doesn’t actually mean that there is a dumpster, on, or with a fire in that context.

In my experience with Midjourney there are a few things you can get it to do well. Very, very, few of those things are actually directed in any meaningful way.

For example, some friends of mine like turtles. I decided to try and make them a cool racing turtle. I started by asking for a turtle with exhaust pipes getting a pit stop. I got this.

I then tried to get a turtle that was either racing, or in a racing car. I went with a more cartooney style because it didn’t understand what a turtle was at all, and after generating nearly 400 individual images this was the best I could do.

I was however, able to get a bunny in a racing car. Midjourney is oddly good at bunnies.

Overall, Midjourney is incredible. It can do amazing things, and you’ve probably seen them. For example, here are some of the things from the community feed as I write this.

What you’re not seeing is that the amazing images being shown off are the cherry-picked best-of-the-best. Your not seeing the countless horrible, distorted, inhuman attempts that it took to make them. You’re not seeing the fact that basically none of these are what the person asked for. You’re not seeing that if you take the exact phrase they used, you will get something radically different.

For example. In the composite image below, the large image on the left is something a community member called CannedGoods generated. The original is here if you’re a Midjourney user.

To the right, is what Midjourney emitted when I entered the exact same phrase they used.

an advanced world with ethereal temples suspended in fractal clouds echoing the past, high detail, intricate Fibonacci design, epic emotional detailed cyberpunk sci-fi fantasy pre-Raphaelite art

As with the prior example, what was generated isn’t what they asked for. Mine is closer to the brief, but there still aren’t “fractal cloud”, it’s not “high detail”, and it doesn’t involve “Fibonacci” in any obvious way. What’s important though is that there is nothing replicate-able here. What’s generated is almost entirely random. As a general statement, you can’t get what you want.

The problem of getting what you want is so bad that a business called PromptBase has cropped up to sell collections of keywords that will generate a particular style on a particular AI. It’s not going to help you get the content you asked for, but you will help you guide it to a particular style.

At this point, someone’s probably yelling about how this is what they’re talking about. They’re yelling that the artists are getting screwed, and other people are profiting from it: the AI systems, and now these people selling things to use the AI systems. This is where I have to remind them that the artists were never profiting from it. The fact that there’s a computer copying their style is irrelevant. Style isn’t, and shouldn’t be, copyrightable.

So, let’s address that. An artists “style” is even harder to define than “obscenity” which infamously boils down to “we’ll know it when we see it.” The idea of copyrighting “style” would be a legal nightmare that, if implemented, would functionally destroy the visual arts industry. “Style” could be defined so broadly, and an artist could have so many “styles” that you’d end up with a few people owning everything and no-one else ever being able to sell anything. You think patent-trolls are bad? Just wait. But, it also has the same problem. Just about any “style” you try and claim as your own has prior art. New “styles” are rare. Practically, even some brain-damaged idiot did decide to save the patient buy cutting of it’s head, it’s not copyrightable now.

And, while I’m at it, why is no-one bitching about the “theft” of written style? AI has been doing that for years and no-one gives a damn. As with visual artists, writers have been doing it since the beginning of writing.

But let’s get back to the generation of images. As I said, it’s terrible at giving you exactly what you want, unless what you want is to wander down a rabbit hole of imagination and see where you end up. The people in the Midjourney discord are celebrating these pieces of uncontrolled emergent beauty.

For example. Midjourney went down for a few minutes while I was writing this. Today’s commnity theme is “echo”, so i created this: “echoes of a time when midjourney was down and the people found themselves with lost and wandering”. Each of these is a new piece of art, synthesized from the study of thousands of artists, processed through a system divorced from any real linguistic understanding.

These are beautiful unique, heretofore unseen pieces of art. And they’re just the starting point. Each one is a road waiting to be explored. With some skill, you might even be able to guide them.

To summarize:

Copying style is how artist learn to do what they do. No-one “owns” their style, and attempting to make style legally copyrightable would destroy the industry. The best available technology has always been used to copy the style of others. It always will be.

There is no way in hell that illustrators are going to go out of business as a result of AIs like Midjourney, or Dall-E, or Stable Diffusion. The systems simply aren’t capable of giving you what you ask for. If you think that’s “just around the corner”, you are showing your ignorance about how hard the computational problem of language comprehension is, and how incredibly important lived experience is to providing context even when you know the meaning of the individual words.

If you are honestly concerned about the fate of illustration and want to do something to improve it, pay an illustrator to illustrate. Do not complain at their prices. Do not haggle, because you don’t think it’s “worth that much”. You don’t need to have some business reason to commission them. If you like an illustrator’s work, pay them money to make you some.

If you are an illustrator, and still fear for your job after reading this, drop me a note, and we can discuss it. If you’re not an illustrator, and you’re not paying illustrators for their art, then please shut up. Your attempts to help are ignorant, and if you succeed you will screw all the arts massively. It’s hard enough to make a living as an artist without your “help”.

gh-url script to get GitHub url for a file

Mon, 15 Aug 2022 00:00:00 +0000

The Problem

For the past decade or so, I’ve noticed a trend amongst my coworkers. When they need to look at the contents of a file that they’re not currently editing, they will go to GitHub, and click their way down through the folder structure until they eventually find the file they want to see the contents of.

On a related note, I believe that most of my coworkers don’t know how to take a relative path in a repo, and tell their text editors to open it.

For example, let’s assume we’re working in the same repo, and you’ve already got a file open in it in your editor. If I were to tell you to open foo/bar/baz.rb would you know how to tell your editor to open that file directly, without manually clicking to open the foo and bar folders and then clicking on the baz.rb file? For most developers the answer seems to be “no”, even though their editors can probably do it easily.

So, if I need to communicate the file I want you to look at, how do I do so in a way that makes your life as easy as possible, assuming you’re like most devs?

Easy, I give you a link to the file in GitHub. But how do i easily acquire that link?

The Solution

gh-url is a script I wrote to take a given path within a repo and generate a GitHub url for it, and optionally, open it in your browser.

So, for example i could say take that foo/bar/baz.rb path and say gh-url foo/bar/baz.rb and it would output a link to that file in GitHub. It takes care of making sure it links to the right branch, and if you have multiple remotes, it asks you which one. Just run it without any arguments to see the usage instructions.

On GitHub Achievements

Thu, 09 Jun 2022 00:00:00 +0000

GitHub recently announced GitHub achievements. It’s a great idea, but I’m really left scratching my head by what the achievements are.

The “Pull Shark” is open pull requests that have been merged. I’ve got a “4x” version. 4x makes NO sense to me given the number of repos I’ve contributed to, but… ok. Maybe it just maxes out at 4x.

That’s it, though, except for “Arctic Code Vault Contributor” which … is more chance than anything else.

I don’t really care that I don’t have more. BUT I can’t figure out what the eff they’re expecting a person to do that they would use to “recogniz[e] the many stages of a developer’s coding journey” that I haven’t done in my GitHub account.

Doubly so because Coderwall already did this for GitHub profiles years ago. They give you “achievement badges” by assigning you to “Organizations” that represent your achievements, and then those show up as icons in your “organizations”

…and they’re cool. Really well thought out. I’m having difficulty finding a full list of the Coderwall achievements, and I’m not sure this is even something they do anymore, but here’s the ones I have. I’m not suggesting they should ALL be used as GH achievements, especially not the language specific ones like “Mongoose” (see below) BUT things like the “Charity” and the “Walrus” badges? Those would be great GH achievements.

Lemmings 100: …have open sourced at least one original repo that’s being watched by more than 100 devs.
Charity: …members that have forked and commited to someone’s open source project.
Opabinia: members that started social coding on GitHub within 6 months of its first signs of life.
Forked: …members that have open sourced a project valued enough to be forked by someone else.
Forked 20: members that have open sourced a project valued enough to be forked at least 20 times.
Komodo Dragon: members that have open sourced at least one original repo where Java is the dominant language.
Mongoose: members that have open sourced at least one original repo where Ruby is the dominant language.
Mongoose 3: (same as Mongoose > 3x)
Raven: …members that have open sourced at least one original repo where some form of shell script is the dominant language.
Velociraptor: …members that have open sourced at least one original repo where Perl is the dominant language.
Walrus: …members that use at least four different languages throughout their open source repos.

I guess my thinking is that I’ve done just about everything a person could do in GH except for having a repo used by millions BUT even on that I prolly contributed to one at some point. And yet, all i have is recognition for getting a PR merged?!?!

I know it sounds egotistical, and entitled, but the reality is that I’ve been using GitHub professionally and personally since roughly the time it began. Off the top of my head here are the things I’ve done in GitHub that are relevant to “the many stages of a developer’s journey”

I’ve got original and forked repos in piles of languages.
I’ve contributed to other people’s open source repos in the form of reporting issues, contributing to discussions, and submitting PRs.
I’ve taken over ownership of other people’s repos when they abandoned them.
I’ve done work in obscure languages, popular languages, and even Bash.
I’ve had a repo starred by hundreds
I’ve had repos forked my … many
I’ve got repos in compiled and interpreted languages
I’ve done all the normal, and most of the rare things you can do with git.
I’ve shared my dotfiles for others
I’ve contributed to languages, frameworks, and libraries
I’ve got repos with server code and repos with client code.
I’ve made private repos public, and public repos private.

What else is there in a “coding journey” that GitHub could be aware of that I haven’t done? I assume “YoLo” is some whimsical thing that maybe I haven’t done but setting aside random silly / quirky achievements, the fact that the only one I’ve got is “PR Shark” makes me wonder if they actually have any more than the 3 shown on their announcement page.

How To Register an Internationalized Domain Name

Thu, 26 May 2022 00:00:00 +0000

( A guide for English speakers as of May, 2022)

I’m going to assume that this isn’t terrible if you speak a language which doesn’t look anything like English. I’m going to assume that your domain name registrar’s don’t have their heads up their butts.

Over here in the English speaking world they’re too anglocentric to notice anything that goes on in languages that have non-ascii characters. Since you’re reading this, you probably use a lot of software that was written by American companies. This means that even if you do succeed in buying an Internationalized Domain Name (IDN) there’s a very good chance that anything you try and stick it in that isn’t a browser will reject it. Especially if you try and use it for email.

If you still want to do it, the process isn’t terrible, if you know how things work.

Key Information

Not all Top Level Domains (TLDs) like .com, .org, and so on) allow IDNs.
The companies that control each TLD, sometimes require you to specify the alphabet type you’re registering (Japanese, Chinese, etc.). As far as I can tell this is completely unnecessary but they require it anyway.
Most registrars don’t allow you to specify the character set so it doesn’t matter if the TLD supports it or not because you can’t register it without specifying.
IDNs are an ugly hack, and aren’t actually unicode.

Finding A TLD That Supports Your Language.

I have no good advice for you here. All I can say is that if you’ve seen a domain in your language, then you know you can use whatever TLD it used. Searching for this is hard but the keywords you need are “IDN” and “registrar”. You can try searching for the domain on Gandi.net and hope there’s a globe next to the TLD you want in your results. If there is, you can try specifying the language you want and it’ll either accept it or tell you it’s not allowed. If there’s no globe, the TLD may or may not support IDNs but it probably won’t work if you try to buy it there even if it does. .com, for example, does support IDNs but has no globe, and gives you an error when you try and buy it even for languages that are allowed.

Getting A Punycode

Let’s address that last point first, because it’s critical to you being able to register an IDN. Let’s say you want to register バター.com You can’t actually do it (even if no-one else has). You have to convert it to “Punycode”. In this case the punycode is xn--5ck7a3i.com. You can, in theory, register that.

In practice, you still can’t. At least, not with most registrars, but I’ll get to that in a minute.

There are 2 ways to get your punycode:

use a punycode converter like https://www.punycoder.com/
just type the domain you want into Firefox. If it works, someone has it and you’ll need to think of something else. If it doesn’t it’ll give you an error message with the punycode version.

NOTE: Do not include the TLD in the punycode conversion. So, again, if we want バター.com we enter バター into the converter and it gives us xn--5ck7a3i then, take that and add the TLD like `.com to it.

Do not even bother trying to mix character sets like this バターสมศักดิ์. It’ll convert to Punycode just fine ( xn--12c2bwb2ai8bxa6ql661a3ea9s ) but you’ll hit the problem of the TLD owners wanting you to specify the character set and you can’t specify more than one.

Registering your Punycode Domain

Ok, now you’ve got the punycode. How do you register it?

In, theory, you register it just like any other domain name, but as noted above, you have to indicate the character set, or you have to find a registrar who can figure it out automatically and do that for you. In practice, there’s no way to know if it’ll work until you try and actually buy it.

Here’s my experience
( tl;dr: go to 101domain.com )

Hover.com has the problem that you can’t seach for バター.com. It deletes the バター part and thinks you’re searching for com. If you enter バター it thinks you’re searching for nothing. You can search for the punycode version though. After getting past that I got “order completed” “payment rejected” and some other error I’ve forgotten at checkout. I got different, or multiple, messages / errors on each attempt. It wasn’t the payment at all. It was Hover.

So I tried Gandi.net. There I noticed something interesting. For some TLDs it had a globe icon which gave you a form to choose a character set when you clicked it. There wasn’t one for .com, but when I tried to complete my order it give me a brief alert telling me I needed to specify the character set. It wasn’t possible with their site, but at least I had a clue what the problem was.

After some googling I found 101domain.com. I gave them a shot because they also support Internationalized TLDs. I figured if they did that, they must have a clue about the “normal” IDNs, and I was right. Even better, it handled unicode searches like バター, and when I went to buy my shiny new domain they handled specifying the character set silently.

They’re not my first choice is registrars for a number of reasons, but they don’t seem to be trying to scam anyone, checkout was relatively painless, and my new domain works. In 60 days I’ll try transferring it to Hover with my other domains.

What about Internationalized TLDs

These exist. For example .コム is a Japanese TLD. My advice, at this point in time, is to assume that these will not work anywhere except the browsers. The thing is, you enter your domain name in a lot of places that aren’t browsers. For example, every time you enter an email address, or paste a link in Slack.

You’re going to have an even harder time finding a registrar that supports those, but if you do they’ll probably handle the other problems well.

I have no idea how to convert a TLD like .コム to ASCII, but I assume it has to happen and that there’s a magic incantation there. If you know, contact me and I’ll update this.

What you need to know about Mastodon

Sun, 01 May 2022 00:00:00 +0000

The goal of this post is to give you the information you’ll need to start using Mastodon before Twitter becomes even more of a dumpster fire than it currently is. It assumes that you’re familiar with Twitter and that you’d like to see if you can continue your twitter-like postings over on Mastodon.

I’m going to cover the following topics:

what the deal is with all the different servers / instances
instances as communities
moderation
choosing an instance
how you use Mastodon
what’s different

Before that, I’d like to recommend you watch this 6 minute intro to Mastodon. I’ll fill in the details afterwards.

Ok, assuming you’ve watched that, let’s talk about the biggest mental hurdle “the servers”, why they exist, and how to choose one.

The Servers / Instances

Every Mastodon instance has a unique domain name (think gmail.com or hotmail.com) and every user has a username at that domain (think me@gmail.com). And just like email, everyone can send messages to each other even if they have accounts with different domain names. me@gmail.com can send an email to you@hotmail.com.

The only difference is that Mastodon is sending tweets … er “toots”, instead of email.

Just like email, you have to pick an instance / domain before you can start sending messages. Just like email, you can move your account, with its history of messages to another server.

Instances as communities

Here’s where things start to diverge from email. Mastodon instances are communities. Some of them are topical. Some of them are more like Twitter, and encourage folks to talk about whatever they want.

For example: I’m on one with a focus on Tabletop Role Playing Games, and another that’s for any topic, as long as it’s in Esperanto. My wife is on one that’s for anyone talking about anything.

Like real world communities each one has its own set of rules about what type of things are allowed. Sometimes, the only notable thing about an instance is this social contract. For example one of the larger instances mstdn.social isn’t topical at all. Its server rules are essentially “Don’t be a bigot, and don’t do bad things”.

It’s really important that you check out the “server rules” before joining because they tell you a lot about the values of the people on that instance.

I’ll cover what the practical effect of choosing one of these communities in the section on how you use Mastodon.

Moderation

The server rules are the first line of defense for keeping mastodon communities healthy, but they’re not the only defense. Every instance has at least one moderator, and they aren’t beholden to any corporate restrictions. They can, and should, boot anyone from the server that violates their social contract. No checking special wording from HQ. Just, you’re a jerk, so I’m banning you.

There’s another more heavy-handed defense that you’ll also see. On most instances, if you scroll down below the “server rules” you’ll see a list of servers that are being blocked outright, media that’s being filtered, and so on. More importantly, you can see the reason they were blocked. That tells you a lot about the values of the moderators on that instance.

Because anyone can set up a new Mastodon instance, there are a instances that gather folks who want to discuss… topics most folks wouldn’t find acceptable.

On Twitter you can message your favorite movie star, even if they’ve never heard of you. Mastodon is exactly the same. It’s not uncommon for an instance administrator to decide “that instance over there is almost entirely racists looking to cause trouble, so I’m going to block them to protect my community.”

As a result, Mastodon is a much nicer place overall because small communities can protect themselves better than some massive company trying to enforce a “fair” set of rules.

Choosing an instance

Most people start at joinmastodon.org, click the “Get Started” button and look for an instance to join.

This is a great start, but if you don’t find an instance you’re interested in, Google is a good option. For example, I searched for “mastodon server for ttrpg geeks” and i found a server that was precisely that.

Once you find a potential server, read their server rules, then click the “See What’s Happening” link. See what conversations are like, and if you’d like to be on an instance with these folks. As above, I’ll discuss the practical effects of your choice of instance in the section on how you use Mastodon.

If you don’t find any instances that sound like a great fit you’ve got two options. The easiest is to just find one that isn’t a bad fit.

The other option is to actually start up your own instance. Masto.host makes this easy and using a services like theirs shouldn’t require any geeky skills. Start with the cheapest plan and upgrade as more people join. Note that you don’t have to open your instance to the public. You can restrict it to just people you invite.

Side note: when you’re checking out the most popular instances you’re likely to see a lot of Japanese. This is because Mastodon is really popular in Japan.

What if find a better instance later?

You can move an account between instances. Under “account” on the old instance you tell it about your new one. On the new instance you do the opposite.

More importantly, you don’t have to abandon the history of things you’ve “tooted”. If you want to bring that along, it’s just a matter of exporting them from the old server and importing them into the new one. Instructions are here.

How you use Mastodon

Sending Messages

If you know how to send a tweet on Twitter you know how to send a Toot on Mastodon.

The mechanism is the same as Twitter. Fill in the text field. Press the button to send it. Where the button is, and how it’s labeled depends entirely on if you’re using the web site or one of the many phone clients. You can attach images, and links just like Twitter. The only notable difference is that Mastodon gives you way more text per message.

Finding People to Follow

Every instance has a “local” timeline. This is where choosing an instance becomes important. The “local” timeline is all the stuff that all of those people are saying. This is where you’ll find your first people to follow. Just like when you first started Twitter.

There’s also a “federated” timeline.

The federated timeline is a view of all the public toots your servers knows about from across the whole network (including local ones). The most common reason that something appears in the federated timeline is that someone from your server follows the author of that toot. - joinmastodon.org

Just like Twitter, you look for people talking about things you’re interested in and follow them. Just like Twitter you can search for hashtags.

Just like Twitter there are trending hashtags. Like the federated timeline, these are based on the toots your instance knows about, not all the toots everywhere. So, again it’s important to try and choose an instance with like-minded folks.

Following people by their username

If you have a friend on Mastodon you just plug their username @their_username@their_instance into the search field, go to their profile, and click “follow”.

So What’s Different

There are a few notable differences.

Lots more space to get your thought out:
Mastodon gives you 500 characters per toot. Twitter’s still at 280.

What you see:
There’s your personal timeline (usually labeled “Home”). There’s the local timeline, and there’s the federated timeline. Your personal timeline is conceptually exactly the same as what you normally see on Twitter. The “federated” timeline is more restricted than Twitter’s because it’s just not possible to show you everything. Of course, Twitter’s not showing you “everything” either. And of course, the local timeline I discussed above.

Who sees your messages:
On twitter everyone can theoretically see what you post, but in practice only the people following you are likely to. On Mastodon there’s a very good chance that many of the people on the “local” timeline will see what you post. So, when you’re getting started it’s not like you’re just shouting into a void.

The instance is costing someone money
Twitter pays for itself by showing you ads. There’s no advertising on Mastodon, so someone is paying to host the instance. On instances with a lot of people this can be hundreds or thousands of dollars a month. Even on smaller instances it can be expensive. So, when your server administrators ask for donations, or sets up a Patreon, you should definitely consider helping them out.

No Quote Tweets
I really miss Quote Tweeting. There were so many things I found that I wanted to share with a tiny bit of added commentary. The problem is that this feature regularly gets used for abuse and the spreading of flame wars on Twitter. So, the Mastodon devs have decided to not do it. There’s a long GitHub thread discussing it here, if you care.

Discovery Is Harder
Logically, it shouldn’t be. None of us see all the Tweets on Twitter. We see the tweets of folks we follow, and the stuff they retweet. I think the problem is that most of the people with name recognition, or significant followings, just haven’t embraced the Fediverse yet. I discovered a lot of cool people, by seeing retweets from people I respect, and then seeing what other things that person had to say.

It’s a “chicken and egg” problem. People with notable followings don’t want to loose their audience, so they don’t try embracing a tool where they have no audience. As a result, we don’t have many of those human social hubs, sharing interesting things from many people. So we don’t have as many opportunities to discover random interesting people.

The local and federated timelines help a lot, but right now (2022) the Fediverse isn’t nearly as active as Twitter.

The Network Effect is Real
As noted in the last section, the Fediverse, at least in the US, isn’t nearly as active as Twitter. People don’t want to move to a place where they don’t know anyone. People want others to hear what they have to say. People with something to sell need to talk about it where there are listeners.

The Fediverse is also very resistant to paid advertising, by design. There’s nowhere a big company can go and spend thousands of dollars to put their ad in front of millions of people. So you’ve got no major companies shouting “Follow us on Mastodon!” I really hate ads, but I have to admit that things like that help drive awareness.

In Conclusion

Using Mastodon is very similar to Twitter. The most significant difference is that you need to try and find an instance that’s a good fit for you. This is, admittedly, a big hurdle for new people, but it’s the key to Mastodon not being a dumpster-fire. Each instance is responsible for its own social contract, and moderation.

There are a lot of technical and ease-of-use advantages to centralized systems like Twitter and Facebook, but as we’ve all seen, they’re incapable of good moderation, and what moderation they do practice is very unevenly implemented. Mastodon’s solution isn’t perfect, but it’s way better.

Splitting an org-roam collection

Fri, 28 Jan 2022 00:00:00 +0000

org-roam supports multiple directories and it should work fine if you start that way, but if you’ve already got an org-roam project that you need to split up, it’s a pain in the butt.

Here’s how I managed to divide my org-roam project into multiple directories after much trial and error and googling.

A note before continuing: If you’re googling around for this you’re going to find a bunch of old commands from when people were upgrading from v1 to v2. Many of these won’t work because their names have been changed.

Step 1 config cleanup

Remove these from your init.el (config.el in doom emacs)

 (setq org-roam-directory (file-truename "~/Documents/org-roam"))
 (org-roam-db-autosync-mode)

Setting a default org-roam-directory is just going to cause you headaches and accidentally writing to the wrong place. Leaving the autosync in there will just cause errors when you load.

Step 2 .dir-locals.el

create a .dir-locals.el file with contents like this. It should be in the directory specified by org-roam-directory

 ((nil . ((org-roam-directory . "/absolute/path/to/project")
 │        (org-roam-db-location . "/absolute/path/to/project/org-roam.db"))))
 (org-roam-db-autosync-mode)

Warning: emacs doesn’t actually read this file until you open something in the same directory or one of the subdirectories. This means that until you do that org-roam-directory is either unset, or set to whatever it was last.

So, always start an org-roam editing session by opening one of the files in the project.

Step 3

Copy over the subset of files that you want to be part of this project into the directory alongside the .dir-locals.el (dailies should be in a dailies subfolder).

Make sure you do not have the *.db file from the original project.

Step 4

Open every single one of those files. I tried every relevant command I could find that didn’t invole doing this. None worked.

Evaluate (org-roam-db-sync)

If you get errors about uniqueness constraint then run the following

(org-id-update-id-locations (org-roam-list-files))

Then re-evaluate (org-roam-db-sync)

No, I have no idea how it’s possible that the brand new sqlite database could possibly have uniqueness constraints but somehow this is a thing that happens.

Step 5

Wonder if maybe you should be using org-multi-wiki instead. I know I am…

Months Later…

I really wanted to like org-roam. The pitch is great, but I just kept having database related problems.

In the end I switched to Denote and have been very happy every since. He’s taken a unix style approach of using simple, proven, filesystem based tools, and making something really useful by combining them. Because of what it’s based on it “just works”.

Check out the author’s intro video on YouTube.

If org-roam is working for you, then stick with it. If it starts giving you headaches like it did me, then definitely check out Denote. I think it solves the same problem in a much simpler, and more reliable way.

You've been lied to about the newline character

Tue, 15 Jun 2021 00:00:00 +0000

You’ve been lied to about the Newline Character

The humble newline character: \n.

You’ve seen it in countless code examples. Usually something like

foo\n
bar\n
\n

You look at that and probably think, it represents the end of a line. Or maybe you think it represents the start of a line. If you believe either of those things, I’m sorry to inform you that you’re wrong.

Fortunately, by the end of this post you’ll have a much better mental model of \n.

Please note that this post is extremely pedantic, but so are computers, and in this case it actually makes a practical difference. You’ll need to set aside your language training, and what it means to you, and think like an incredibly dumb and excessively pedantic computer. That’s what we’re giving instructions to as programmers, and that’s where this becomes relevant.

The only accurate way to think about \n is as the boundary between two lines. It exclusively marks the ending of one line, and the beginning of another.

When you open your text editor you see

foo
bar

but that’s not what’s actually stored. The file is a stream of characters: foo\nbar\n. The \n marks the boundary between “lines” that don’t actually exist. There’s also an end of file character but we can ignore that here.

So, let’s logic this out. Our ground truth is the fact that foo with no \n is a perfectly valid line. If \n indicated the start of a new line then 2 things must be true:

lines must start with \n
foo must represent either the middle or end of a line, but not the start or entirety of one.

Since we know that foo is a valid line then both of those must be false. You could argue that computers are making a special exception for the start of a file and have special handling for that situation, but they don’t and that would be way more work than just treating it as a boundary indicator.

If \n indicates the end of a line then the following must be true:

lines must end with \n
foo must represent the start or middle of a line, but not the end or entirety of one.

Again, both statements are false.

There’s also a simple tool to prove that it must be a boundary: the split function. Before we explore that, I want you to think about “splitting” a piece of paper. If you make one cut through a piece of paper you end up with two pieces of paper. Cut it again, and you get three. You always end up with cuts + 1 pieces of paper. “Splitting” a string is the same, or it should be. Some languages have inconsistent behavior around \n.

We’re going to be working with foo\nbar\n\n which most code examples would show you on 3 lines like this:

foo\n
bar\n
\n

While the intent of the \n character may have been to indicate the start of a line (technically it was used to move a print head down a “line” worth of distance), what we actually recorded was a boundary indicator. You see, the above isn’t 3 lines. It’s 4, and here’s the proof.

iex(1)> String.split("foo\nbar\n\n", "\n")
["foo", "bar", "", ""]

Here our string is split on \n into n+1 elements, just like our hypothetical paper. Personally I find it easier to visualize like this:

foo|bar||

The line is a piece of paper and each | is where I’m going to cut with my scissors. Elixir split that string exactly as you’d expect, and gives us four elements.

One of my coworkers (paraphrased) asked how you would differentiate "" from "\n", and "\n\n" if it didn’t do that?

iex(1)> String.split("", "\n")
[""]
iex(2)> String.split("\n", "\n")
["", ""]
iex(3)> String.split("\n\n", "\n")
["", "", ""]

Each \n in the initial string is an indicator of where to cut. No cuts and you still have the whole paper. One cut, and you have two pieces, and so on.

IF \n were truly a start of line (“new line”) character then String.split("\nfoo", "\n") should result in 1 line, because the \n would mean “start a line”, and there’s no second line started with another \n. Thus we have [explicit begin character]foo[implicit end] which gives us only one line. Splitting on \n in that string gives us ["", "foo"] thus proving it’s not an indicator of a line’s start. Or at least, the computer doesn’t think of it as one.

That’s the key here. It’s irrelevant what you or I think it should represent. What’s important, is what it represents to the computer. To the computer, there is no situation in which \n exists and there is only one “line”.

We’re dealing with a legacy term from a time when computers had no screens, that was brought to us by a special gearing from the bar you slapped on a typewriter to shift a roller sideways and rotate it “one line” worth of distance. The “new line” term has persisted, but no longer reflects what’s actually happening.

All of this came about because of very real bug in code I wrote to parse request headers. I knew how to fix the bug, but I couldn’t understand why it was a bug in the first place. This was because I kept stubbornly, and incorrectly, thinking that the following was only three lines, because I’ve always treated it as an “end of line” character.

foo\n
bar\n
\n

The most obvious practical takeaway is that splitting a string, by any means is suddenly going to match up with your expectations if you think of it as a boundary character instead of a “new line” character.

Trollphabet

Tue, 23 Feb 2021 00:00:00 +0000

Once upon a time a group of friends gathered at a restaurant. We passed the time trying to devise the worst phonetic alphabet. One that, when heard, would do the best possible job of not successfully conveying the letters you were trying to communicate. This is what we came up with.

A aye
B bdellium (the b is silent)
C cent
D djin
E eye
F fore
G gnu
H heir
I I
J jicama
K know
L like
M mnemosyne
N no
O oops
P psalm
Q quatar (pronounced kutter)
R really
S sea
T two
U umm
V varies
W why
X xenomorph
Y Yes
Z zero

Example Usage (Say these out loud):

no: “no oops”
hair: “heir aye i really”
salmon: “sea aye like mnomosyne oops no”
rowan oak: “really ooops why eye no oops aye know”
aisle: “aye i sea like eye”

Some of us need bigger text

Fri, 04 Dec 2020 00:00:00 +0000

That sounds pretty obvious. It is pretty obvious. Anyone with any familiarity with older humans knows that they generally have trouble reading small text, or making out fine details. Every drug store has a rack of magnifying glasses. Everyone’s seen an older person doing the thing where they lift up their bifocals and start moving a thing closer and farther with their arm trying to find a spot where it both large enough to be readable but far away enough to be in focus. They’re not the only ones who need bigger text, of course, but they are the ones everyone should be familiar with, and likely has in their lives.

I’m bothering to tell you this, because you, my young friend, with your 20/20 vision, or something close, are building the web sites that I attempt to read, and you’ve forgotten to consider that not everyone has your beautiful and capable eyes.

This post is to give you a glimpse of what the internet looks like for us, & to teach you how to easily see it. Actually fixing the problem is usually quite easy once you can see it. This post won’t be addressing the things you need to do to help users with screen readers, but the techniques I do discuss will help many people who are functionally and legally “blind” but still make use of their screens.

What’s the problem

There are 2 parts to this problem.

The Fundamental Misunderstanding

The biggest, is the fundamental fallacy that the web designer has the final say on how a web page is displayed. They don’t, and this is a good thing. If you choose teeny tiny fonts that look beautiful to you, I can’t read them. If you choose a font with very thin lines, I’m going to still be squinting even when I increase the size. However on the web, the reader has the final say over fonts. We can say “oh, I need it bigger”, or “I like it smaller”, or “I need a font that helps with my dyslexia”. Whatever is comfortable for you is going to be unreadable by some of your visitors, and that’s ok.

The Design Problem

Almost every time I encounter this problem it is the result of a designer trying to put text in a box, but not allowing that box to grow to fit the content. The “box” can take many forms, and is frequently invisible. Sometimes designers allow the boxes to grow to fit the text, but then don’t allow them to re-flow, so they start overlapping each other, or slide off the edge of the screen instead of moving down the page.

Also, I need to specifically call out graphing libraries. Graphing libraries, in general, are terrible about how they handle the text in labels. They fail when it’s too big, or when there’s too much of it. Those same failing result in a product that’s very hostile to people with accessibility needs. In many cases it’s better to just make an image. We can zoom that. Yes, it’ll be terrible for totally blind folks, but most of the time your graph was completely unusable to them anyway.

Some examples:

I count at least 8 different errors in Amazon’s Navigation Bar right now. We’ve got forced box size, poorly handled overflow, assumptions about how tall a font is, and more.

Here’s a pretty typical example of not allowing a box to resize from the State of CSS 2020 web site. In these situations odds seem even that stuff will either be poking out the side like this, or just cut off and unreadable.

From the same site, we have an example of forcing a font size. You can see that regardless of what text size you need (big or small), the graph is imposing its own ideas on what is the “correct” size. The text above the graph, in both images, is the size the browser has been told to render text as. This means that the graph library is likely also overriding the designer’s choice of “correct” size for the page’s text.

The color key in this graph is detached from the normal “flow” of the text and didn’t shift over as the text beside it increased in size.

How to See What We See

“Zoom” is the enemy. Zoom, in its most common form, changes nothing. Your layout looks just as great “zoomed” as it does at the size you designed it at. This is because “zooming” the page is like taking a magnifying glass to it. It’s great for extremely low vision folks, but In the end it doesn’t meaningfully alter anything about it, and makes your stuff so big that much of it falls off the side of my screen.

Many of us don’t want or need your images zoomed. For example: imagine an image of someone holding their credit card out to a store clerk. I don’t need to be able to read the numbers on the card to know that that’s what they’re holding. I can extract all the relevant info from the picture without zooming “oh, it’s an example someone buying something in a store”. Similarly, I don’t want my monitor filled with your “hero image” when I came to read your text.

When a browser forces me to zoom to read the text it also forces me to work in a mode designed for incredibly low vision people (think “legally blind”). It’s great that that’s an option for them, but I just need to not squint at your text.

Here are the settings in Firefox, Chrome, and Safari. Note the “Zoom Text Only” checkbox in Firefox. Chrome doesn’t have this.* This is going to make your life, and mine, much easier. Check this in Firefox can now whack Command + (or Control + on Windows) a bunch to see what your page looks like with a fat font, and then Command + 0 to reset it. In Chrome and Safari Zoom will only magnify the whole page. Sadly Safari has no obvious way to set a default font size, only a minimum. If you want to zoom text only in Safari you have to hold down the option key, and click on the “View” menu. Then you will see “Make text bigger” instead of “Zoom in”**. I am unaware of a way to do this without the mouse.

All three have the ability to set a minimum font size. Firefox hides this under an “Advanced…” button. This is significant for designers, because it means that even if you do a great job and make all your font sizes relative to the browser’s base font size, the browser may still use a lower bound that is higher than you expected.

How to Deal

In general, the solution is to let go of the idea of pixel perfect web sites, and embrace “Responsive Design” and Flexbox layouts. It’s never going to look exactly the same on every computer and OS anyway.

The great thing about “responsive” web sites is that when I jack my font up to huge sizes, they just reset themselves as if i were on a device with a smaller screen, which in a way I am.

The other thing that will dramatically help, is to stop replacing the browser’s widgets with “prettier” CSS + JavaScript versions. Pull-downs and multi-selects are the most common example of this. These custom widgets are rarely designed with accessibility in mind, and frequently need to be tweaked to handle whatever your specific use case is. Those tweaks almost never take accessibility into account, because most developers don’t think about a11y. Firefox, Chrome, and Safari have all done a great job of making sure that their built-in widgets work really well for folks with accessibility needs.

As noted above, graphs are a problem. No-one wants to write their own graphing libraries, and few of the existing ones are good at accessibility. Try them out at varying font sizes and with lots of elements and see what happens. Unfortunately there’s not really a good answer here. Using a graph is frequently the right call, they’re notoriously problematic, and writing your own graphing library is almost always the wrong call.

As far as sticking text in boxes though. That’s not actually a problem. There are lots of good reasons to do it. Nav bars, grouping, highlighting a specific thing… These are all reasonable design decisions. If you need to use a box keep these things in mind:

Make boxes that expand in a controlled manner with the text within them.
If expanding the box isn’t an option, don’t just cut off text and make it impossible to read. Make it obvious that there is text that isn’t currently being displayed, and provide a mechanism to easily read it. For example, have scroll bars appear when contents overflow. They are there to help people read.
Avoid CSS’s overflow: hidden property when dealing with text, unless you provide scroll bars. It almost always results in cutting off the text and leaving people like me unable to read whatever you wanted us to read. text-overflow: ellipsis looks better, but the intended text is still cut off.
if clicking an item causes a sub-menu (or whatever) to be displayed, make sure that that sub-item is anchored to the boxes current location, not some hard-coded number of pixels or em spaces across the page.

Summary

There are millions of folks who have visibility issues, and you’re likely to become one as you age. So, embrace responsive design. Use native widgets, and never try to make “pixel perfect” designs.

If you’ve got more suggestions on how to improve sites for low vision folks please contact me and I’ll add it to this page.

Footnotes:
* Chrome doesn’t have the built-in ability to zoom text only, BUT there is a Zoom Text Only plugin which over 10,000 people have installed. There are probably many thousands of other users who didn’t know this was an option, or weren’t tech savvy enough to even look for something like this.
** Not it is not reasonable to expect anyone to “just know” that holding down the option key when clicking on a menu will change its contents.

Ubiquity Upgrade Fiasco

Fri, 20 Nov 2020 00:00:00 +0000

[⚠️ This is a blow-by-blow ranty post about what happened when Ubiquity screwed up a software upgrade ⚠️]

This morning has been… a journey.

Our Wifi coverage has been kinda 💩 at the new house because there’s way more space between us and the Access Point.

So, let’s just run some ethernet across the floor for now! Should be quick! 🤦🏻‍♀️

We run it into my wife’s iMac. No problem. All good. Fast fast. Another cable, through her office, past front door, into my office, And…. “wait… wtf do i plug this into?”

Flashback to about two weeks ago: When we moved in the Ubiquity setup needed administering because… who knows. It did, and we needed internet, because “duh”. We don’t have a hardware controller (yet) and have to use the stupid Java app, but couldn’t get on the wifi to administer it because it needed administering. So we went with the fastest option, buying an ethernet adapter from Staples down the road, even though that meant another potential exposure incident. We like getting paid and being able to pay our mortgage.

They had two options. A “thunderbolt” adapter and a USB-A adapter. “Thunderbolt” is, of course, a useless term when your goal is to figure out if it will fit into one of the holes in your device. They showed something that MAY have been USB-C and MAY have been the mini-display port shaped thing the older macs had. There was no side-view to confirm. Fortunately I have both options available (yay old computers). We bought both adapters just in case. It turned out to be the old style, which is fine, because that’s where the stupid Java app lived.

Back to today: The “Thunderbolt” adapter is useless for this modern mac which has Thunderbolt, but we had the USB-A adapter. Ethernet to USB-A adapter into USB-A to USB-C adapter into new mac, because Apple cares more about selling you more dongles than a good user experience.

The speed is terrible. Google says “Oh Ethernet->USB-A adapters are crap and max out at 100Gb”. Well that didn’t help at all.

But hey, our friend was kind enough to send us a loaner access point we hadn’t tried plugging in yet because OMG MOVING AND LIFE. So i plug it in.

Now, let’s configure that thing. Boot up the stupid Ubiquity Java app. “Unable to load Java Runtime” …WTF? I booted this like 2 weeks ago and it was fine?! Google says “install java” UGH I’ve avoided that for years, I guess it was running some that came with my mac but… whatever. Fine. I’ll install the latest Java.

[BEGIN tangent] Side note: Oracle’s marketing department has NO fucking clue what Java is because they think this is a reasonable representation of people who download Java and what they’re doing while downloading it. Ignoring the fact that we’re in an industry dominated by white males, no-one is all “doo-de-doo I’m just layin’ here on the floor. I think I’ll download Java. That sounds fun! See how happy I am?” No. No-one is fucking happy to download Java, including Java developers, and I speak from experience here. It’s way less annoying than it was 15 years ago, but it always involves more BS and legalese than it needs to. I’m surprised they didn’t try and trick me into downloading NetBeans. Is that still a thing? [END tangent]

ANYWAY… I download and install Java. I reboot the Ubiquity controller. It has me launch a browser to connect to the local server. All good. All normal.

New UI. ….wtf? New UI that’s all “Hey welcome to Ubiquity!” Hofuck. Not good. “Enter a username and password” [type type] “Nah, that one’s no good” “oh shit.” [reread the instructions and enter my passy for the Ubiquity web site].

There’s a “Or restore from backup” at the bottom, which sounds like a great option right now except that the old UI never told me to make a backup or that that was even a thing it could do.

I forge onward.

You have no devices Connect devices to your network.

At this point I am connected to the internet via the old Access point which is plugged into a Ubiquity switch, which is plugged into a Ubiquity Security Gateway… and on to the internet. ALL THE !@#$!$@ DEVICES ARE CONNECTED!!!!

Now, it turns out this is actually a security feature. The devices that are connected are like “we’re managed by someone else. We ain’t letting you touch us.” That way some random schmoe out on the street can’t take over your network, which is great, if there’s a random schmoe on the street looking to get into your network but pretty fucking terrible when Ubiquity has somehow managed to upgrade your software without telling you and without asking if you wanted to make a !#@$!@ backup first.

Note that this isn’t like a App store app. It has never auto-upgraded behind the scenes in all the years I’ve had it installed (at least that I was aware of) and I definitely haven’t upgraded it in the last couple weeks. Even if I somehow managed to tell it to upgrade, and then completely forgot about it, it should have never actually upgraded because I didn’t have the required Java it needed. This has two separate, and glaringly obvious paths to screwing over the user.

The way to get around this lovely “feature” is to do a hardware reset. To do a hardware reset you need a paperclip.

You know what I don’t happen to have in my possession? A !@$##$@ paperclip. We found a safety pin, but that just stabbed into the plastic button. Eventually we found a teeny-weeny Allen wrench that happened to fit in the hole. Reset it. Software didn’t see it. Nuffin…. Then (despite my having refreshed the page) it suddenly saw it. Said it showed up “4 minutes ago”. 🤦🏻‍♀️

Great, except it’s bypassing the security gateway and just going straight to the internet via our router. Presumably because the security gateway is managed by some “other” network.

Wheee I’m standing naked on the Internet Superhighway!

The next step is to poke every device on our network with the Allen wrench and then go through the steps to recreate the network we had in order to be able to control it because Ubiquity felt like upgrading some software without permession, warning, or any way to transition smoothly.

Except, I can’t do that because you know, work, and meetings over the internet. I sigh and go back to my desk, switch to the wifi that has been functional and really slow, but at least has a hardware firewall.

I can’t connect to the internet. It’s like. “Umm…. urrr…. maybe…. um. I … I think I can see it. It’s so far away though. " I’ve got an RSSI of -73 Db, which is low but should be more functional than it is. I have no idea what RSSI stands for but I understand decibels as they affect radio waves if it gets too quiet you’ve got issues. My computer still says 5 bars of wifi but in practice no web page loads.

The same computer, on the same wifi, on the same access point, going into the same hardware that it’s been in for like two weeks… Turns out the new access point is clobbering the old access point because they’re probably on the same channel because they’re not all being managed in a coordinated manner by the controller. 🤦🏻‍♀️

🔥 FUCK YOU 2020. 🔥

It works in the living room still. I just have to give up my monitor, my keyboard, my camera, and my microphone. But, you know… no biggie. That’s not disruptive.

Maybe I should just consider myself lucky it isn’t all on fire.

At least in the new version of the Unifi Controller it’s all “you want me to do automatic backups?” right at the start, which is great. Would have been great if it did it with the old one too. Would have been better if i also knew where they were. Would have been even better if I didn’t find myself suddenly needing them because some jackwad at Ubiquity thought it’d be a good idea to upgrade my network controller and wipe all my settings without asking!!!

I was actually intending to be productive today. To do a little more work for our client. Really though? All my spoons have been used up on this stupid ass spontaneous “upgrade”.

Oh, and next week we’ll have a hardware controller coming in. If I could have done this in a controlled manner as intended next week, I would have found out there was an ability to backup your settings in the old software, and then restore them to the new hardware.

As an aside: I still think Ubiquity hardware is amazing, and in general their software is pretty damn excellent, and we’re happily throwing more money at them, but this situation still sucks.

[update] The old wifi stopped working in any meaningful way for the 2019 mac. Is usable on the 2013 mac sitting on the same desk.

The Coin Game

Mon, 21 Sep 2020 00:00:00 +0000

The Coin Game is one of the tools I’ve come up with to help myself recognize when I do accomplish something of value. It also helps motivate me to do more.

Boring tasks are hard, especially for ADHD brains. On top of this, when we do actually manage to accomplish something, we don’t give ourselves credit for it. Sometimes it feels like it shouldn’t count because of how long it takes. Sometimes getting it done involved lots of irrelevant tangents, and we “yeah but” all the value away. At the same time, most of us do actually contribute enough value to our employers that they keep us on staff.

The short short version is that you earn a coin every time you deliver a unit of value. Originally the idea was you’d use these coins to “buy” yourself some guilt free break time. After working with this for five months what I’ve come to learn is that the real value of this “game” is the physical evidence that you’ve accomplished something. On days when motivation is lacking, or it feels like you’re just being useless, each coin is proof that you’ve accomplished something of value.

The coins you earn are based on things that you consider valuable about what you do. Working towards these intrinsic (not extrinsic) goals makes all the difference. Every time I earn a coin, I do a happy dance, and get a real sense of accomplishment. “I earned a coin!” Every time I feel like I’m not making any progress I look down and see “Hey, I’ve already delivered x coin(s) worth of value today.”

How it works

Prerequisites:

an idea of what your valuable contributions are
a small stack of coins
2 Post-It™️ note sized pieces of paper.

The key to this is coming up with a list of things you do for your job that constitute “delivering value”. How long it takes you to do the thing is irrelevant. What matters is if it’s actually providing notable value to you and/or your coworkers. This is important because we can’t reward ourselves for doing something valuable if we don’t know what value we provide. This is also going to help us set realistic expectations for ourselves.

In addition to the actions you’ve been hired to perform, think about the actions you take that improve life/work for your coworkers or company in notable ways. These have value too. You may not have been hired to improve that process, or code up some useful utility, but if it makes the lives of you or your coworkers better, you’ve delivered value.

Here are some of my “valuable” things (I’m a programmer):

creating a “Pull Request” for some new functionality or bug fix (a code deliverable)
carefully reviewing and testing a coworker’s Pull Request
implementing non-trivial changes requested by a coworker’s review.
representing our team in some politically important meeting
spending 15 minutes researching, and making a decision that will save us hours / days of frustration going forward.

Once you’ve got an initial list, you’ll need some “coins”. You can use “normal” coins like quarters, but I think it’s better if you can use something “novel”. I 3D printed some “Pirates of the Caribbean” coins. You could grab some tokens from a board game, use foreign currency, or whatever. Most days I deliver 1-3 units of value. I have actually had a 5 coin day and it was kinda mind-blowing.

Next, you’ll need 2 Post-It™️ note size pieces of paper. The first one is “The Bank”. The other one is “Booty!”

Take both of these pieces of paper and place them on your desk. They should be in your normal line of sight, but where they’re not in the way.

At the start of each day you take all your booty and move it back to the Bank. Every time you deliver something of value, you earn a coin and move it from The Bank, to your Booty!.

Each coin is a physical representation your accomplishments. It’s proof that you delivered value. You’ve done your job. Feel free to go go off and replenish your dopamine levels. Doing it without thinking about how you “should be working” is going to help you come back more refreshed, and more capable of earning more coins… er… delivering more value. ;)

Some followup thoughts:

Most days I earn 1-3 coins. That’s 1-3 things units of real value to the company. One coin sounds like very little, but sometimes it just takes a day to get a thing done, and that’s ok. In the past I’ve worked on tasks where I haven’t “delivered” anything for a month, but along the way I finished off a number of sub-tasks. If that happens again, I’ll reward myself for the accomplishments along the way. It’s important to recognize that we are accomplishing things even if they’re not ready to hand off to others.

First Principles & Scheme

Sun, 26 Jul 2020 00:00:00 +0000

(Or, The Value of Working at Lower Levels of Abstraction.)

I’m loving working in Scheme because it forces me to work from First Principles.

There’s a huge value in the convenience functions that most languages wrap around those first principles, but it’s like buying and using a car vs. building the car you’re using.

The latter is more work but you’re going to really understand how that car works and you’re going to have the perfect car for your needs.

Some languages (cars) are built for speed (Rust, Go). Some are built for user happiness (Ruby). Some are built for making a specific task easy (SQL). Each has its pros and cons.

Scheme feels like it’s built to be buildable. It’s the Lego™ set of languages.

Like Lego™ if you want to quickly build some complex thing, it’s going to require a lot more time and effort unless you’ve got some pieces pre-built (by you or others). Like Lego™ there is very little limitation to what you can do with it.

The car you build won’t necessarily be the fastest possible car, but it will be the perfect car for your needs. Imagine making a pick-up truck that lets you safely chain additional truck-beds to it when you have big loads. No-one makes a car/truck like that. They make faster cars. They make better looking cars. They make cars your kids can drive. But they don’t make the perfect car for every use case.

Understanding first principles allows you to create that perfect vehicle for your needs. Most languages are pre-built cars. Some are highly specialized Formula-1 models that will send inexperienced developers hurtling into the wall at high speed. Some are comfortable Honda station wagons that’ll get you to your destination safely. Some are Porche 911’s: fun, relatively safe, go reasonably fast, but they’re terrible for taking the whole family and picking up groceries.

Most of the time, that’s perfect. You get the right kind of car for the type of stuff you’re doing. If you’re writing cutting edge video games it’s probably the Formula-1. It’ll be hard to steer, and easy to crash, but you can go really fast with it. If you’re writing a typical webapp it’ll be the Honda station wagon: safe, easy to drive, san handle a load of unexpected groceries, plenty of service stations.

From a productivity perspective it’s great to be able to hop into a “normal” car and just drive. You don’t have to worry about weather much because it’s got windshield wipers, heater, and AC built in. You just want to get to your destination relatively quickly and comfortably.

But, it’s terrible for ever learning how the car works, or how to make something more appropriate than the car they handed you.

And that brings us back to Lego™ and Scheme. Frankly, they’re both terrible for getting things done quickly if all you have is the raw pile of “Bricks”. But they’re spectacular for learning how to make things, and thus how to make a thing perfectly suited to your current needs.

Once you learn those first principles, AND you’ve chosen a scheme with good libraries,¹ you’re left with a tool for building the perfect thing for your needs.

Scheme is a machine shop with a lathe and a cutter. Scheme + libraries is a machine shop with a lathe, a cutter, a CNC, and all the other machines people built with their machine shops.

Ruby + libraries (for example) is a woodshop with saw, chisel, hammer, and a bunch of useful Jigs built by other woodworkers.

Practical Realities

But.. that’s just a tool shop. I want a tool box 99% of the time

Python is a toolbox. It’s not the fastest & not the best. But it builds pretty quickly 🤷‍♀️

Not saying I wouldn’t learn Scheme. Just prioritizing trade offs. e.g., I learned C++ in 2018 for reasons. - Joshua Kehn

Josh’s got a good point. That type of thinking is embraced by basically every programmer trying to get something built in a timely manner. For example when my coworkers and I sit down to work we either use Ruby + Rails or Elixir + Phoenix. We’re not just working in high level languages, we’re also using libraries that give us skyscraper levels of abstraction. It’s all about using off-the shelf tools that’ll get us to our destination quickly. For us, making reliably things quickly translates either directly, or indirectly into money.

But, some folks who really understood first principles had to spend a lot of time building those abstractions. I’m incredibly grateful to them, but I don’t want to be limited to their abstractions, and I don’t want to be tied to their choice of language to use them.

For example. Let’s take the Maybe Monad. It’s incredibly useful, but Ruby didn’t have that baked in. So some rails developer who understood first principles added the .try method. It took until ~2016 for Ruby to add .dig.

.try and .dig are incredibly useful, but if you didn’t understand the core principles of programming you either wouldn’t think to add them, or you’d implement it in a worse way, because you aren’t aware that there are established and efficient patterns for implementing that stuff.

This brings me back to why I love Scheme. There are geeks who love reading academic and abstract programming guides that have no direct practical bearing on their day job, and critically can actually remember the stuff the next week. Then, there are the rest of us, who don’t remember any of that crap unless we actually use it, repeatedly.

Scheme forces me to use it. Scheme forces me to understand it. Every day I spend programming Scheme I better understand fundamental concepts that give me more options in my day job. Every day I use Scheme I build up a few more abstractions in code that are perfectly suited to my tasks and my way of approaching those tasks.

To put it another way, by having so little baked in, and having such great support for building good things, I’m building my own perfect framework.

Would it have been faster to use Ruby + Sinatra? Absolutely. Would the end result have met my goals as well? Not even remotely. Would I have learned anything along the way? Not a chance.

So, yes, I’m going to reach for Ruby or Elixir in my day job. But for my personal work, I’m going to keep working in Scheme and improving my libraries, and eventually I’ll have my own framework, that is more efficient than Rails or Phoenix for the things I’m trying to accomplish.

Racket and Chicken Scheme both have great collections of pre-built libraries. Racket’s language, and library ecosystem have some of the best documentation available for any language. ↩︎

Scheme Is My Vim

Sun, 26 Jul 2020 00:00:00 +0000

Emacs is arguably the most powerful tool available to the modern programmer. Vim’s pretty close. Both require more effort to learn than say Atom or Sublime Text. But, the additional start-up effort pays off quickly.

Like Scheme, they both suck out-of-the-box. Unaltered they’re both horrible bare-bones skeletons of an editor. Their potential is incredible though. If you’re just going to do something quickly, and never spend the time to customize them, they are a terrible choice.

But, if you’re willing to invest a little time and tweak them to your needs (a macro here, a plugin-there) then you’ll end up with an amazing tool perfectly suited to your brain and your approach to programming.

Watching an experienced Atom / Sublime user with vs. an experienced Emacs / Vim user with a setup customized to their brain is the difference between watching 8 year olds attempting to play Soccer and watching the final match of the World Cup.

Scheme is my Vim. I’m still learning how to customize it, but I can see the possibilities.

Delve RPG Review (not Ironsworn Delve)

Sun, 19 Jul 2020 00:00:00 +0000

There’s a little known RPG called “Delve” that is not to be confused with Ironsworn Delve.

Welcome to Delve You awaken on a beach surrounded by the debris from a wrecked ship, you are not alone as others seem to be also awakening from their ordeal. You had no time to pack and all you have is what is in your pockets or what you can find amongst the wreckage. This begins your adventures on the island of Cragbarren. Delve is a fantasy RPG of discovery and adventure, you are on a lost island with no way to leave. The island is filled with dungeons, ruined cities, old caves, mad mages and monsters, with a lot of opportunity for an awesome GM to create their own.

I was intrigued. I figured it’d be an interesting minimalist system. Players couldn’t have much to work with, having woken up on a beach. The cover made me think there’d be interesting rules regarding how you survived through dangerous caverns and dungeons with no resources. Because of the beach thing I figured it might be some kind of rules plus replay-able adventure module.

The reality was a poorly organized, unedited, unfinished world book with new rules for old ideas, cliché racism and sexism, and old D&D monsters. I see no reason for anyone to buy this.

Summary

You awaken on a beach surrounded by the debris from a wrecked ship

There’s a quick little loot table to see what you start with. Next you find some caves which you enter for no apparent reason. Here players will have to contend with rules tracking how long their light sources will last.

Eventually there’s a goblin camp, light at the end of the tunnel and a ticket booth with a bored guy who congratulates you on making it past the goblins and tells you there’s a town down the road.

Everyone who washes up on this island comes through those caves. The goblins occasionally attempt to raid the town and are easily repelled. For some reason the goblins don’t bother to eat the guy at the ticket booth, and despite them regularly killing shipwreck survivors and being a nuisance the town doesn’t seem inclined to do anything about them.

When you get to town you learn that there’s no money here. Everything is barter, but in order to make the game a bit easier every item has an abstract numerical value. Some might call it a “price” if “money” were a thing here.

Despite the marketing of washing up on a deserted island, you very quickly find a town with a tavern, a blacksmith / weapon-smith / armor-smith, a merchant, mage’s guild with many members, and everything else you might need to equip yourself for adventure.

As far as the world-book portion of this, there’s a good town (as in not evil) populated with people who’ve washed ashore called “Wreck Haven” It is every medium sized town in every fantasy RPG, but with three detailed NPCs, each with a 1 page description.

There’s also a bad town (evil), the “City of Stench” which has a history multiple centuries old, and known to the old people of Wreck Haven despite them only having been here for 100 years.

If you spoke to the oldest person on Cragbarren they would tell you that the city became corrupt, that the ground swallowed up the buildings and churches and then spewed out death, that deep beneath the island evil dwells and it manifested itself by rupturing and creating the rotten and pungent orifice that now dominates the city, a running pustule of rot and evil.

It is of course, infested with undead, and ruled by a demon. Thus your adventurers who have no possessions, must go there, and risk their lives because…. 🤷‍♀️reasons. There are some details, a map of the requisite underground portion, and a loot table for this city.

Then there are lots of monsters taken directly from D&D via the Open Gaming License: Ankheg, Basilisk, Blink Hound, etc. If there’s an original monster I missed it.

Details

Organization

Good organization is critical to an RPG rule-book. Essentially no-one ever remembers all the rules, and you’re going to need to grab it and quickly find the answer to how Combat works (or whatever).

Here all the reference information is presented inline with a running narration of gameplay. You learn about “Hunger” as you wander the beach. You learn about combat when you encounter your first creature. You learn that you can cast spells and that they cost magic points, at this time too, but not what spells are available, or how many points you have. That’s…

There’s no index or chapter markings for any of this. You just have to remember that it’s somewhere in “Into the Caves”. Technically there’s a “Rules Summary” on page 58 (you just have to remember this). It’s not all the rules that have been presented so far or any that are yet to come, and it doesn’t tell you what page to go look at to find the details on anything.

The armor and weapons tables are hidden in the chapter of the city / town of “Wreck Haven”. You can find them after the page detailing the blacksmith NPC “Er-varin” and before the page describing the flotsam merchant named “Flotsmam”. The table of standard gear in between description of Flotsam and the Mages Guild.

Racism & Sexism

Racism in RPGs is no better than racism in real life. If the dwarves rise up in your game world and start committing genocide or something similarly evil, it’s reasonable for everyone else to distrust them. In Delve though dwarves “…have always been warlike, considered untrustworthy in matters of business, and drunks.”

Sorry, did you want to play an honorable dwarf? Tough shit, everyone’s going to treat you like an untrustworthy drunk. And every species is like this except the Half-elves. These quotes are all taken straight from the book:

Elves are often seen as haughty, adventurous, jaded, cruel and pompous all of which are justified and are opinions

Halflings had for years been seen as small communities of happy and social people… but that is all just a façade. Halflings are thieves, and not only thieves but also assassins, spies and murderers.

Half orcs have been known to attempt to remove their teeth, lighten their skin and even slice their own faces in order to become less orc like…To be a half orc is to be hated, untrusted, despised and rejected

But humans are tenacious and will turn a blind eye to the suffering and death of others, even their own kind just to line the pockets of the few.

The half-orcs are especially depressing. Everyone hates you so much that you despise your own skin and try to pretend you’re another species.

Why would anyone want to play in a world where before you even start, everyone hates you and has terrible preconceptions about you based on your race. No matter what you do, most of society is going to be prejudiced against you for the rest of your life.

Don’t worry though, we’re not done. In addition to the baked-in racism we also have baked in sexism

Witches can be seen differently from the Mage within society, seen as evil or less powerful many are viewed as the mad old woman, or the strange hermit. They spend a lot of time gathering herbs and fungi for their brews.

Yeah that’s right ladies; if you have any power they’ll see you as evil, less powerful than the men, or mad, and you’re expected to spend your life “gathering herbs” and cooking potions while the men go off and do manly things.

Rules

There are rules for all sorts of things: parrying, attacking from horseback, how long light sources last, hunger, called shots, firing into melee, etc. It’s simultaneously more than most players want to bother with and not enough to satisfy those who would crave a “realistic simulation”. They’re also very difficult to find in the book.

Everything is percentage based, which you’d think might make things easier, because you’re just rolling two d10s all the time, and seeing if you beat the odds, but what percentage you have to beat is constantly changing based on circumstances, and may frequently involve summing three things and subtracting from your base percentage, or whatever. As a bonus, unlike d20 systems, where you roll and immediately know what number you got, now every roll you make now involves figuring out which of the two die that just rolled across the table is the 10s and which is the 1s, then doing the math to add them up.

I saw nothing in the rules that was innovative, new, or even a new twist on an old idea, other than the fact that you can only level in a Tavern.

Delvers can only level up in a tavern, they cannot level up whilst adventuring and I recommend that GMs wait until they reach a tavern before handing out experience points.

There’s only one tavern on the island though, so players best hope it doesn’t burn down.

Magic

It’s a fairly standard manna point magic system. The two magic classes are “Witches” and “Mages” There is a strong implication that witches are female and mages are men, but it’s not explicitly stated (see sexism above).

You learn spells via the conveniently located and surprisingly well staffed mages guild with its stores selling potions and magic items and library… in a small town on an island comprised entirely of shipwrecked people and their offspring.

Spells are typically once sentence long and inconsistent. Some ranged spells mention how many feet they can go. Some don’t. They’re presented in two columns of center aligned text for no apparent reason. They’re located at the end of the chapter on Wreck Haven between the information on the Mages Guild and the City of Stench.

Conclusion

Literally the only good thing I have to say about this book is that I liked the description of the three NPCs. Every time I think about the rest, I’m pissed off by the blatant racism and sexism. The whole shipwreck thing is pointless because other than an excuse for starting with nothing you promptly find yourself in a well stocked town with every convenience. Magic potions, magic items. “Anything can be found at Flotsam with rarer items appearing on a d6 roll of 4,5 or 6.” If it’s not there today, just wait. No matter how rare it is you’ve got a 50% chance it’ll wash up shortly.

The organization of the book is frustrating at best. The drawings are cobbled together from a variety of artists with inconsistent styles. The monsters are literally taken straight from D&D with minor tweaks for this game system.

There’s no concept of alignment, which is fine, because everyone is a fucking racist who hates everyone who doesn’t look like them so it goes without saying that essentially everyone is Lawful Evil. And that’s ok, because the dwarves are all alcoholics, and the halflings are all murders, and the half-orcs hate their bodes, and and and….

Please don’t buy this.

Covid Decision Flowchart

Sun, 12 Jul 2020 00:00:00 +0000

There are a number of people who want to stay safe during the COVID-19 pandemic, but have found themselves making questionable decisions, because they’ve become acclimatized to it, and because they want to believe that their friends are healthy, because they look healthy, and reason that “of course, those friends are responsible, and I’m responsible, so it should be safe to get together and do something.”

Friends and family are the big problem. We need them. We’re social creatures. The thing is, if your friends choose to get together with you in a non-socially distanced way, it proves that they aren’t being careful, and then you have to wonder about all the other not-careful people they’ve been in contact with, and the people they’ve been in contact with and on and on.

When you come close to another human, you’re not just interacting with their germs and viruses. You’re interacting with the germs and viruses they’ve acquired from their friends, and their friends friends and…

It’s really hard to see the danger. It’s part of what’s helped our species survive. Minimizing danger is what allowed our ancient forefathers to go out and try to stab a mastodon with a spear.

So, here’s a flowchart to help you decide if going out, or getting together with others is a reasonable, logical, decision, and not just an emotional want.

Hating Email, and Loving Hey

Fri, 26 Jun 2020 00:00:00 +0000

I… really hate email.

By the time I left my last company I had successfully trained everyone around me to stop sending me email, or at least not expect me to have seen anything they sent me. My friends are similarly trained.

The thing is, I don’t actually hate email.

I hate traditional email clients and the bullshit usage patterns the force on us, and I hate the bullshit way most employers use email.

I’m _loving _Hey, because it solves the first problem.

Let me explain. I apologize, that this is a little ranty, but I’ve been dealing with this BS for decades and it negatively affected my ability to communicate with friends, family, and coworkers.

Here’s where we’re starting from.

Essentially every web site I have an account on, or buy something from sends me email. I want less than 1% of it. Marathon sports just let me know that “Sketchers Performance Footwear is Here!” and that “Dad Deserves the best!”.

I also get “recruiter spam” and other solicitations that may be “personalized” for me and not directly trying to sell me crap and thus doesn’t count as “spam” for the purposes of automatic filtering. I want none of it. “Kay! We have an urgent need for a developer with 5 years of [tech that’s not on my resume]!” “Hey masukomi, we can apply [buzzword] ’technology’ to masukomi.org to boost your [other buzzword]”

My inbox is MY inbox. It’s not their delivery basket. No-one should get to say what shows up in my inbox but me. I’m the one who has to read it. They don’t get to decide what I have to read.

Make no mistake, you have to read everything in your inbox if you want a clue what’s there. You may just be reading the subject line, but you’ve still read it. You still need to decide “do I want to open this?”. I do not want to be wasting my mental bandwidth and limited decision making power on something that I never asked for and don’t want.

So, the starting point, the baseline, of this discussion for most folks is an inbox that is filled with thousands of emails from people trying to sell them stuff or get them to do something they don’t want to do. Somewhere in that torrent are a couple emails from friends or family. Maybe. Hard to tell.

I declared email bankruptcy in May of 2018. Since then I’ve unsubscribed from dozens of mailing lists. It’s June of 2020. I have just under twenty two thousand non-spam emails. Essentially none of them are from anyone I care about. I’ve seen maybe 1% of those that are from people I care about. That’s roughly 34 emails a day. I think my friends, so thoroughly trained to not bother sending me email maybe send me 1 email a month…maaaybe. I hear about them after the fact: “oh, you don’t know what’s going on because it was in an email thread.” Let’s say they have actually sent me one email per month. That’s 0.09615% of my email that 1 actually care about. Let’s add in the notes from my credit cards when there’s a suspicious or notable charge. Let’s be generous. Let’s say that those increase the email worth having my an order of magnitude. Now 0.9% of my email is worth having.

ZERO POINT NINE PERCENT of my email is worth having.

Or, to put it another way, if I bothered to actually address my email 99.1% of that time would be spent looking at things I don’t want to see, most of which actively annoy me.

And we still haven’t touched on the work email, which honestly, isn’t much better, what with the email threads you don’t need to be CCd on, the digests from software you’re forced to use, and literally thousands of notifications and alerts you don’t need (if you’re a developer). Alert Fatige Anyone?

So, how does Hey help?

The biggest difference is that, no-one gets to put anything in my inbox without me approving them. Everything goes into the “screener” where I yes/no every sender. So, yes I have to deal with emails from them, but only once. Not every time they try.

This is a bit more up-front work. For each new sender I have to decide if i want it, and if I want it in my “Imbox”, or in one of the other 2 bins. But this 1 time per sender task means that my “Imbox” is going to only have things I actually want to see in it.

I’ve heard people argue that they want this to be automatically done. That they like how Google automatically shoves things into “Promotions” or “Updates”. Well, Google does have the best AI in the business, and incredible quantities of training data. But, that brought me from 26,000 emails down to 6,500 so I paid SaneBox to bring it down to 2,100. My current Inbox in GMail is displaying a full page of emails (and another one if I scroll down) with literally none that I actually want in my Inbox. So, even with the best AI in the business the results are still terrible. There’s still way too much for me to deal with that I shouldn’t have to deal with.

Filing by sender solves this. This isn’t perfect. Because if some company uses the same email address for their billing as their newsletter then you either don’t see the billing promptly or you always see the newsletter you don’t care much about.

I’m ok with this. The reason I’m ok with this is that I don’t want the !@#$ newsletter anyway. And yes, some of them are actually worth reading, but 99.999% of the time my time would be better spent reading a book, or writing some code, or petting my animals, or simply staring out the window and breathing for a minute. Newsletters are, in general, the high calorie, nutrition free food of the internet.

The second biggest difference is that notifications are off by default. My phone isn’t pinging me about all the 33 emails a day that I actively don’t want. Of course, because of the screener there isn’t much in my inbox anyway. Yes yes, I’m sure some of you are yelling that it isn’t going to ping me about things auto-filed to “Promotions”. It doesn’t matter. Every notification I do get is still something I don’t want. There are a lot of emails that are important for me to see but are not important for me to be notified about. I just got an alert from Gmail that Hipstamatic wants me to buy some new filters in their app. Yay. I don’t even know why I was on that mailing list.

Those two things remove the vast majority of my problems with email.

On top of fixing most of my problems with email by implementing two very old ideas, they then went and made hundreds of tiny usability changes to how you interact with your email. Some of them like being able to “Read together” or addressing all your “Reply Later"s in one screen are dramatic and awesome. Some of them, like always showing tiny hints about keyboard shortcuts so that you learn them as you go, or having a button available where you can see the list, are tiny and awesome.

The privacy improvements are pretty sweet too.

Is Hey perfect?

Nope. But, for me it’s a thousand times better than everything else. I’m happily throwing my money at them because, I don’t really want to build an email client despite how many times I’ve been tempted.

I’m happy so far, but what I’m really hoping is that this is the kick-in-the-pants developers need to get off their asses and rethink email. Not, make yet another client that looks like every other email client but “lets me treat my email like a todo-list” or whatever bullshit continues to put the senders desires before mine.

I want more people to write clients that say “Hey, you know what? This is your inbox. It’s not about what they want. It’s about what you need. It’s not about seeing all their crap. It’s about not missing the things that are important to you, and not wasting your time.”

D&D vs. The Fantasy Trip

Sun, 23 Feb 2020 00:00:00 +0000

In 1987 I was a sophomore in High School. A teacher had an after-school class where he taught us to play Melee and Wizards. Our characters battled each other with spells and weapons on a wide open hex grid. Little cardboard punch-outs with terrible drawings marked our places on the map.

I loved it.

Decades later, as an adult, I payed someone $40 US for them, because I kept thinking about them. Together Melee and Wizards made up a combat system. The Fantasy Trip was the Role playing system built around it to compete with D&D.

I never got to play them with anyone, but then The Fantasy Trip’s Kickstarter came out and I threw my money at it. Fun combat system combined with the joy of D&D Role Playing?! Sign me up!

Now I have it, and I’m trying to figure out if I should use it in my next campaign.

This is a long post. There’s a summary of my thoughts at the bottom if you don’t have time for it all.

Comparing and Contrasting

So, what’s the difference? Why choose one over the other? The way I see it there are four notably different aspects. I’m going to cover each below. There will be a lot of simplification.

Character Stats & Rolls
Combat
Healing
Magic
Leveling
Source Material

Before that, I’d like to put an idea in your head. It’s a bit of an oversimplification, but I think it works. In D&D adventurers go from being slightly gifted individuals to demigods of incredible power. In TFT adventurers go from being slightly gifted individuals to exceptionally skilled individuals. It’s more of an “athletic child” to “Olympic Track and Field gold medalist” kind of scale.

Quick terminology:

TFT: The Fantasy Trip
D&D: Dungeons and Dragons
DM: Dungeon Master. The person running the game. In TFT they’re Game Masters. I’ll use DM throughout for simplicity.

Character Stats, Creation, & Rolls

The Fantasy Trip

In The Fantasy Trip you have 3 stats:

Strength: health level & literal strength
Dexterity: how easy it is to hit or dodge things & literal dexterity
Intelligence: how smart you are & how powerful the spells you can cast are.

It only uses a D6 (six sided die). You almost always roll 3 of them. You’re also always trying to roll under whatever your stat is.

There is also a concept of “adjusted dexterity” (adjDX). It’s a bit fluid and varies based on what you’re wearing and relative positioning of enemies.

When you need players to roll for something they know they’re going to need 3 dice, and they’re all going to be D6s. You probably won’t have to tell them which stat to roll against either.

If I said “roll to see if you can avoid the falling rock” it’s pretty obvious that you’d be rolling against your Dexterity. You’d also roll 3d6 because that’s what you always roll.

This allows for much more free-form interactions. I don’t have to tell you to roll a specific check for something. A player can say “do they have a heartbeat?” and the DM can respond with “roll to find out!” I don’t have to tell them which stat. Intelligence is the obvious choice, as Dexterity was for avoiding a falling rock.

To summarize:

3 stats that are extremely easy to intuit
1 kind of die and almost always rolling 3 of it.

D&D

In D&D you have 6 stats. Each one has a “modifier” which is relative to how much above or below 10 it is. For every two points you add ( or subtract ) 2. I’m not going to go into each one because, there’s just too much.

Each of the six stats has an associated “Saving Throw”. Rolling for a “Strength Saving Throw” for example is a D20 + your Strength Modifier.

There are 18 “Skills”. Each skill associated with one of the 6 stats, and it’s not obvious which one. Rolling for one of these skills uses a D20 + the modifier of the associated stat. Different races might give you a bonus to certain Skill Checks.

Characters are also “proficient” in some skills. If you are proficient in the skill the DM asks for then you also add your “proficiency bonus”.

Your “proficiency bonus” starts at 2 and increases by one, at levels 5, 9, 13, and 17.

When the DM asks for a skill check or a saving through it’s always a D20, but players have six different dice in front of them. I can not tell you how many times I’ve seen players ask “what do I roll?” even many many sessions into their 1st campaign.

Depending on the class you choose you have a different Hit die. Usually a D8 or D6. Each time you level you roll it again, and add your constitution modifier to see how many Hit Points you have.

When a player asks “Do they have a pulse?” The DM needs to instruct them to “Roll a medicine check!”. It’s not obvious to the player what check to roll otherwise. “Investigation” seems reasonable, as do “Perception” and “Survival”. Even “Intelligence” isn’t a crazy idea.

New players will usually respond with “what do I roll?” and then “what do I add to that?” They’re not sure what Stat Modifier it’s associated with. They don’t know if they’re Proficient in it or not, or what they have to add if they are Proficient.

To summarize:

6 Stats
6 Modifiers (one per stat)
6 Saving throws (one per stat)
1 proficiency modifier
18 skills (some you’re proficient in, some you’re not, each associated with a non-obvious skill)
6 different kinds of dice

Backgrounds

Both systems encourage players to create interesting backgrounds for their characters. You want them to feel like living beings. Players know how to roll play a situation, because they know what this character’s life has been like.

D&D’s 5th edition has worked hard to make it easy for players to create rich backstories for their characters. It is spectacular for players who are new to Role Playing or aren’t very good about coming up with stuff like that. They also keep adding new background creation tools.

The Fantasy Trip is, in essence, a reprint of a book from the 80s, where they hadn’t figured out how to do this well.

Races

In TFT you have humans, elves, dwarves halflings, orcs, goblins. This affects your starting stats, but not much else.

In D&D you have those, and many more. Different races have different starting bonuses, and abilities. More importantly, they have different histories, personalities, and places within the social fabric.

With almost every new book D&D introduces new playable races. Each new race helps people explore and express different aspects of their personality. It helps them to find their place in the wide world of role playing.

Aside

Wizards of the Coast deserves tremendous praise. Every image they provide is another starting point for your imagination. They’ve made sure to show women and people of color as player characters in these scenes. They’ve been working very hard to make D&D into a space where everyone is encouraged to participate. We need so much more of this.

Historical Note

Back in the late seventies, when The Fantasy Trip was first published, only the six-sided die was easy to acquire. Steve Jackson described it best in _The Space Game_r #10 (Feb-Mar 1977) where he wrote:

“The special dice are expensive and sometimes hard to find; it is monumentally aggravating, for instance, to purchase D&D and then find you can’t play without laying out more money and waiting another couple of weeks for dice.

Hexagram Issue #3

Combat

When watching people play, the most visible difference between TFT and D&D is how they handle combat. TFT’s rules originally came in little rules pamphlets for Melee and Wizard. Those pamphlets are really small. You could probably print all the combat instructions on two sides of an 8 1/2“ x 11” sheet. D&D’s rules come in a book about ~200 pages long, but it turns out, very few of those pages are actually combat rules. I wanted to get a sense for the relative complexity of combat, so I flow charted them both.

The details aren’t important at the moment, and I’ve made this image low-rez so that we don’t get caught up in them. What’s important in this image is the relative complexity of each.

So, is TFT harder / more complex? Well. Yes?… and no.

D&D

In D&D everything about combat is simplified to the point of being hand-wavey. From the standpoint of the rules, everyone is just a floating blob of Hit Points. Do you want to stab someone in the back while they were looking the other way? Not gonna happen. D&D doesn’t care what way they’re facing. Is your friend between you and the enemy while you shoot that arrow? No worries, you literally can’t hit them. The D&D fans are yelling about “natural 1” now, but nothing in the rules says “and thus shalt thou hit thine friend!” It’s all the DM improvising. Improv like that is great. It is the heart of great RPG, but at the same time it feels like it’s verging closer to a simple board game.

“Hold on, lemme dig through my backpack. I know I’ve got something I can use… just… I think it’s under my bedroll. Yeah I know we were trying to kill each other but gimme a sec… sheesh!”

TFT

TFT doesn’t get crazy nit-picky about switching weapons but it does have a concept of a “readied” weapon. So, having a dagger on you doesn’t mean you’re constantly able to stab someone with it.

In its defense D&D, only lets you switch weapons without dropping if you spend your action doing it. There’s never a movement penalty, but most DMs just say “sure, grab & stow!” D&D encourages this attitude of making it simple for the players. TFT is striving for simple but trying to balance that with keeping things a bit more plausible.

In TFT if you’re shooting an arrow past your friend, you might hit them. With a spear, you’re more likely to hit from 10’ away than you are from 20’ away. When someone’s looking in the opposite direction it’s easier to stab them.

TFT also has some optional rules about “aimed shots” and “crippling hits”. For example, you could attempt to cut off someone’s leg and then they wouldn’t be able to walk around. In D&D it doesn’t matter how much damage you do to someone or where. They are never affected by it until they’re dead.

Healing

I’ll cover magical healing in a minute, but what about regular “natural” healing?

D&D

D&D wants players to heal up and be ready for whatever comes next regardless of what’s happened to them.

In D&D you have “Hit Dice”. You get 1 per level.

A short rest is a period of downtime, at least 1 hour long, during which a character does nothing more strenuous than eating, drinking, reading, and tending to wounds.
A character can spend one or more Hit Dice at the end of a short rest, up to the character’s maximum number of Hit Dice… For each Hit Die spent in this way, the player rolls the die and adds the character’s Constitution modifier to it.

So, in theory, you could heal any amount of damage during a short rest. You can take many of these during a day, but you can never roll more than your total hit dice during the day. If you have 4, rolling 2 now and 2 later is fine.

And then there’s the “long rest”…

At the end of a long rest, a character regains all lost hit points. The character also regains spent Hit Dice, up to a number of dice equal to half of the character’s total number of them (minimum of one die).

A good night’s sleep heals all wounds. Literally.

TFT

The Fantasy Trip takes a somewhat more realistic approach.

Physical damage can be healed in 3 ways:

Someone with some First-Aid training (a “Physicker”) can give you First Aid, and heal 2 points of damage. 3 points if they’ve got advanced training (a “Master Physicker”). It takes five minutes to do, so it won’t happen in a battle.
Potions that heal 1 point of damage only.
Sitting around and healing at a rate of 1 point a day.

Magical Healing

D&D has many magical healing options. The more powerful spells require touch, and the stronger potions are fairly expensive. Many of the classes have access to minor healing abilities. To put it another way, while death is always a possibility, healing is relatively easy to come by.

In TFT there are healing potions, but they they cost $150 and only heal one point. Their biggest value is preventing someone who just dropped to 0 points from dying.

There are no permanent healing spells. This probably seems crazy to most D&D players. In 2019 Steve Jackson (TFT’s creator) proposed one on their forum and the resulting conversation says a lot about playing TFT.

I thought this quote summed it up well:

Having played TFT for years with no healing spells, rare fragile healing potions that cost $100 for one dose that heals one point of damage, and having to devise ways to survive years of adventure anyway (making sure you have enough people and a physicker, and/or finding safe places to heal and actually resting), I still feel your original design was best.
It makes injury significant. There are ways to survive and triumph despite no healing spells, and I still find that more interesting and satisfying than the typical alternative of easy healing, which I find tends to make injuries less relevant, and actually tends to up the stakes of combat as players expect to be able to fight people and get hurt but then heal up relatively quickly for no really serious consequence. – Skarg

Healing Consequences on Gameplay

The consequences on gameplay are huge. In TFT characters typically have less than 40 points total spread over 3 stats while creatures roll at least 1d6 per hit. Damage is mitigated by armor and such, but when you’ve got maybe 15 or less Strength points to begin with, every point counts.

In D&D players are self-regenerating killing machines. They start with ~8 HP and can end up with well over 100 as they level. As long as they can get a rest in between fights they can keep going.

Barely survived a fight? There really aren’t any consequences if you can get a night’s rest.

It TFT players have to be much more careful, or they need to pull a cart filled with carefully protected potion bottles behind them. ;)

I don’t think either is better. It’s more a question of what feels right for your campaign and / or your players. That being said, making a long “dungeon crawl” survivable is going to take a lot more work on the DMs part in TFT.

Magic

Magic in The Fantasy Trip

I love the idea behind how magic works in TFT. There your magical forces comes from your physical health. When you cast a spell it saps your strength. Strength (Hit Points) lost via magic regenerate at 1 point per 15 minutes (notably faster than physical damage). You can kill yourself by casting too many spells.

More powerful spells require more strength. So you can’t save up your really powerful spells for the end because you won’t be able to power them.

If you read the Dragonlance Chronicles, this is very much like Raistlin. He’d cast a powerful spell and then become weak and wracked by coughing fits.

As you grow more powerful you can store up “mana” in your staff and use that to power your spells instead of your own strength. However, it caps out at the same level as your IQ, (maybe 20 points max) and you have to spend your experience points to make it instead of leveling your stats.

There’s a catch though. Excluding what power you can store in your staff, you can’t store very much. You need IQ to be able to cast powerful spells, but you need Strength to be able to survive the spells you cast, and the enemies that you encounter.

After you use up you staff’s mana each spell will drain you physically. Meaning, every spell you cast, also makes you easier to kill. It doesn’t matter how healthy you are at the start of the fight. Every casting brings you closer to death.

There are balances though. Every wizard is also an enchanter, infusing magical items with spells they know in their downtime. The process takes weeks, or months, and frequently require the help of other wizards. Magical items can enable Wizards to do things that might otherwise be impossible during combat, but many still drain your health. So, no free fireballs.

Unlike D&D everyone who casts has access to the same pools of spells, and can all create new ones, and can enchant items. The only limitation is their intelligence and access to strength for powerful spells. Everyone can cast a spell in theory, but Wizards study for years to be able to learn spells more efficiently.

There are roughly 250 spells to choose from and creating your own is something explicitly mentioned in the rule book. You memorize new spells by spending experience points.

Spells are typically very simple. They come in 4 flavors:

Missile: used to damage someone (roll to hit)
Thrown: act on a creature but don’t hurt it.
Creation: bring something into being (images, illusion, etc).
Special: anything else (Teleportation, Dazzle, etc.)

Here’s a complete spell description from the book.

IQ 10: Dispel Missiles (T) Dispels any missile spells (or missile or thrown weapons) aimed at the spell’s subject. They simply vanish. Cost: 1 ST to cast, 1 to continue.

That, is it. The “(T)” means it’s a “thrown” spell.

Magic in D&D

In D&D there’s a limit to what you can cast, but doesn’t hurt you. Casting doesn’t make you easier to kill. Some classes have fewer spells, but get them back after a Short Rest. Some have more spells, and flexibility in spell choice, but only get them back after a Long Rest. Some spells can be cast as a “ritual” which takes longer but doesn’t use up one of your available casting “slots”.

What class you are affects what spells you have access to, and how many of them you can cast at each level. While you can create new spells it’s not generally done, and enchanting items is something only specific classes can do, and it’s way more limited than in TFT. That being said, there are a lot of spells to choose from.

The fact that it’s not tied to your health means that you can save your really powerful spells for the end… “just in case”. The fact that they’re tied to neither intelligence, nor health means that as you level you will eventually become a demigod of power.

Spells can be created by players but generally are not. That’s not a big deal though because there are literally over 500 to choose from.

Spells have 10 aspects each:

Level
Casting time
Duration
Range / Area (can be a distance or a volumetric shape of a specified size)
Components (verbal, somatic, and/or material)
School (mostly ignored)
Attack / Save (is a roll required? if so, who rolls?)
Damage / Effect (what kind, how many dice are rolled, what kind of dice, any plusses)
Classes that can cast it.
Info on how the spell changes (or not) as you level.

The Components are great for role play, but are frequently ignored in favor of just using a “focus”.

Leveling

In both systems you gain Experience Points (XP) as you play.

In D&D these experience points eventually cross a threshold and your character levels up. Every time you level you get more Hit Points. Melee classes get more abilities. Casting classes get more spells and access to more powerful spells. Each subsequent level requires more experience points to reach.

In TFT there are no levels. You spend your experience points to improve your basic stats, to learn new spells and talents, for gold, for a Lesser Wish spell, or to improve your magic staff’s Mana stat. Each stat increase requires more and more XP to reach, and the cost is based on your total stats.

D&D lets you choose from carefully curated lists that are relevant to the class you chose. Some levels don’t get you much. Some levels are an exciting set of decisions “ooh I could take this spell, or that one, but ….which?!”

TFT is more “With study and practice you can be whatever you want to be!” Players will save up for the thing they’ve been looking forward to, or the thing they really “need”.

Source Material

This is a very unfair comparison.

TFT

TFT is, as I mentioned, basically a reprint of a book from the 80s. In that time Wizards of the Coast has been iterating and perfecting what they do. In addition to the time to do this their recent popularity has given the financial resources to create more content. Steve Jackson Games only recently reacquired the rights to TFT and hasn’t had a chance to create much of anything new for it.

If we’re lucky folks will start playing TFT and demanding more from its creators.

As it stands though… There are some spells. There are some monsters. The choices pale in comparison.

Some monsters have stats. Some don’t. None of them have stats organized in a consistent way. There is no sense of relative difficulty between them. Many don’t have images, and the ones that do tend to be very mediocre quality black and white (literally black, and white, not grayscale). The descriptions are decent.

Planning an encounter is frustrating and difficult for people who aren’t intimately familiar with the game.

There are some “pre-programmed adventures” (as there were called) but they’re short. The one that comes with it is 24 pages. Many are much shorter. By comparison The Curse of Strahd for D&D is a 256 page hard cover book with many beautiful illustrations and maps.

D&D

D&D has tons of source material. It is gorgeous. It is well organized. You don’t have to come up with everything from scratch. You don’t have to tweak everything to make it work. Tons of monsters to spark your imagination. Lots of “modules” (pre-planned adventures) to steal ideas from, or send your players on if you don’t have the time or inclination to create one yourself. There are short community ones, and epic ones from Wizards like the The Curse of Strahd.

Everything about spells and monsters is more complex, but it is presented with such consistency, and predictability, and structured “stat blocks” that it doesn’t matter.

D&D also has an incredible wealth of high quality fan content. I think much of this can be attributed to their Open Game License. This basically says you can include lots of their spells, and creatures, and other intellectual property in your content and software, even if you’re selling it as long as you don’t try and claim it’s yours. As a result, people can create new adventures for you without having to create all new monsters or spells.

Summary

I love the simplicity of TFT’s stat system. While I can see the argument that it’s too simple, D&D’s stats and rolling things are way too complex. I realize that 5e is a dramatic simplification from 4e but that doesn’t change the fact that it’s way more complex. There are way too many complications when it comes to answering the question of “what should I roll?” and “what do I add to that?”

I love how much more plausible combat feels in TFT. D&D has brushed over complications like shooting through spaces occupied by your friends. It ignores how it should be easier to stab someone that’s facing away from you. Accounting for that in TFT adds complication, but D&D isn’t much better. It may actually be worse. The simple case is easy in both. D&D can get very complex when you have multiple buffs, and debuffs, from friends and enemies, each potentially involving different dice.

I really like D&D’s use of different polyhedral dice. They’re just more fun. Having all those “choices” may add confusion for new users, but combat is “roll a d20” and then find and roll the right dice for damage. I think the confusion is more tied to the myriad stats and modifiers. The lack of confidence from that bleeds over into combat.

I want the simplicity of being able to say “roll to find out” and knowing that a TFT player will have confidence in what to roll, and against which stat. D&D requires more explicit telling, and more calculating by the player who is rolling.

I’m unsure about the fragility and lack of healing in TFT. My gut says that it would encourage DMs to create small encounters separated by weeks or months of game time. The short length of every TFT module I’ve encountered seems to confirm this.

Those adventures are fine, but what about the epic journeys through enemy lands in search of… whatever? There seem to be DMs who have been playing epic campaigns without altering the healing rules. I need experience playing it to find out how much of a problem this is or isn’t. I suspect that the secret to keeping wizards alive is having them craft magic items.

In contrast, D&D feels too much like the adventurers are 1970’s Super Heroes. They get crazy powerful and it doesn’t matter how badly hurt they were in the last comic. They’ll all be healed and ready to go in the next issue. “Oh, did they run you through with a spear? Take a nap Dear. You’ll be fine in an hour.”

Judging how powerful a TFT character is, is very difficult for a new DM and there are no guidelines. D&D’s levels provide a very simple, albeit rough, way to judge that. Their “Challenge Rating” of monsters is flawed, but generally sufficient to building a balanced encounter.

In TFT there’s no clear progression of monster difficulty. There’s no easy way to choose reasonably balanced monsters for my players to encounter. I’d love to be able to take the monsters from the D&D monster manuals and “translate” their stats for use in TFT but no-one has come up with a good way to do that. It may not be doable because of how characters progress in TFT, and how varied their choices for spending their Experience Points are.

TFT players seem to use “attribute points” in place of levels. Where a D&D module might say “for levels 3-4” a TFT module would say “for 32-35 point characters”. As a new TFT DM it’s not clear what that really means in terms of how much damage a character can dish out. With D&D it’s clear that as you progress in levels you dish out (and can withstand) more damage. Characters are guaranteed to have more hit points each level. Every few levels they’re granted access to more powerful spells or abilities that do more damage. Maybe I’m worrying over nothing, and “attribute points” are a perfectly good scale. Either way, I still don’t know how to compare that to monsters.

…

After going through all this, I want to play TFT even more, but I want to do the work of creating a campaign in it even less. If Steve Jackson Games released a Monster Manual that was as well written and organized as D&Ds, I would have no hesitation.

Note for the nit-picky geeks. Yes, I am aware there are oversimplifications in this, like saying you “always roll 3 dice” in TFT. I know there are exceptions.

Software That Lasts

Sat, 15 Feb 2020 00:00:00 +0000

The Cloud Problem

When your data only exists in software that you don’t host yourself it is no longer yours. It can disappear at any moment. Its future is dependent upon a company’s continued profits and interests.

Imagine you’ve been building up a knowledge base for two years, but you fall on “hard times”. Maybe you can’t afford it. Maybe something happened and you’re literally unable to (accidents, medical issues, legal restrictions). What happens to all that data?

If you’re lucky the site has a good export feature, and you have the opportunity to use it, before its too late.

You can’t rely on a company’s VC money continuing to last. They might get bought and end their “incredible journey”. They may simply loose interest in the product.

If you’ve put years worth of effort into it. It would be a full time job to recreate it in another system. So, really you’re screwed.

The Local Problem

When the software lives locally, on your phone, or on your desktop, the situation a bit better. It should continue to work until your Operating System eventually upgrades enough to break it. If you know a breaking update is coming you could stop upgrading your device… forever. This problem is guaranteed to happen for every piece of unmaintained software.

The Solution

There are two parts to the solution.

The Data Solution

Software that manages text (documents, spreadsheets, etc) must be stored natively in a human readable, text format. You must be able to open up its files with a text editor, and with some motivation, be able to make sense of them.

Image and video data is harder, but the formats are generally public so we should be able to read them in 40 years.

Anything with DRM is guaranteed to stop working.

The Software Solution

The software must be open source. I don’t say this as an open source zealot. No company lasts forever. This is especially true for technology companies. Sooner or later, every single piece of proprietary software will die. The question is will it die before, or after you do. This sounds dramatic, but it’s actually a very real consideration. All proprietary software will eventually be abandoned. All of its creators will die.

If you’re going to put data into a piece of software, and you want that data to last for years, it must be open source software. You don’t need to be able to maintain it, but anyone who cares about it needs to have that option. In the worst case scenario, you will always be able to pay someone to make it work with your current computer.

But, being open source isn’t enough. Imagine, for example, that the world moves on from MS Word, and Microsoft decides to open source it. It’s an incredibly large and complex codebase. Many pieces are tied to the version of the operating system they were written for. It’s also, probably not documented very well internally. To keep MS Word alive and useful for the next 40 years will require a large team, working countless hours. A future government that really wants to read their digital archives, might be able to fund this. It’s not going to help normal mortals.

The software needs to be open source, documented, and reasonably focused in its scope. It must be something that a handful of dedicated fans can keep alive.

The considerations needed to design software that will last 40 years is another post entirely.

Choosing Well

For now I want you to consider a some things about the software choices you are making:

Will my livelihood be affected if the the developers who make this die, or suddenly kill this product?
If I keep using this, will I loose years of data that I care about when the developers die, or go out of business?
- Can I export my data?
- If so, would it be in a format I could do something with? For example: PDFs are nice, but they’re terrible for transferring data from one piece of software to another. They’re also annoying to extract data from.
If I suddenly become poor, or otherwise unable to pay my bills, will I loose years of data I care about?
- Note that many sites will delete your data to save space if you stop paying.
If I forget my password, or no longer have an old email address, will I loose years of data I care about?

A personal journey through programming languages

Sat, 04 Jan 2020 00:00:00 +0000

A little while ago there was a post about Programmer Migration Patterns through programming languages. I didn’t agree with it, but it got me thinking, about my 30+ years of programming, the languages I’ve been through, and when I can take away from that.

When I was a wee thing my mother brought home a used Texas Instruments TI99/4A that had been velcroed into a suitcase. I had a lot of fun with that computer. With the help of the Learn To Program Basic books from the library, I made circles and squares appear and move on the screen and did other silly things.

Fast forward a few years and I was a young teen sitting in the computer lab of my mom’s college writing Choose Your Own Adventure games in Basic on an Apple //e.

Another fifteen years or so and I’m doing freelance web design with HTML & JavaScript; pure Vanilla JS. Front-end interaction wasn’t enough though, so I learned Perl, which lead quickly to learning Bash and SQL, which have served me well ever since.

I loved Perl. It’s an awesome language to work in when you have the discipline to write clean, maintainable code.

Despite my love of Perl, Sun spent millions getting everyone excited about Java, and it worked. All the large companies were hiring Java devs. All the cool new stuff was being made in Java. So, I learned it…

I think Java’s. It’s an incredibly capable language, and it taught me a lot. It’s also completely soul-less. There’s no joy in it. While my days were spent poking Java for big companies, I dabbled in Python and picked up enough PHP to help on a contract. I hated PHP. I feel it’s a messy junk-drawer of a language.

Perl came back into my life for a while when my employer bought a company with a Perl codebase, and that was a nice change.

Around that time (2006ish) I discovered Rails, which thanks to Ruby, was a much nicer way to build web sites than anything before it. I think Matz created something great when he built Ruby. Its guiding principle of “optimizing for developer happiness” has had wonderful consequences. I’ll be forever grateful to Dave Thomas for writing the book that helped bring this language to the US.

Ruby lead me on a brief trip through Smalltalk, which I undervalued at the time (Glamorous Toolkit didn’t exist yet either). Looking for something that wasn’t just another C-like thing I turned to Common Lisp. CL was great, for the time it was written. We have learned a lot since then, and certain things like “the internet”, and “package managers”, and interacting with “other applications” have proved to be really useful ideas. Common Lisp has managed to incorporated essentially none of them, although Quicklisp is starting to change that.

I wanted to love it but it honestly felt like it hadn’t been updated for 30 years, and trying to anything that involve things invented since then was ridiculously difficult. Combine that with things like looping being having its own excessively complicated mini language, and other common APIs also having way too many ways to invoke them and I gave up. I don’t want to have to fight with my language to get basic shit done.

It was around this time that i started to be concerned about distribution. If I wrote something in Common Lisp, how would I give it to you to run? You probably don’t have it installed. What about something I ran in Ruby? Ruby’s even worse. You need to know about installing different versions of it. You need to know what a “Gem” is. You need to know what “Bundler” is and how to use it. If it’s a rails app there’s another layer of setup and invocation knowledge that’s required.

Developers immersed in a language’s ecosystem forget just how much built up knowledge it takes just to “launch” an app. I want to be able to create things I can just give to you and have you use, regardless of your favorite language or if you’re even a developer.

It was clear that lisp was something special that still had a lot to teach me, and I wanted to find a way to work with it. That led me to Scheme, which is awesome but has tons of flavors to choose from. Fortunately, I had a couple more criteria to help whittle down the list.

It had to produce a binary that other people could run with no knowledge of the language or ecosystem it was created in.
It had to be something that made it easy to work with the internet, databases, and filesystems. Yes, I know. Most developers take it as a given that you can do that.

I ended up with the Chicken Scheme because it has a great collection of modern libraries and is very enthusiastically kept in the present by its users. It also transpiles to C and then uses a native compiler to compile that to an executable. So, I’ve got tools for the modern world, and a binary you can “just run”.

Unfortunately, Schemes are “batteries not included” languages. Their Standard Libraries are very bare bones, and the significant number of things you have to write for yourself is a bit jarring when coming from languages like Ruby and Perl. The number of “eggs” (libraries) helped a lot, but I still ended up writing my own set of list functions, and comparators, and other “core” stuff like that.

I feel like getting stuff done in a scheme is a lot more work than in a “batteries included” language, but I’m not “fighting” with the language. Scheme is happy to help me make the tools to get stuff done. It just doesn’t have them pre-built.

Around the same time I started looking at Crystal. It’s essentially a statically typed, compiled version of Ruby. I’m a huge fan of Statically typed languages and explicitly defining what everything is. The compiler errors help me develop faster, and the explicit annotations are wonderful for improving the maintainability of the codebase. To me, though Crystal is just a better Ruby. I’ve gotten a lot of value out of it, but it hasn’t taught me anything new, and I’ve been hanging out in Ruby land for a very long time now.

After building my Chicken Scheme and Crystal executables I rediscovered the headaches of dynamically linked libraries (dylibs). Both languages gave me an executable that worked great, if you happened to have the right libraries installed on your system. They didn’t even work on all of my computers never-mind a non-developer’s. On top of that, it turns out that macOS (my preferred OS) really REALLY doesn’t want you to generating statically linked binaries.

As far as I know it’s not possible to make a 100% statically linked binary for macOS, but you can statically link everything except the system libraries. There are some tools for finding those dylibs in your executable and statically bundling them into it. At the time, I could not find them, and the languages didn’t offer static linking as an option. Crystal may have, but I recall still having some issues testing it. At the time of writing Crystal and Chicken scheme both offer it and I know for a fact that the Chicken Scheme works well, but the documentation is kinda crap.

I wanted a language that really “got” this distribution problem, understood the modern world, and now my latest criteria… had a good solution for concurrency or parallelism. [side note: Crystal actually had concurrency from early on, and now offers parallelism too.]

I tried Go. Partially because it really understands this distribution problem, and “all the cool kids are doing it” which is useful when job hunting. Unfortunately the more I used it the more I disliked it. I kept telling myself that it was created by some geeks with serious cred, and that if I stuck with it, I’d surely learn something good.

What I learned was that I have fundamental philosophical differences with the people who created it. I’m crossing my fingers that I don’t need to get a job programming in it.

Conclusions

So, what have I learned from all this?

Learning new languages just makes you better at whatever language they pay you to write.
Being a “good” language isn’t the same as a “good” language for you.
People don’t value learning a lisp nearly enough.
People aren’t thinking enough about the importance of easy distribution.
What’s Next?

Learning languages makes you better.

Fundamentally there are only a handful of programming constructs. Learning a new language teaches you to distinguish between basic programming features, and the syntactic sugar your language adds to them to make life “better” for the developer.

As you learn more languages you pick up more core tools. You gain new ways to use the ones you have. After the first couple, every new language you learn reinforces your core understanding of what “programming” is, and that learning the next language is just a matter of learning the syntax for the concepts you already mastered.

“Different Strokes for Different Folks”

Different people think about things different ways. It’s why working through problems with other people is so useful. I loved how Perl let me solve my problems in 20 different ways. I hated how Python forced me to use 1, or maybe 2 solutions for a thing. It was never a “bad” solution, but it forced me solve problems from an approach that I just didn’t want. At the same time, that simplicity and lack of complication is joyful for some people. I totally understand why people love Python.

It’s ok to hate a language others love. It’s ok to love a language others hate. Try and find one that works well with the way you think, and helps you to express your thoughts with the least interference.

Lisps

Even after a decade of programming it was still a major eye-opener to learn a Lisp. I suspect that learning something even more functional, like Haskell, would be a great learning experience even now. I think it’s ridiculous how people get all bent out of shape about “all those parentheses”. There are tools for this, people. It’s a solved problem.

And macros, oh my. Lisp macros are a beautiful thing. Being able to easily change and improve any aspect of a language… it’s an amazing thing. It’s also a dangerous tool that, when taken too far can make it difficult for others to contribute to your project.

My advice is to learn a Scheme. Racket is probably a great place to start. There are lots of books, the documentation is great, and it’s designed for teaching and learning. I went with Chicken Scheme because of its ecosystem (Racket’s is even better) and because it compiles to C code (or straight on to an executable), which means I can build it anywhere easily. The 5.0 release made creating statically linked binaries easy too.

Distribution

Code distribution is a serious problem that’s not getting nearly enough attention. The required knowledge to get a Ruby programming running is ridiculous, and it’s the same with most modern languages. The Go community is one of the few that really gets this problem. They’ll give you a binary for your system that requires zero knowledge of Go or Go libraries to run. On top of this, their binaries can be statically linked. This radically changes who can use your creation and how hard it’ll be for them. Wanna know how to run a Go app? Just execute it. It’ll either start working, or give you usage instructions.

It is frustrating to me that no-one seems to care about this.

What’s Next

I’ve burnt out twice in the past decade. The first time was bad. The second time was worse. I’m trying to avoid a third time. The effects of this color all my decisions now.

The most significant effect (relative to this post) is that I don’t have enough fucks to give for languages that I don’t enjoy. I spend 8+ hours a day thinking about code. Most of it is frustratingly terrible code that I’m wading through. I don’t need any additional frustration coming at me from the language I’m working in.

I’ve been learning Rust for a work project, and I’m gaining serious respect for it. It’s a really great solution to the problem its creators had. But I don’t have the problems its creators have. I’m fine with garbage collection. In fact, I like garbage collection.

After 30+ years of writing software. I like not having to deal. I like not having to specify every little detail for the compiler to know what I mean. Crystal does a great job of letting me not deal. I even specify all the types that it could figure out implicitly because it makes it all so easy, and my doing so makes it trivial for the people who come after me to figure out what I intended. But, like I said, I’m getting tired of Ruby.

My advice to you? Don’t waste your limited time in a language you don’t enjoy. There are too many good ones out there. Search them out. Some of them are new, and rough, but worth helping grow. Some are old and filled with amazing tools. Learn Smalltalk. Learn Lisp.

I’m not sure what language I’ll end up playing with next. I do know that I’ll be trying to find a way to spend it with one that makes me happy.

How SSH Keys let you into servers - a metaphor

Mon, 17 Jun 2019 00:00:00 +0000

SSH Keys can be a little confusing to new developers. Here’s a quick little metaphor to help you think about how they work.

tldr; Your public key is your business card. You can give it to people so that they can add it to the list of people authorized to access a machine or service. Your private key is a tool that proves that you’re the person associated with that business card.

…

Imagine that remote machines as members-only nightclubs. The bouncer will prevent anyone from entering if their name isn’t on the list.

You get your name added to the list by having a trusted member of the nightclub add it.

Once that happens, you go up to the door, prove that that name is really you, and then you are allowed entry.

With regards to SSH keys, every key is actually a key pair. There’s the public half (the .pub file) , and the private half. Frequently these are called id_rsa.pub and id_rsa. But, they could be called anything. Your public key is like a business card. You should feel comfortable giving it to anyone you think could use it.

In this metaphor, you gave your business card to a nightclub member and they attached it to the list, so that the bouncer would know to let you in. In real life, you give your public key to a system administrator and they add it to a literal list of keys of people/machines allowed to access something.

Your private key is super secret. You don’t let anyone see it. You don’t even let the bouncer see it. The private key is a tool that lets you prove to the bouncer that you’re the person on the list. The bouncer says “prove you’re XXX” and you use your private key to do just that.

…

There are different forms of encryption that can be used in generating your key pair, and different reasons for each, but that’s largely irrelevant to how they’re used.

Go will never belong to the community until they decide its future

Wed, 29 May 2019 01:03:48 -0500

There was a recent post* about how Go is Google’s language, not ours. It was an opinionated post, but it provided some evidence to back up its claims.

Russ Cox (a Tech Lead for the Go language) posted a reasoned response to this which, I think basically tried to say that it wasn’t true, and they had regular meetings to discuss community proposals.

But for me, the telling bit of it was this:

We have talked in the past about whether to explicitly look for people outside Google to sit in our weekly meeting, but if that’s really important, then we are not doing our job right.

It doesn’t matter how many different types of people you let speak at a meeting if you don’t let those same types of people participate in the decision at the end.

There’s a huge difference between listening to people unlike yourself and truly understanding people unlike yourself. For example, I’m white. I try really hard to listen to members of the black community, but I am in no way equipped to truly understand what it’s like to be a black person in this country. I’m definitely not equipped to make decisions on their behalf.

This same thinking applies to any group. If the community is not participating in the decisions about their needs then they have no real voice, and whatever you’re discussing absolutely does not belong to them. It’s just something you’ve chosen to share with them, and let them talk about.

For a real world example of this, consider politicians. Their job is to listen to community proposals about what to do with the community. Recently 25 white men who just decided that they were better judges of what to do with women’s bodies than women. Similarly, politicians with stable incomes have been making it increasingly illegal to be homeless. This is what happens when the community gets to speak, but only one type of person gets to decide.

Until the community has a voice in the decisions about Go’s future Go is not theirs.

[UPDATE] Russ responded to my post on twitter with more thoughtful words. The core of it seemed to be that I was misunderstanding the purpose of the “room” discussed above. I may be. But in my experience, whenever an insular group is discussing things that affects others, and asks “should we allow them in here?” the answer should essentially always be “yes”.

* Recent as of May 29 2019

oho's Backstory

Thu, 23 May 2019 01:03:48 -0500

I’m going tell you the tale of oho, a program which is arguably the world’s greatest ANSI text to HTML converter, and how it solved a real business problem. I’m sharing this because, as a geek, it’s important to remember that you can frequently solve work needs, while having fun creating open source tools that interest you.

Side note: ANSI escape sequences are the things that cause text to be colored, bolded, etc when displayed in a terimnal.

One of the roles I played at One Door was that of Release Manager. The core of that task was figuring out what code was included in, or missing from, a release - and then communicating that info to the Project Managers and Scrum Masters. Most importantly, I needed to make it clear to them if there were things they should be concerned about.

I accomplished this by writing a series of small, focused, command line tools that embodied the Unix Philosophy and worked together to extract data from Git, Github, and Jira, then combine it into a report which was transmitted to the interested parties via Slack.

The larger releases presented a problem though. Project Managers didn’t really want to read through the status of 300+ tickets, or contemplate what unexpected commits might mean to their release. It was too daunting of a task, and they had enough things on their todo list.

One of the strategies I took to help address this was to highlight unimplemented tickets, or unexpected commits, in different colors. Unfortunately, there’s no good mechanism to get terminal colors into Slack. Colored text just isn’t supported. For multiple reasons, the right answer seemed to be to give them a PDF version of what I was seeing in the output of my tools.

I didn’t find any extant ANSI to PDF converters, but that wasn’t surprising. I did find a number of HTML to PDF converters though, and I knew you could convert ANSI to HTML. So, I set up an ANSI -> HTML -> PDF pipeline and quickly discovered that my PDFs looked terrible. The problem was the HTML. Every existing ANSI to HTML converter had some aspect of it that made it just unusable. In one case, my half-page test grid of colors ended up being an unreadably small postage stamp in the corner once it made the final transition. Others didn’t actually support the various color codes very well.

Choosing a technology

aha (Ansi HTML Adapter) seemed the best of the available tools. It was written in C. I figured it was better (and faster) to debug and tweak something that was fast and mostly working, than it was to write something from scratch. Unfortunately, it’s source code was not up to my standards. It worked, but it wasn’t very readable, or commented, or well organized. It was more a stream of consciousness in code form. As I spent more time refactoring it, I realized that by the time I was done, I’d have a completely different codebase that was readable, and maintainable, but still not very extensible.

So, I began to write oho.

It was clear from my work refactoring aha that this was going to be a non-trivial codebase with multiple files. I wanted to write it in a language that would allow me to distribute it without people having to know anything about the ecosystem surrounding it. Ruby is terrible for that because you need to know about Gems, and Bundler, and most systems ship with old Ruby versions and… I wanted this to be simple for users. So, I needed a compiled language. Crystal met those requirements, and I’d been using it for a while and found it rather enjoyable, so that’s what I used.

Crystal produces Dynamically Linked executables (like most compiled languages) so distribution was just a matter of creating a Homebrew script (for Mac users) that told people’s computers where to download it and what dynamic libraries it dependend on. The same can be done for other systems with little difficulty.

Chicken Scheme would have been another choice I could have easily worked with, but beyond just producing a single executable, Crystal is less intimidating to most developers. Lisps are treated as exotic things with “too many parentheses.” I wanted something that could be easily enhanced by anyone in the Open Source community. Crystal looks very similar to Ruby (it’s essentially just Statically Typed Ruby), and organizes its code along lines that are familiar to most developers who use descendents of C (Ruby, Python, Java, etc). Crystal also has a decent testing framework built in. It could be better, but it gets the job done relatively painlessly.

So, I chose a language that would give me a single executable that required no knowledge of the language or ecosystem it was written in to install, would be easy to test, and easy to extend by people unfamiliar with the codebase. If I had it to do again, I might write it in Go, because of the Statically Linked executables it creates, along with easy cross-compilation.

In the end, I had a fast tool that I installed at work and began presenting the project managers with colorful PDFs for each release. Since then, I’ve added support for more esoteric escape sequences, and plan on continuing to do so in the future.

I also had fun writing it.

Quality Is Rarely Job 1

Sun, 03 Mar 2019 15:13:58 -0500

In 1981 Robert Cox came up with a slogan for Ford; “Quality is Job 1”.

It has always stuck with me.

In the software industry there are few slogans could be further from the truth. C-level’s and other customer facing types frequently proclaim the “quality” of their products, but they aren’t the ones making the product. They’re frequently not even the ones using the product.

In software there are two viable ways to release quality software. You can release it when everything you want done is done, or you can release what you happen to have done at a specific date. You can’t combine the two, although almost every software company tries to.

People outside of engineering tell clients X will be ready on Y date. That date is inevitably too soon for the promised features to be completed.

Realistically, there is only one way to combine promised dates and promised features in software. You compromise the quality. People could, promise a date generously far in the future, but that’s not very helpful meeting to this quarter’s sales goals.

In order to deliver quality an engineer needs the support of management to not deliver code that isn’t done. “Done” of course doesn’t mean “It seems to work.” or “QA didn’t complain.” Done means “I have tests to prove it works.” Done means “QA can prove it works when users get ahold of it.” Done means “It’s intuitive for users.” For multi-user systems Done means “We can prove it works when tons of users try to use it at the same time.”

Done might not mean “It does everything that was requested.” There are always more features to add. It does mean that everyone, even the client, agrees that the features that are Done, are “enough” for now.

I believe that there are a few companies out there that actually deliver “quality” software that even their engineers believe in. I’ve never worked for someone else’s company that did this. Features sure, but overall product quality? No.

Your Own God(s)

Sat, 12 Jan 2019 21:03:48 -0500

I’ve had an idea buzzbuling around my head for a while, that I’d like to share with you. If you’re a devout follower of any religion, I ask that you set aside what your preconceptions for a few minutes, and listen openly to this somewhat heretical thought.

Premise

All, or at least most, gods are created by people. Maybe I’m wrong, and there is one true deity, but logically if one is true, then all the conflicting gods must be the creation of human minds. If none are true, then they’re all human fiction.

No-one has any proof that their deity, or deities, are the true ones that will really handle our souls in the afterlife. Statistically speaking it is improbable that whatever god you’ve been told is the real one is, actually the real one (assuming any are). There are just too many gods. Plus, just because a lot of people agree about something doesn’t mean they’re correct. There is far too much historical evidence for that statement. In terms of religions, look at the Greek pantheon. Essentially no-one believes that the Greek gods exist, or ever existed, and yet countless people prayed to them daily. “Everyone” knew they were real, and now “everyone knows” they’re just old human fiction.

Additionally, we have the fact that holy teachings are constantly being twisted by their “faithful”. Witness the Christian Crusades completely ignoring the “Thou shalt not kill.” and “Love thy neighbor.” rules when they went off and killed or tortured vast swaths of people who believed differently. Priests of every religion disagree about what their god(s) want you to do all the time. The Bible, for example, has had the meaning of many of its passages dramatically changed through translation “errors” over the many versions since its original Aramaic. Even if the deities you were told were the “true” ones are actually, the true ones it is incredibly unlikely that what you were taught about what they want is actually “true”. Could any human language accurately, and unerringly, capture and describe the will of a god?

Reality

There’s no denying that the belief in deities has a very real value to very many people. The more difficult our lives are, the more we reach out to the gods for comfort and protection. Many people who truly pray seem to feel something positive come from their actions, even if it’s just the sense that someone is watching out for them.

Prayer, like meditation, influences our state of mind, which, in turn, influences our “state of body”. It reduces the experience of anxiety, elevates a depressed mood, lowers blood pressure, stabilizes sleep patterns and impacts autonomic functions like digestion and breathing. Further, in influencing our state of body-mind, prayer and meditation also influence our thinking. This prompts a shift in the habits of the mind, and, subsequently, patterns of behavior. These changes, in turn and over time, induce changes in the brain, further influencing our subjective and objective experience of the world and how we participate in it. - Psychology Today

Heresy

If gods are human fiction, and it’s unlikely that whatever god(s) you believe in are real, but having someone or something to believe in, and pray to, can provide us with comfort and solace, then why not create your own god or gods that reflect the world as you see it?

Imagine what happens when you start to live in a world surrounded by gods you know intimately; gods who manipulate, or ignore, the world around us in ways that are entirely sensible, because they are the ways you envisioned.

Maybe you create new ones. Maybe you repackage the ones you grew up with in newer garb that makes more sense to you. Maybe you love Jehovah, but can’t believe everything in a Bible that regularly contradicts itself. Maybe Zeus is still around, but not living on Mt. Olympus anymore. Maybe Media is a new god that far too many people pray to… It’s entirely possible that your personal god(s) may actually be a true description of the “real” god(s) given to you by holy inspiration.

Everything we’re taught tells us this is “wrong”. History, however, tells us this this is what humans have always done. For me the real question is, will you give yourself permission to take this leap? Will you give yourself permission to do what our ancestors did again and again? Even an atheist can benefit from their own personal pantheon to pray to, or swear by.

Basic Readiness

Sat, 01 Dec 2018 11:12:49 -0500

Basic readiness is a problem for most people. We assume that we’ll always have power, water, and food. We ignore the fact that this stuff goes away regularly, because it usually happens to someone else.

There was a snow storm here in Vermont (USA) last week. This was not a blizzard. As far as weather goes, this wasn’t particularly dramatic. There was just a lot of heavy snow and some high winds. Monday night the news came that towns were starting to loose power. As the weight of the snow took down more and more trees and branches, it became clear that this was going to be major.

“[Green Mountain Power] tripled its field force with external crews from Massachusetts, New York, New Hampshire, Connecticut and Ontario and Quebec in Canada. GMP also doubled its tree crews with teams from Pennsylvania, New York and New Hampshire.” - Green Mountain Power

They let folks know early on that some people wouldn’t have power restored until Saturday (five days later). On Friday this was reported:

“Winter is here in full force and is prepared to hit us again with another storm forecasted for Saturday. Green Mountain Power crews have been out all week and so far, restored power to more than 100,000 customers. Crews are on track to finish restorations tomorrow, just as forecasters say a new storm system will hit Vermont. GMP is preparing for the possibility of new outages starting Saturday night. The storm is expected to bring wet snow, freezing rain and ice to already hard-hit areas of central and southern Vermont.” - Vermont Biz

100,000 people were without power. Some of them for almost a week. Cell phone towers usually have a few hours of emergency power. Outside of the city, when a tree takes out power lines it frequently takes out your phone, cable, and internet too.

Emergencies like this happen. They’re not rare. They just tend to get spread out, and we assume that because we haven’t had an emergency like that we’ll be fine. But even 24 hours without power can be a big deal in the winter or on summer days when the temperature is around the 100°F (38°C) mark.

So, here’s my question to you. If your neighborhood lost power for 3 days in the dead of winter, what would you do? What if you were snowed in? What if the storm was still going?

Can you keep your family and pets from freezing?
Can you keep your pipes from freezing?
Do you have enough food?
Do your pets have enough food?
If you live in a rural area, how will you know when the roads are safe?
If someone gets hurt, how will you contact emergency personnel? (remember: no phone, cell, or internet)
What if someone becomes hypothermic?
Does your town have a warming shelter? If they don’t, where’s the nearest one? Do they allow pets?
What if the roads aren’t drivable?
What about medical devices (even CPAPs) or things like insulin that need to be kept at a certain temperature?
How will you get water if the water pumps have no power?
What about food? Supermarkets get cleared out before a storm, and don’t like taking deliveries or doing business when they have no lights, or refrigeration, and can’t process anyone’s credit / debit cards.
If your car breaks down on the side of the road when people were told not to drive, how will you call for help? How will you keep from freezing?

And that’s just questions for winter. What about something like the California wildfires?

I wish it wasn’t so hard to get people to think about these things. I wish people wouldn’t keep disregarding these types of simple emergencies that happen to people in first world countries every year. Climate change creates more extreme weather, and is even being linked to earthquakes. These events will happen with increasing frequency, but even if it didn’t, it already happens with enough frequency that we should all take it seriously.

Ready.gov has basic guidelines to get you started with planning for events like these. They’ve also got a guide to putting together a simplistic emergency kit.

Libraries, Fameworks, and DSLs

Thu, 16 Aug 2018 23:23:07 -0400

One of my coworkers was trying to understand the differences between libraries, frameworks, and DSLs and asked me

…how do I know what i’m using when all these things are

interacting and being used within each other, etc

To some degree, you don’t, and it doesn’t matter, but that’s not a very helpful answer. So let me step back and talk about what each of these are.

Libraries

Libraries are the simplest. A library is just a collection of code intended to be reused. They’re typically packaged using a package manager, but it doesn’t need to be “packaged”. It could be just some file of useful code that you load into your code like any other source file.

A library is the hardest to “know” you’re using because it generally provides some new classes or methods. Unless you happen to know where those clasess and methods came from you don’t know you’re using it. In languages like Ruby where you can alter code at runtime a library could change the behavior of existing code; no new methods, no new code, things just behave differently.

DSLs

DSLs are Domain Specific Languages. The greatest example, in my opinion is SQL. For example

select name from students where age > 7

Without any SQL knowledge you can probably guess that there’s a list of students somewhere, and running that line will return the names of each one who is older than 7.

SQL is very powerful, but it’s very focused on querying and manipulating tables of data. It makes that very easy, but it’s really crappy at everything else. That’s pretty typical of a DSL.

In the Ruby world we have a lot of DSLs but people tend to not recognize them as such. For example, an RSpec test might have something like this

describe "Math" do
	 context "double" do
	   it "should return twice the input" do
	     expect(Math.double(2)).to eq 4
	   end
	 end
end

Like SQL it’s pretty easy to guess what it does.

You might be thinking “But rspec’s just Ruby code. That’s just Ruby methods.” This is true. RSpec is a DSL written in Ruby. It’s not limited to Ruby though. I could port RSpec to most languages and maintain the same syntax.

You can think of a DSL as a collection of commands that simplify instructing the computer to do something in a focused domain.

How do you know when you’re code from a DSL instead of your core language? If you are dealing with a non-trivial set of commands, that aren’t part of the core language, and are all focused on helping with one specific aim, you’re probably using a DSL.

RSpec, is a DSL, that’s packaged up as a library, that can be added to your project. Loading the library teaches the Ruby compiler how to understand the RSpec DSL.

Frameworks

Neha Choudhary described it like this:

If I told you to cut a piece of paper with dimensions 5m by 5m, then surely you would do that. But suppose I ask you to cut 1000 pieces of paper of the same dimensions. In this case, you won’t do the measuring 1000 times; obviously, you would make a frame of 5m by 5m, and then with the help of it you would be able to cut 1000 pieces of paper in less time.

That sounds a lot like a DSL, and from some perspectives there is overlap. But a framework doesn’t make it easier to do only one thing. It provides a large infrastructure to facilitate the connection of things in many domains.

I like to think of them like skeletons. Skeletons are collections of bones. Some bones are for protection. Some facilitate locomotion. Some facilitate eating. Collected together they are a framework with areas specialized for holding digestive bits, and areas specialized helping us move around, and so on. Creatures can exist without them, but once you have a skeleton lots of things become easier to accomplish. Code can exist without frameworks, but frameworks make it easier to create code that does big complex things.

Let’s look at Rails (a web development framework) as an example.

Rails (like most web frameworks) provides infrastructure to:

facilitate object relational mapping to store the data you’ve collected about some object in your system in a database, and then take the data in a database and convert it back to objects in your system.
facilitate the handling of HTTP requests from a web server and make it easy to query all their relevant pieces (form data, headers, query string data, cookies, etc.)
facilitate the generation of HTTP responses to a web server with all their relevant pieces (headers, cookies, mime types, content (html, javascript, css, etc)
facilitate the handling of those http request objects it created for you
template management (in various templating DSLs, haml, erb, etc)
facilitating the connection of templates to the things handling the requests
logging
testing (of models, of controllers, of views)
and many, many more things.

You could say that almost all of those involve some DSLs. Making a class a descendent of ActiveRecord::Base connects it to a database table, gives it a getter and setter method that corresponds to every column of that database table, functions to update, validate, save, delete, etc. There are even methods for describing the relationship between other classes tied into tables like belongs_to :some_class

All those methods are part of a DSL for manipulating the data in database tables. Just like SQL. But, that DSL doesn’t know anything about manipulating HTTP requests, even though Rails does.

Rails is a Framework, made of a collection of DSLs, packaged in a Library.

Summary

So, how do you know when you’re using a Library, a DSL, or a Framework?

The only way you’re not using a library is if you’re writing something that only uses code from the smallest beating core of your language.

Most languages come with a “Standard Library” which is a collection of classes to save people from writing a lot of obnoxious low level code. For example: most languages have a Date class (or something like one). That’s part of the Standard Library. Compilers have no need of a Date class. They can do their job just fine without one. That’s a convenience library for the humans.

Are you using a DSL? If using methods defined as part of a Framework then there’s a good chance you are. Frameworks are frequently collections of things that could be classified as DSLs. If you’re using a set of commands that would be useless for anything other than one focused domain, then you’re probably using a DSL.

Are you using a framework? That’s the easiest. Did you load a framework? Are you calling methods defined in that framework? Then yes, you’re using a framework.

If you are using methods defined in a framework, that are also a DSL, then you’re using all three, because frameworks are collections of code intended to be reused.

Ultimately, it doesn’t matter what you’re using, but there is value in knowing where the commands you’re calling come from. When you start another project, you will know what libraries to pull in to give you those commands again without having to create them from scratch.

Converting HTML to PDF on the command line

Sun, 27 May 2018 21:39:00 +0000

I recently needed to convert some HTML to PDF on the command line and went hunting down the options.

There numerous posts saying “X is great” “Y works great for me” but no-one gives examples that show you anything.

I’ve tried WeasyPrint, wkhtmltopdf, Pandoc and Google Chrome (yes via the command line). The test was simple. Take a simple color chart, made from pre-formatted text and render it as a pdf. This doesn’t test any fancy CSS grid layout, or sizing or … anything. Just straight pre-formatted text with some spans that only define colors.

Here is the original html and here’s what the conversions looked like.

The version rendered from Chrome is perfect. I have zero complaints.

The version from WeasyPrint is cut off on the right edge. Note that it is not the window that’s cutting it off. That’s the edge of the PDF itself.

The wkhtmltopdf is perfect if you zoom waaaaaay into it. Realistically though it’s unusable crap because it’s so small. Note that it has also added a border

Pandoc (not included in the screenshot above) seems to be really focused on text. The result was completely devoid of color, used a different font, and was centered in the page. It did maintain the formatting within the table though.

The winner, for me, is clearly Chrome. The magic incantation is as follows. Save it in a file called html_to_pdf and then you can convert your html with

html_to_pdf path/to/my/html_file.html

It will generate an output.pdf file in the current directory.

#!/bin/sh

# on linux everything before --headless can be replaced with just
# chrome
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --headless \
  --disable-gpu \
  --no-margins \
  --print-to-pdf $1

This all came about because I’d recently written oho (an app for converting your colorful terminal output to HTML), and I wanted to convert that HTML to PDF to more easily share with my coworkers over Slack. Oho is perfect for sharing terminal output on a blog though. ;)

Zed Shaw's Utu: Saving the internet with hate

Sun, 25 Mar 2018 13:51:38 -0400

A high level summary (and paraphrasing) of Zed Shaw’s talk at DEFCON 15 (in 2007) because I couldn’t find a good text version.

Utu is the Maori word for a system of revenge used by Maori society to provide social controls and retribution. Utu is also a protocol that uses cryptographic models of social interaction to allow peers to vote on their dislike of other peer’s behavior. The goal of Utu is to experiment with the effects of bringing identity, reputation, and retribution to human communications on the Internet. A secondary goal is wiping out IRC because apparently nobody really likes IRC.

The Utu project is now dead, but its source code can be found on Github. While reading this keep in mind that the core idea is a centralized chat server.

Part 1: The Idea

Philosophical Foundations

Strong Identity
Reputation
Retribution

If you have and combine those, you can start to implement some controls available in human communications.

Strong Identity

In order to have strong identity everyone has a cryptographic key, but because keys are so easy to create you have to be invited, and you have to have a handshake as part of the invitation because you need to care about who the invitee is. This doesn’t work if any jerk can invite any other jerk without consequence.

Zed certify that he wants to invite Joe.
Joe certifies that yes, that invite is from Zed.
Joe takes action to assert that they actually want the invite
Zed says yup, I really did want Joe to join us.

Reputation

Rather than associating likes with an identity or posts you associate “hate” with an identity, and over time that hate builds up from many people.

“Wouldn’t it be great to punish the dickheads?”

Retribution

(Keep in mind that Utu was intended as a chat network)

As a person builds up hate they have to do some cryptographic proof of work before they can do anything. The more hate they have the more work their computer has to do before they can say anything.

This accretion of hate gives you a weighted social network that you can crunch numbers on. You can figure out who “hates” who, who talks to who, where they come from, and we can start looking at the social problem.

You can say “Hey, if we change the hate model to be this way, or we change the hate model to be that way, how does the social network change? Do the jerks go further away?”

Another alternative to hate is distance, because people aren’t prevented from talking to you it just takes them longer.

Part 2: The Implementation

Geeky Details

The Protocol

Sends 2 bytes for size (htons(size)) (for framing)
Sends the data structure (“Stackish”)
- S-expressions with netstrings in a FORTH stack order
- [['4:test' 1234 child root is equivalent to this lisp (root (child (1234 '4:test')))
That’s it.

Semantics

Determined by the Hub (everyone talking to hub)
- routes things to different chat rooms
One Stackish node for header
Another for body

Data Encoding

Always ASCII text, but you can put anything you want in BLOBs.

Simplicity is Key

2 bytes for frame
Stackish for header and body
easy to implement

Security Preventions

Zed believes that you need to design your software with the assumption

..that everyone on the internet is a fucking ass hole and they need to be taken down…If it goes on the internet it’s social software. It shouldn’t be designed assuming everyone likes you… Eventually some person is going to hack it. Eventually someone is going to try and abuse it.

I’m not going to be able to stop everyone…but if the server and the protocol, like from the base of the protocol on up is designed to make it so it’s harder… it’s not making it impossible, just harder… then what I’m banking on is the predator concept. A predator, when picking two different types of prey, will pick the weakest one.

Client does all the crypto work to prove identity first and the server just validates it. If it’s wrong the server puts the identity in a blacklist and then boots them.
Client is considered hostile
Booted immediately
A Finite State Machine controls

The Cryptography

Never write your own. Let the pros do it.
Follow the rules
Use standard stuff

Details on exactly what it uses are at 20:48 in the talk.

Secure Coding Practices

All code “ruthelessly” run through a test suite on a loop, with running stats used to compare releases.

Statistical Quality Control

Collect Information on
- Valigrind erros
- Unit test errors
- Logged Errors
Analyzed the changes over time

Code Auditing

Review my code repeatedly.
Consistent “rules” I follow.
Assume it’s always broken.

C Coding Practices

Bstring library for strings
All functions have valiadtions
- Assert
- Preconditions / postconditions
- Extensive Unit Testing.

Secure Unix Server Practices

The Server Always chroots ALWAYS
Leave minimum resources open.
Minimum configuration.

Practical Demonstration

This starts at 30:41 in the talk and involves a fair number of geeky commentary. For non geeks a) why did you read this far b) it’s just a really simplistic chat client.

The Guy Who Loved His Work

Wed, 21 Mar 2018 17:23:02 -0400

(or Why A Healthy Work-Life Balance Is Important)

During the dot com boom I worked at a company with a developer who loved his work. The problems were challenging, and we really valued the things he produced. Everyone who worked late late got dinner, and sometimes he’d work so late that he ended up sleeping by his desk. Bob (not his real name) wasn’t pushed to do this. He just really liked his job.

After about five years the dot com crash hit. A third of the company was laid off. Then another third of the company was laid off. Then everyone left was laid off and all the assets were sold to IBM.

Bob was left with a five year gap in his life. He had nothing to show for that time. No real relationships. No software he could point to. It had disappeared into the bowels of IBM. I assume he became a better programmer during this time, but everything else suffered.

Bob could have been spending those hours writing cool software for himself. He could have been helping open source projects that were important to him. He could have spent time with the people he cared about. He could have found new people to care about. He could have been falling in love.

Day after day, most of us help someone else’s company to thrive, and many of us forget that it’s not our company. It’s not our “baby”. We don’t get rich if it succeeds, and we suffer when the people in charge make bad decisions. Your company may get sold, or implode. The people in charge may decide to abandon the thing you’ve devoted your time to. Even in a healthy company, your work rarely makes the world a better place. It rarely makes the people in it healthier, or happier.

Our time on this planet is too limited, and most of our waking hours go to someone else. They aren’t devoted to improving our lives or our happiness.

Don’t let yourself wake up one day and discover you’re another Bob. Put in the hours you agreed to when you signed up, and then go do something for you.

Getting Started With Scuttlebutt

Tue, 26 Dec 2017 09:56:35 -0500

Ok, you’ve been hearing about Scuttlebutt and decided that “Yes, I do want to join an amazing social network with lots of good people that no company can control and also happens to also work offline.

Here’s a quick overview with the basics you need to know.

First off Scuttlebutt is a protocol on which many different kinds of apps can be built.

As for the social network, there are many clients, just like there are many Twitter clients. It doesn’t really matter which one you use. They’re all talking on the same network.

As of Dec 2017 Patchwork is the most polished client and it doesn’t require you to know any geeky stuff. The only caveat is that it just wants to run on one computer. ¹ and your identity is tied to the files on the computer you install it on.

Step 0

If you haven’t done so already go to the Scuttlebutt Home Page and watch the video. Then come back.

Step 1

Download Patchwork, and install like any other app.

Step 2

Boot it up and set up your profile.

It doesn’t matter what name you put. It can be your real name. It can be a nickname. Like the real world it’s entirely possible for multiple people to have the same name. Your friends can give you nicknames too.

You don’t need to upload an image, but I recommend that you do, because it’s much easier to figure out who is talking when there’s a visual, and the defaults are really generic. Some people use a photo of themselves. Some people use a random avatar they like, just like Twitter.

The text area, like every text area in Patchwork uses markdown formatting².

Save that when you’re done.

Step 3

Get connected. Because Scuttlebutt is a distributed network you need to find some people to follow. This is partially because it’s really really boring if you’re not listening to anyone and no-one is listening to you. It’s also because you get “gossip” from the people you follow. “Gossip” is more than just info about people you’re interested in. It is also the name of a protocol that Scuttlebutt uses to share information.

Connecting Locally

Most of us don’t happen to be sitting next to someone else on the network. If you are you’ll see them listed under “local” on the left. Click their profile to see more about them, and click “Follow” if you feel like following what that person has to say (just like Twitter). You’ll start downloading information from them that they’ve posted to the network and information their friends have posted.

Remotely

Even if you are next to someone you’ll still want to connect to a “pub” server so that you can exchange info with others if no-one is nearby. In the video they’re described as being more like bartenders than pubs, because it’s the bartender who you gossip with at the pub, and shares the gossip of others.

Go to the list of pub servers.

Open one up in a new tab and you’ll see something like this.

Click the button to “Get An Invitation” and it’ll generate a custom invitation code just for you. Copy the whole thing. Then click the “+ Join Pub” button in Patchwork.

There’s a limit to how far gossip will travel through a network of people, and the bartender at a pub is just another “person” in the chain. Because of this it’s good to connect to a few pubs. Also, it spreads the load.

Note: If you’ve already got a friend on Scuttlebutt, ask them what pub(s) they follow. Otherwise it’s possible that you’ll be out of range of each other, so to speak.

The pub’s you’re currently connected to are listed on the left side if you click on “Public”.

Getting all the Gossip

As soon as you connect to a pub or start following a person Scuttlebutt will start syncing down all the “gossip” they have for you, and pass on any “gossip” you have for them. *The first time you connect to a pub server there will be a lot to download. * So, give it some time.

You’ll see some channels listed in “Active channels” on the left, but the “More” menu up at the top has a “Browse All” option under “Channels”.

Find a topic that looks interesting and start reading. When you’re ready to “Publish” remember that it uses Markdown formatting.

Remember, it doesn’t matter if you’re online or not. You’ll still see all the images, and you’ll be able to respond to posts and create new ones. The next time you connect to a local person or a pub server everything will connect up. When you’re online this will happen constantly, and responses can appear very quickly.

NOTE: There is no edit. There is no Undo. There is no delete. So, use your spellcheck, actually look at the Preview (When and publish mad.

Linking To Things

Sooner or later you’re going to want to link to some web page. With markdown formatting that’s just [display text](destination url)

How do you link to other messages in Scuttlebutt though? Well, first you need the message id. Right click on a link to the message you want to link to and choose “Copy Message ID” Then make a link just like a normal url link but use the message id as the destination url.

Profiles are a little different. A profile is a feed for a single person. So, in that case you want to use “Copy Link Ref” For example, if I wanted to link to André’s profile I’d say [here's André's profile](@QlCTpvY7p9ty2yOFrv1WU1AE88aoQc4Y7wYal7PFc+w=.ed25519)

I wanted to share a really interesting conversation with a friend of mine who wasn’t on Scuttlebutt yet, so I right clicked on the first message in the thread, chose “Copy External Link” and then messaged them that link. You could Tweet it or post it on Facebook, or whatever. The link goes to a public site where you can see, but not interact with, posts on Scuttlebutt.

It should be noted that people can indicate that they don’t want their stuff shown on public sites or in search results on sites like Google.

Stay Happy and Safe

Don’t worry, if come across someone whose views make you uncomfortable. You can always block them, and you’ll never receive any of their posts again, and they won’t get yours either.

Here’s how to run it on multiple computers. Just remember to never run it on multiple computers at the same time. ↩︎
The official scuttlebutt markdown reference is here but it’s layout is terrible, and it doesn’t show the results. ↩︎

Do Social Networks Need Companies?

Fri, 22 Dec 2017 09:37:51 -0500

I’ve been thinking a lot about Scuttlebutt lately (see my Why Scuttlebutt post), and Srol just wrote a great post about how Mastodon makes the internet feel like home again.

There’s a lot of good reasons for people to use tools like them for socializing online, and I don’t want these services to just wither as their users wander off. I want there to be options that aren’t controlled by large companies, but at the same time services that require servers (like Mastodon) need someone to pay for those servers. And while Scuttlebutt doesn’t need servers, the “pub” servers do play an important role. I find myself wondering what is required for a social network to succeed? Are businesses a critical part of the equation?

I think yes, and no. I think sites like Patreon its like, have shown that people are willing to support the people and projects that are important to them. So, I think that from a purely financial standpoint that no we don’t need the corporate money to keep these spaces afloat. Also, hosting costs for distributed systems like this are dirt cheap, and getting cheaper. There are a million people using Mastodon on servers paid for entirely by people who just feel like it.

At the same time corporate presence helps with the legitimacy of young networks. When major businesses establish a presence on a network it reinforces the idea that this is a “real” place, and that it’ll probably be around for a while.

From the business perspective, social networks aren’t great for selling things (instagram ads seeming to be the major exception to this), but they’re great for supporting your customers and finding like-minded people. Think, for example about what REI has done with their Opt Outside campaign.

Small companies, like indie software developers, survive because of their social interactions. They can’t afford the big marketing. So they make human contact, and support their customers, and help them to succeed in their business, or play, or whatever. And the customers appreciate it. Many of us become fantastically loyal to a product or company specifically because of the social interactions we have with the people behind them.

I look forward to getting on to Scuttlebutt and seeing what new things people have had to say, just like Srol looks forward to getting on Mastodon. Having to then switch to Twitter to ask a question of some developer whose software I use… it’s not hard, but it is a barrier, and it also means i’m going to have to deal with whatever’s going on “over there”.

I love Twitter, but if I’m not speaking with the Esperanto people there I’m pretty much guaranteed to get stressed out with some new political BS, and Facebook has always annoyed me.

But, it takes a lot of effort to for a company to have an effective social presence on a network, all that effort isn’t cheap. There’s got to be a reason why it’s worth the effort to have a presence there. They’ll come, if the people are there, of course, but the question on my mind, is will it help the people to come, or stay, if the businesses are there?

Do the creators of need to think about how companies could derive value from their platform? Not for any financial benefit of the creators, but as a tool to help the platform thrive.

I don’t think McDonalds, for example, being on Twitter devalues the Twitter experience in any way. I don’t follow them. They don’t affect me. I do think that the fact the companies I do care about are on Twitter enhances the experience for me. Is there a downside to the users to making the network more useful to those companies?

To be clear, I am explicitly not talking about allowing them to put ads in front of users, or charge for anything, or directly recognize revenue in any way. I’m talking about helping them to know that their presence on the network provides benefit to their company. Maybe it’s just knowing they got the word out about something important. Maybe it’s supporting their users.

I think maybe we should be thinking about the companies, if we want to see these new networks survive to maturity.

Why Scuttlebutt

Wed, 20 Dec 2017 22:35:40 -0500

I fell in love with the scuttleverse because of the people who are inhabiting it. Regardless of UX/UI, I continually come back because here I found people discussing practical ways of building their own airships, and what life is like doing guerilla gardening in Berlin or living in a self-reliant shack on top of a lava flow. There’s a distinct social anarchist bent to the discussion, and folks are not only discussing alternate societies at length, but also have the skills to realize them. – Zack! -> here

The other day André Saltz wrote about A Plan To Rescue The Web From The Internet, which had some good points, wrapped in a lot of… extra that tended to make my eyes glaze over. Before that he explained how the web has been dying since 2014. I definitely recommend you read the latter.

The heart of André’s post about saving the web is important though. Instead of trying to restate his thoughts I figured I’d give you mine on why you, like André, should care about Scuttlebutt, and the similar new ideas that are emerging and trying to take the internet back from the highly controlled walled gardens of Facebook and their ilk.

Once Upon A Time…

Once upon a time the web was a free-for-all. It was glorious. It was ugly. It was filled with failed and successful experiments. Every page looked and worked differently, but you could at least count on there being links you could click on that would take you somewhere. Making pages required learning some “HTML” thing, but then we got blogging software got better until we had things like WordPress which made that problem go away entirely.

It also wasn’t filled with ads. You didn’t have to log in, or launch an app to see the contents of a site. Maybe you used bookmarks. Maybe you used used an RSS reader. Regardless, you read the stuff you wanted, in the way it was intended, and it was good; occasionally ugly, but good.

More Recently…

More recently we got Facebook. I say “Facebook” but really I mean any of the similar walled gardens than have come and gone, and the future ones that will come and go again.

Facebook and friends have done some very good things. They’ve made it easy to see all the posts from the people you care about in one central place. The pages have a consistent navigation, and while it’s hard to say that Facebook is gorgeous, It is fairly easy on the eyes.

Unfortunately the things you upload are only technically yours, and once they got everyone on the site, they changed the rules.

The Oatmeal’s comic on “Reaching People On The Internet” summed it up nicely.

Eventually Facebook will stop being “the cool site”, and everyone will move on to something else. The doors will close and billions upon billions of posts, photos, memories, and well-wishes will be lost. There’s already evidence of this starting with younger generations and Facebook.

Enter Scuttlebutt

Scuttlebutt is one of a number of new ideas emerging to address the problem of these walled gardens, government censorship, corporate BS, and more.

Technically it’s a protocol, like the HTTP protocol that most of the internet is built on. Some people use it share blog posts and Tweets. Some people use it for chat. Some people build games. Some people use it to serve data for specific applications.

Scuttlebutt has some huge differences though:

Once it’s been shared, nothing can be lost, or deleted, or censored.
- links to old articles and blog posts never die
- great for people living under oppressive regimes
- politicians can’t take back stupid or racist statements
- companies can’t walk away with years of your posts and images.
everything is silently encrypted
- private messages are truly private.
it’s decentralized, and works offline
- millions of people in rural and/or poor areas don’t have constant, or fast, internet connections.
- no company or government can control it.
- no-one can act as a gatekeeper

Patchwork is one of the many applications that run on Scuttlebutt. It’s one of the social apps, but really they’re more akin to web browsers than “social apps”. Some people like this one. Some people like that one. They all look a little different, but they generally let you do the same thing.

So what do you do with it?

Using Patchwork is conceptually similar to Slack or irc: There are public channels that are topics for discussion: #games, #birds, #boats, #esperanto, etc. But there are also public channels that are blogs: #spider-farm being an oddly enjoyable one that has nothing to do with spiders. All of these posts can be filled with images, and attachments, that work perfectly offline. The big difference between it and Slack or IRC is that most people are posting thoughtful multi-paragraph things, not chatty one-liners.

You can also send private messages that are truly private thanks to the encryption working behind the scenes.

It’s also a little like Facebook. You have a profile page, and a network of people you follow, and they have a network of people they follow, and you can see who you have in common.

But, like real life, you can only send a message to someone if there’s a chain of connections between you and them. This is because Scuttlebutt transfers data using the power of Gossip. No really, that’s the name of the protocol. Messages pass from person to person across the network, but you don’t have to download every message for every person. It’s all about the network of people you’re connected to, and who they’re connected to.

And that, is where the “distributed” and “offline” aspects come in to play. I can turn off my wifi, and still read other people’s posts, still see images, even reply to posts, create new ones, and update my profile. When i get back online everything all of that will go out to the people I’m connected to and they’ll see it the next time they connect.

But, it’s better than that sounds. Imagine I’m in a rural area but one of the people in my Scuttlebutt network comes by. We can connect over a local network (think AirDrop). I can get the latest stuff she has, and she can get the latest stuff I have. Every time one of us connects to another friend the information will continue on until one of us connects out to a wider network like the internet.

This sounds like it’d be very slow, but when everyone is online, message transfers are actually very quick. And when you’re in the middle of nowhere and it takes two days for a friend of a friend to connect to the internet, it’s still a lot better than no connection. Plus, you can still use the system in between visits.

Right now, Facebook is useless to the 4 billion people with poor or intermittent connectivity. Imagine if those people started using a tool like Scuttlebutt before Facebook was able to get its hooks into them.

[quick implementation note] you don’t have to know someone on the network to use Scuttlebutt. There are “pub servers” whose job is to be someone you can connect to, and help you share “gossip”. Connecting to one is generally the first thing you do when you start up a new client.

And one more thing

Right now the internet is a toxic place for those of us in the US. You can’t look at any of the social networks, without encountering a constant stream of stress-inducing pro or anti-Trump rants. Wouldn’t it be nice to have a place online where you could go, and be social with others without all of that?

On top of all that, the people on Scuttlebutt right now are actively thinking about ways to make things better: their lives, the internet, everything.

Watch the video overview. Grab a copy of Patchwork, and join me and others in an ad free oasis filled with some pretty cool thinkers.

P.S. Patchwork is stable and good, but we’re still figuring out how best to use it. It’s like the early days of web browsers. I recommend you don’t install it on your work computer, because it likes to only be run on one computer at a time, and if they suddenly fire you (or burn to the ground), you’ll loose the computer with the keys to prove your identity, and decript all the private stuff you’ve shared and received. It’s not hard to share the same identity on multiple computers though.

P.P.S The links to Scuttlebutt posts and profiles in this article are not links to Scuttlebutt itself, but to a read-only web view into it.

How to use the same Scuttlebutt identity on multiple computers.

Tue, 19 Dec 2017 22:43:35 -0500

v2.1

(Note: Manyverse / mobile users please see the warning at the end.)

Offically Scuttlebutt doesn’t support posting from the same identity on multiple computers (as of Dec 2017). Unofficially, it’s easy but requires a little bit of care. In practice this means never run the Scuttlebutt client on two computers at the same time.

The gotcha is that if you post from both computers before the changes of one have had a chance to replicate to the second via scuttlebutt one or both of your feeds will get screwed up and other people won’t see some of your own posts ever again.

Note: These instructions require using the command line. I’ll show you how to do it on a Mac. Hopefully that’ll be enough of a clue for Other OS’s too.

Step one.

On the computer where Scuttlebutt is already running, Take your ~/.ssb/secret and make a backup of it in some secure encrypted location like 1Password, because you really don’t want to loose that and you don’t want to give folks keys to your identity.

How?
Open your Terminal app and type

open ~/.ssb

(then return). A window will open up in the finder showing the contentns of your ~/.ssb directory. Copy the secret file from that directory and put it somewhere safe. Then send it and the gossip.json file to the 2nd computer.

Step two

On the 2nd computer create a ~/.ssb directory in there and put a copy of your secret and gossip.json files in there.

How?
Open up your terminal app and type:

mkdir ~/.ssb
open ~/.ssb

Now drag a copy of your secret and gossip.json file into the window that just opened.

Step three

Confirm Patchwork is off on the 1st computer. Boot Patchwork on the 2nd computer. It will ask you to fill in a profile. DO NOT FILL IT IN. Instead click “Cancel”. Then wait. It’s going to have to re-download everything you had before, including your profile. After it’s done syncing quit, then relaunch Patchwork to make it re-attempt to connect to other pubs. Currently (Dec 2017) it doesn’t always sync with all the pubs you were connected to the first time it loads.

WARNING

Do NOT make Patchwork an app that opens at startup. Do not start Patchwork immediately after waking up a computer. Always quit patchwork on one computer before opening it on the second one. Then wait for all the posts to finish syncing before you publish anything or update your profile.

Manyverse users

Currently the SSB Mobile client Manyverse is still very new. Mobile devices add a whole bunch of weird edge cases to how and when things function. My personal advise is to not try sharing your identity with a mobile device at this point in time. In theory, as long as you let the posts from your computer(s) sync to your mobile device before posting from there, and vice-versa, you should be ok. That being said, the consequences of this going wrong are being forced to abandon your old identity because 1/2 of the world can’t see any new posts from it. It’s just not worth the risk.

I don’t have an Android phone so I can’t test it. Instructions are available in Scuttlebutt though if you’re willing to take the risk.

100(ish) things

Sun, 01 Jan 2017 16:23:34 -0500

Many would not guess it, but I am a minimalist at heart. I don’t like looking around and seeing all the crap I’ve accumulated. So this year, I’m going to do something about it. This year, I’m working towards only owning 100(ish) things, and I’d like to encourage you to too.

The 100 is easy. The “ish” requires some explaining, but I feel it is the key to making this workable.

What follows is my guidelines for paring down to 100ish items. If that sounds like a goal you’d like to achieve too, keep reading.

ish #1

100 is a target, not a hard and fast rule. If I whittle it down to 104, and getting rid of those last 4 would be painful, I’ll stop at 104.

ish #2

Heath, safety, and “regular maintenance” items don’t count. Your first aid kit doesn’t count, even if it has 1000 items in it. Your tooth paste, soap, and tooth brush, don’t count. Your pills don’t count. Health and regular maintenance aren’t just limited to you though. Your car needs regular maintenance, and checkups too. Tire guage, Snow Chains for your car, Window Breaker, Snow Brush… All safety / maintenance items. Go Bags are also a form of safety item. Dog toys? Maintenance item (also, they’re not really yours), but maybe your dog(s) don’t need all those toys.

You will need to be careful with the “regular maintenance” items though. It’s easy to go “oh yeah i need that for ____” when it’s more a “want” or a “nice-to-have”, instead of a real need.

ish #3

Atypical Activities: Limiting yourself to 100 items will free us up mentally, but it’ll hamper our ability to do the non-everyday things that bring us joy. Camping, as an example, requires special equipment: sleeping bag, camp stove, water filter, etc. You should not have to give up camping, to enjoy downsizing. The items required for you whatever activity you love in your off time: they don’t count, but you still have to sit down and ask yourself which ones you actually need.

Bonus items!

Anything digital doesn’t count. It takes up no physical space. You can have 10,000 books!

Gray areas

To me, pills like Ibuprofin, count as health and maintenance. Any in the first aid kit, or medicine cabinet I won’t count, but if I choose to carry an extra bottle in my backpack? That bottle will count.

Groupings are complicated too. A keyring has many keys, but most people would call it one item. An Altoids tin filed with useful everyday items? Maybe. A box filled with crap you can’t decide on? Probably not one item.

Shared items. I don’t feel it’s right for me to get rid of items that my wife uses regularly too (like the stereo), but do I count that towards my 100? I dunno. I can talk to her about getting rid of items we don’t use anymore.

Work items. A woodworker needs a lot of tools, but maybe, they don’t need all their tools. Could you get your job done well with fewer things? Try working without them for 6 months. If you find you don’t need them, get rid of them.

Getting to 100(ish)

How each of us gets to 100 is going to be different. For me it’s going to start with Marie Kondo’s advice in The Life-Changing Magic of Tidying Up (It’s available on Audible too). At the heart of her teaching is a simple question: “Does this item bring me joy?” If it doesn’t, you get rid of it. I’d modify that slightly: “Does this item bring me joy? Is it actually required?” For example: I consider having a backpack to be a requirement. I use it to carry my laptop to work safely. Fortunately, I love my backpack.

My plan is simple. Each weekend I’ll address a room, or part of a room. I’ll do as much as I can find time for. I’ll choose the items I want to keep, and donate, or discard the rest. Once I’ve finished going through the house, I’ll go back, start counting, and repeat the process until I’m down to 100.

Staying at 100(ish)

I, like many of you, lust after things. I hear the siren call of “better”, and that’s ok. When you only have a few items it’s important to make sure they’re the best they can be. So, feel free to window shop. Just don’t pull the trigger unless you know that it’s an improvement over what you currently have, and know what you’re going to be getting rid of to compensate.

In the end, this will mean spending more money on fewer, but better things. In my experience, this will leave you with items that you really value, and appreciate having around.

To summarize

Let’s work on getting rid of things we don’t need, but keep ourselves safe and well cared for in the process. Only keep the stuff you really love, or really need. Get rid of all the “maybes”.

If this sounds good to you, but you’re still on the fence, consider these 7 reasons that keep people from getting started with minimalism.

Dear Esperanto Beginner

Thu, 03 Nov 2016 21:43:23 -0400

Dear Esperanto Beginner:

I love Twitter, butI have not found a good place for a beginner to practice their Esperanto there. So, I made @praktiku.

Say hello to @praktiku and practice with me. You don’t need to be skillful, just willing to practice.

Kara Esperanto Komencanto:

Mi amas Twitter, sed mi ne trovis sekura placo por komencantoj praktiki sian Esperanton tie. Do, mi faris @praktiku.

Diru saluton al @praktiku, kaj praktiku kun mi. Vi ne bezonas esti lerta, nur volanta praktiki.

Keeping a great Changelog

Sun, 03 Jul 2016 13:03:55 -0400

Changelogs are an invaluable, and often neglected part of any software project. So, how do you do that?

A good changelog helps you users to understand:

Why they should care about your latest version
If any of your changes affect the problems or frustrations they’ve been having.
If there are any changes that might affect how they use your app / library.
Why your efforts are worth their continued support.

A great changelog does all that, and shows the personality of your team.

Shifty Jelly’s Pocket Casts is notorious for their fun, and informative changelog entries:

Equal Opportunity variable speed playback. Why should MP3s have all the fun? Welcome AAC & OGG! * Bzzz. Bzzz. You can now choose which podcasts to be notified of.

Slack’s been doing a pretty bang-up job too:

Fixed: The app now automatically scrolls down when you begin writing a file comment, giving your precious fingertips much needed beauty rest. * Fixed: Time zones were sometimes shown with incorrect deltas. Now your coworker who is 5 hours ahead of you will no longer simultaneously be 8 hours behind you.

I can’t overstate how valuable it is to have a Changelog with personality. As soon as you see that one of the apps you use has a great changelog you look out for them, and always stay on top of what they’ve fixed and added. Then you start spreading the word, because not only did they add good stuff, or fix that really annoying bug, they made you smile along the way.

A Changelog with personality helps build evangelism for the thing you’ve spent so much time building.

The guts of a good Changelog Entry

It must speak in terms users understand. Most of them won’t be intimately familiar with your source code. Don’t use internal jargon. If a bug is fixed, speak in terms of the actions that caused it, or the behavior it exhibited, but not the specific classes, unless you absolutely have to.
It must be knowledge that’s useful to your users. Speak to the features and flaws that affect your customers. Users don’t care that you refactored some unit test, or reformatted your comments.
It has to be at the right level of abstraction. Even if your writing an open source library. The Slack timezone bug above was handled perfectly. They could have mentioned which class & method had the bug, or the conceptual flaw that caused the bug, but that’s all too fine grained for a Changelog. Instead, they spoke at a higher level of abstraction.

Changes need to be grouped by type

Group your bug fixes. Group your features. Group “all the things!”

Imagine a user who’s been particularly frustrated by a bug in your app. They’re going to open your changelog and immediately try and find out if you’ve fixed it in this release. Help them. Don’t frustrate them further by making them hunt for it in a jumble of features, fixes, and changes.

Dates are important

Versioning your software is great, but dates are important too. When did version 6.0.0 come out? Did I have that problem before then or after?

Additionally, not everyone in the world keeps dates in the same format. 06-08-16. Is that August 6th or June 8th? It depends on who’s reading it. Year Month Day is the only one that makes any logical sense no matter where you are. XKCD even had a Public Service Announcement about it.

To summarize

Write at a high level of abstraction
Speak to things that affect users, not developers.
Group things so that people can find them easily.
Add some personality.

Want an easy tool to help manage this?

Check out changelog_manager. It’s a free and open source tool to help you easily generate high quality Changelog entries.

Why you can’t auto-generate your Changelog

Why you can't auto-generate your Changelog

Thu, 30 Jun 2016 08:28:07 -0400

Let’s start by taking it as a given that a Changelog file is something very valuable that every product should come with. Even if your “product” is a library for other developers.

With that in mind, the question rises of “How can I make it really easy to generate one”. Many developers have had exactly that thought. There are many free and some paid solutions that will “Autogenerate your changelog from your git commits/tickets”. The simple fact is, that no matter how well they’re written, you shouldn’t use any of them.

A good Changelog entry has…

A good Changelog entry has three primary aspects

It’s at the right level of abstraction. Consumers of your product don’t care what files you tweaked or how. They care about the fixes and changes you’ve made that may impact them.
It needs to be knowledge that’s useful to the consumer of your product. It’s a simple judgement call, but it’s one that has to be made.
It needs to be written in a way that people who either aren’t geeks, or at least aren’t intimately familiar with your codebase can understand.

Changelogs from commits

Commits are at the wrong level of abstraction

A git log is filled with commits like: “ensured current_and_future_campaigns returns a relation”, or “cleaned up whitespace in User.rb”, or “fixed expected aspect name in update test for locations_controller_spec” These are useful to other developers on the project, but they aren’t things that are useful to the users of your product.

In short, they contain too much detail, at the wrong level of abstraction.

Commits are messages from one developer on a team to another one

They’re not messages to your users, and they shouldn’t be.

Commits frequently use jargon, and references to specific elements of code. This is absolutely fine, but it’s probably meaningless or useless to most of your consumers.

There’s no point

If I wanted a geek level listing of all the changes in your git history I could just ask git: git log --oneline Plus, git will let me slice and dice that information sixteen ways from Sunday.

You can’t edit them

As Commits From Last Night proves. Commit messages frequently aren’t written in a customer friendly way. Even if you’ve got very polite developers, everyone makes typos. You can’t edit the old commit. If you want a changelog that looks professional you’re going to have to manually edit it, the same mistakes every single time you generate it.

Tickets are at the right level of abstraction

…but they rarely have titles that are appropriate for a changelog.

How about “Item Finder - Page gets wonky after searching for content that doesn’t exist - plus 404”, or “Something’s eating up all the ram and taking down the servers” Not really appropriate for your changelog.

If you’re really following agile an agile methodology you have user stories that look like “As a I should be able to ___ because ___” and that’s no good for your changelog.

Some projects do take the time to curate their ticket titles. The results are almost usable as changelog entries too, but there are always exceptions. They’re generally worded well for the people who need to work on them, but not your consumers.

It’s a matter of human judgement

You want a changelog with the information that is useful to your consumers, and written at the right level of abstraction. This means people need to ask themselves some questions. “Do we need a changelog entry for this?”, and if so, “How do I summarize this change in a way that’s useful to our users?”

The first question sometimes eliminates information, through curation. That’s something tools can’t do. The second question changes the form of the information conveyed. It was directed internally, now it’s directed externally.

Want an easy tool to help manage this?

Check out changelog_manager. It’s a free and open source tool to help you easily generate high quality Changelog entries.

Keeping a Great Changelog

On Being A Manager

Fri, 13 May 2016 08:15:00 -0400

At its core, being a manager is about power. I feel that many managers fail to understand what that power is for.

A manager is a lot like being the King or Queen of a tiny, tiny kingdom. The sovereign of a country can impose their will upon their people, but that’s not their job.

A sovereign’s job is to keep their people safe, happy, and prosperous. The more prosperous the people become, the more power they gain. The more power your people have, the more power you have. The more powerful and successful the people are the more powerful the sovereign becomes.

A good sovereign only imposes their will upon their people to protect them. A really good sovereign convinces their people to take the action themselves.

The people above you made you a manager because they believed in, and trusted you. They grant you power, but that power is titular, until you have the support and trust of your people. Your people’s success, and happiness, proves that trust was well placed. It encourages those above you to have more faith in you, and trust you more. That is your voice at the table. That is your strength in negotiations big and small. Your true power is to influence the future of your company to support your people.

There are times when you will be asked to bring your people unhappy tidings. If you’ve done your job, your people will trust you. They will trust that you will help them through the unpleasantness. They may not agree with you, but they will trust that they have their best interests at heart. They’ll trust that will do everything you can to protect them.

Internal threats are the only time a manager, wields their power downwards. If your people are threatened from within, you try and fix the problem. If the problem can not be fixed, you exorcise it. Sometimes the problem is a person. Sometime’s it’s a process.

When the threat is external, you raise awareness, of the problem, and its consequences. Diplomacy play a key role in this. Few of us are particularly good at diplomacy, so do your best, and learn from your mistakes.

Your people give you power. Protect and encourage them. Use your people’s power to reinforce that protection an encouragement within your world. Spread their influence through success.

Work with your people to build their power and trust in you.

Weeding Wednesday

Mon, 09 May 2016 07:02:45 -0400

“Follow Friday” has been a longstanding tradition on Twitter. It’s a great idea. People you follow, make curated recommendations of good content. Well, the world needs balance, and I’m instituting Weeding Wednesday.

Weeding Wednesday is a day for reducing internet noise.

This Weeding Wednesday watch your Twitter feed from a different perspective. Don’t look for the great posts. Look for the “meh” posts, then unfollow anyone with a low cool to meh ratio.

Spend a few minutes scrolling through the first couple pages of your email inbox. Unsubscribe from things you don’t want. Filter out things you don’t need to see all the time into different folders.

Find places where “weeds” have crept into your media consumption, and clean them out:

Twitter
Email
Instagram
Facebook
Podcasts
RSS Feeds
Everywhere

Your next week on the net will be higher quality, with less overload. I guarantee it.

Creating a Terminal Emulator from Scratch (where to start)

Sat, 30 Jan 2016 10:13:19 -0500

Where to start creating a Terminal Emulator from scratch

Before I get started I need to link you to this great answer on the Unix & Linux Stack Exchange which explains the differences between a Terminal (tty), a Console, and a Shell. That knowledge will be key to writing a terminal emulator.

VT100 (and beyond)

Setting the stage with a little background.

Most terminal emulators claim to be VT100 emulators. VT100 came out of DEC somewhere around 1977. There were a number of subsequent versions (52,102,220,330,420,510,520). The problem is, that VT100 is a rather limited subset of what people expect:

VT100s have no function keys.
VT100s do not do color.

But there is some relevant stuff that came out of this. Eventually the geeks of the world said “Hey, we should probably standardize this stuff”, and that resulted in these standards:

ECMA-35, Character Code Structure and Extension Techniques (ISO/IEC 2022:1994)
ECMA-43, 8-Bit Coded Character Set Structure and Rules (ISO/IEC 4873)
ECMA-48, Control Functions for Coded Character Sets, (ISO/IEC 6429)

Today XTerm is the 500lb gorilla in the room. Modern xterm (as of 2013) implements 546 control sequences. Most VT100 emulators (VT102 really) only implement 68. That being said, there are a good number of competitors to xterm which claim to emulate “most” of XTerm’s controls, the reality is that “none of the other terminal emulators emulates ‘most’ of xterm. Instead, they implement the most commonly-used control sequences, and there are differences between them”.

The takeaway is that, XTerm may be bad-ass, but you don’t need “most” of it to create something that’s very useful. Even better, you can use XTerms list of control sequences as a todo list of things to implement. If you want to create something that is just functional enough to use Vim & Emacs in, then all you need is VT100(ish).

Some Example Projects whose source you can explore

hyper (GitHub here) looks like a promising step into the future for terminal emulators / interactive shells. It’s a node.js app with an Electron front end. Because its UI is html, the possibilities open to it are pretty limitless. The things that TermKit promised us back in 2011 can finally be realized with this, or some clone / descendent of it.

iTerm 2 is arguably the best OS X terminal emulator available. It’s written in Objective-C.The source code is here on Github

There’s Terminal.py which is a terminal emulator written in pure python. Being Python I suspect its source code would be a bit easier to wrap your head around (less low level stuff to deal with relative to an Obj-c codebase). It claims to support XTerm emulation, but I can’t say how much of xterm it actually emulates.

Terminal.js. This one’s a little different: Node.js sets up a wee server on your desktop and you interact with it via a Terminal.js which you load up in your browser. There’s a demo app for it. Not sure what exactly that gets you.

And of course, there’s XTerm but I suspect that it’s not a great place to start. Too much functionality built up over too many years. I wouldn’t go there until I’d gotten a handle on the basics.

Credits

Much of the info here was gleaned from this page on vt100.net, and the XTerm FAQ.

Adding Press and Hold Characters to macOS (OS X)

Sun, 13 Dec 2015 00:00:00 +0000

EDIT: As of Monterrey Apple has completely locked down the files you need to edit.

There are 2 ways I know of to do this, and neither of them is as good.

use TextExpander. You can tell it that when you type cx to “expand” it to ĉ. You’ll probably have to copy the character you want from here or any other page with it. Then do the same for all the other characters that need ˆ. Here is a public snippet group with the Esperanto Diacritics that I’ve put together. Just type cx to get ĉ, and so on for all the characters that use the ˆ or ˘ diacritics.
use Keyman. They specificaly have a QWERTY Esperanto keyboard layout. However it’s not what you think. It doesn’t give you press-and-hold menu, and it doesn’t actually let you type a ĉ. what it does, is exactly the same thing as Text Expander, only with +h or +x. Basically, what you get is an incredibly limited free version of Text Expander, that only works with the QWERTY keyboard layout.

In short, buy Text Expander, because you’re going to get a ton of other cool functionality and it’ll work regardless of what keyboard layout you use.

OS X makes it easy to type accented characters by simply holding down the letter you want accented. If you hold down c (for example) you’ll see this:

Well, I do. You probably don’t see that 4th option: “ĉ”, and that’s what this post is about. I needed to add that, and others to support typing in Esperanto without switching to a different language keyboard. This technique is also useful if there is a language keyboard you want to use but it doesn’t have the Press and Hold support you want.

Here’s the deal though. The files you need to edit, are in an area of the system that Apple has locked down so hard that even the root user can’t touch it. Normally the root user can do anything it feels like. You’ll need to temporarily disable System Integrity Protection and run a few commands in the terminal to replace the XML file that defines what characters show up in the Press and Hold menus. You’ll need a developer’s text editor (not Text Edit), and knowledge of how to copy and move files on the command line.

If that’s all gobbledygook and/or scary to you, then you should probably stop here. I’m sorry. Apple’s made this a geek-only operation.

Still here? Good.

Here Be Dragons

There’s a system folder in which You’ll find a variety of files. We need to modify the file in there that corresponds to your default language. If you’re reading this your default language is probably English, so you’ll want to Keyboard-en.plist (“en” for English). If not, find the file with the 2 letter abbreviation that corresponds to your system’s language.

In El Capitan this folder is here

	/System/Library/Input\ Methods/PressAndHold.app/Contents/Resources/

In Sierra this folder is here

	/System/Library/Input\ Methods/PressAndHold.app/Contents/PlugIns/PAH_Extension.appex/Contents/Resources/

If you just want to add Esperanto character’s to your English Press and Hold menus then download this file (right click, save as Keyboard-en.plist) and skip down to the part about Disabling System Integrity Protection.

Modifying your Press and Hold plist file.

Once you’ve found the appropriate file copy it into another directory and start editing. You can’t edit it in place.

First find the <key>...</key> line that corresponds to the key you want to edit. When I went to add a capital C with a caret over it I found the <key>Roman-Accent-C</key> line, then edited the <dict>...</dict> block below it. I’m fairly certain that the first character must not be changed. The other characters are the ones that will show up in the Press and Hold pop-up. Modify them however you want. You can even put emoticons in there. I just modified to have the Ĉ you see below. Note that there are spaces between each character. What happens if you string multiple letters together without a space? Dunno. I’m betting you’ll get an entire word for an item in the menu.

	<key>Roman-Accent-C</key>
	<dict>
		<key>Direction</key>
		<string>right</string>
		<key>Keycaps</key>
		<string>C Ç Ć Č Ĉ</string>
		<key>Strings</key>
		<string>C Ç Ć Č Ĉ</string>
	</dict>

Once you’ve modified all the uppercase and lowercase versions of the letters you want the pop-up for it’s time to replace the original. I recommend making a back-up first. Just in case.

Temporarily disabling System Integrity Protection

You’ll probably want to print out / write down these instructions because you won’t be seeing them after restarting.

Restart your computer. Hold down the “Command” key and the “R” key when you hear the restart sound. You’ll see a progress bar as it boots you into Recovery Mode. Ignore the window listing backups and disk utility. Click on the “Utilities” menu, and choose Terminal.

Disable SIP and reboot (to make it take effect).

csrutil disable; reboot

sudo cp path/to/your/edited/Keyboard-en.plist /System/Library/Input\ Methods/PressAndHold.app/Contents/Resources/Keyboard-en.plist

or this for Sierra & High Sierra

sudo cp path/to/your/edited/Keyboard-en.plist /System/Library/Input\ Methods/PressAndHold.app/Contents/PlugIns/PAH_Extension.appex/Contents/Resources/

Reboot and go back into Recovery Mode. Open up the Terminal again, and run

csrutil enable; reboot

That’s it. You’re done. Now your customized popover will be available to any keyboard in your default language.

On offering up Grad School Recommendations

Sat, 05 Dec 2015 00:00:00 +0000

I was recently asked to provide a letter of recommendation to a past coworker who is trying to get in to grad school. The experience was excessively time-consuming, and left me with little belief that any of these schools are worth attending because their systems were (with one exception) all painful to use, and (with no exceptions) all looked like shit. If you can’t teach your students how to build a decent system for letting people upload recommendations, then how the @#$% can I expect you to teach anyone graduate level concepts? I know that some of the following schools are actually quite good, but they show no evidenced of it in the code they offer up for professors and professionals to use.

Carnegie Mellon

asked my to put my letter of recommendation on “a letterhead” in PDF or Word format. Seriously? WTF does “letterhead” even mean in the digital age? You want me to paste my company logo at the top? In the age of paper this had meaning. It proved you’d spent money going to a printer in support of your company / institution. It was an easy way to help confirm the reviewer actually worked at the company they claimed to. Now? Now, it doesn’t mean Jack.

NYU’s

form a) has a full page of documentation on how to upload a recommendation letter b) is completely teacher centric, as though no-one would every come with a recommendation from a the world of gasp business c) is a 3 page process. Forces me to “Please compare the applicant’s academic ability to that of other students.” which makes me either lie (because I’m a manager not a professor) or choose “I prefer not to answer”, which would raise flags if I was reviewing this recommendation. Also, they made me “sign” the form twice.

Stanford, Cornell, and University of Michigan

all use the system for managing your account, but each ask different questions in different ways.

Stanford

mostly wanted me to prove I was a worthy reviewer and asked questions like “How many years have you evaluated people in this group?” and “Approximately how many people are in the group, totaled over those years?”

Cornell

did a surprisingly good job of making it easy for me to give them info that would be helpful to their evaluations, like a quick rating on Academic Performance, Intellectual Potential, Creativity and originality, and Motivation for graduate study.

University of Michigan

had a similar form but with even better questions which would not only help judge him, but his potential usefulness to the school with the typical tasks a grad student is asked to perform.

Boston University Metropolitan College

only allows 10 characters for your title. I put “Tech Lead” because it sounds better than just “Manager”, but then at the bottom of the form I realized they meant Mr. / Mrs. / Dr. / etc. They don’t allow enough characters in the phone field to put in an international number with any formatting. They also make you agree to a typically large “Terms of Service”, which of course I didn’t read. They were, however, the first school that actually grasped the idea that people outside of academia might be providing reviews.

Columbia’s

was the least painful, but very meh.

U Mass

let me know that “When entering your recommendation, please save your progress every 15 minutes, or changes may be lost.” which doesn’t speak highly of their computing department if they can’t keep their system from blowing up every 15 minutes, or figure out how to use that fancy “AJAX” technology that’s only been on the scene for 10+ years. They then ask me to fill in this sentence “I would rank this student in the top _____ % of approximately students I have taught in _____ years. And, of course, after filing it with “NA” it decided it didn’t like it (when I attempted to upload a PDF ?!?!), so I put my cursor in a field and used the delete key, which took me to the prior page, and when I went forward again it lost all my data, just like the form promised. So, I ranked him in the top 100% of the 0 students I’ve taught in the past 20 years. They also asked me for my “Title” but after the last one I have no clue what they meant.

After finally managing to upload the PDF it suggested I click the “View” button to make sure it looks correct. So I did, and the browser promptly blocked their Pop-Up window. Pop-Up blockers have been shipped on by default in browsers for how many years now? If their recommendation form is any indication U Mass is an absolutely shitty place to study computer science.

University of Southern California’s

process is relatively painless, and gathers some useful info, but also allows you to upload your review in “.jpg, .pict, .gif, .bmp, .tif or .png format” in addition to normal text things… which is somewhat disturbing.

Software worth recommending

Sat, 14 Nov 2015 00:00:00 +0000

There are lots of great tools out there. Far too many to try. Here are the ones that I’ve tried, and found worth recommending. Mostly they’re

OS X

Developer Things

Quiver is a “Programmer’s Notebook”. I’ve recently switched to it from CodeBox which seems to have been abandoned by its developer. I’ve got some minor quibbles with Quiver, but overall it’s pretty nice and I’ll be bringing all my code snippets and reference material over to it.

Dash is excellent for anyone who needs to search language / framework docs semi-regularly.

MacVim because I can’t fathom why anyone who wants to use vim on a mac would limit themselves to using it in a terminal when they don’t have to.

Kaleidoscope It’s a great visual diffing app. If you use diff on anything resembling a regular basis, you should give Kaleidoscope a try.

Markdown

Marked 2 for previewing Markdown files and exporting them to other formats, this is the app you want. That being said, I’d only recommend it to people who really love Markdown. People who only use it occasionally probably don’t care enough to justify buying this.

Deckset It’s presentation software, but you build your presentations with Markdown. Yay. Not as full featured as I’d like, but it’ll let you build very nice presentations.

Flow Charting

OmniGraffle is the king of the flow charting apps. It’s awesome. End of story.

But…
Monodraw has earned a special place in my heart. Recently I had to wrap my head around a complicated data flow. When I was done, I created a flow chart in Monodraw and pasted it into the source code so that the next time I have to look at that code I’ll have a nice graphic to guide me through it.

Miscellaneous

Noizio is great for noisy work environments. Turn it on, along with some music and you won’t make out anything your coworkers are blabbing about. And no I’m not suggesting making everything so loud as to drown them out.

Day One This is a really beautiful app, and the iPhone version is great. The companion app on the watch looks like a really nice addition too. I haven’t been using it much, but it’s the kind of app that makes you want to use it.

Pixelmator Screw Photoshop. Get Pixelmator. It’s affordable, powerful, and exceptionally well made.

DaisyDisk Helps you figure out what’s taking up your disk space. I don’t need this very often, but when I do it’s invaluable.

Skitch If you need to make and annotate screenshots, this is the app to use.

Bartender Helps address an excess of menu bar icons.

Transmit If you deal with FTP, SFTP, S3, or pretty much any other file transfer system on a regular basis, then you want this app.

Screenflow Excellent, easy to use screencast software, that lets you go back and add really useful annotations, highlights, and more.

Multiplatform

Spacemacs “The best editor is neither Emacs nor Vim, it’s Emacs *and* Vim!”. I love Vim. I envy the extensibility of Emacs. This is the first implementation of Vim (technically it’s Evil) on Emacs that has come even close to working. Normally they piss me off within 30 seconds. This has me wanting to take the time to figure out how to replicate my vim workflows in it.

Scrivener Writing anything of significant length? This is what you want. Be sure to go through the tutorial. There are a ton of powerful features hiding in plain sight. Out of the way until you need them.

1Password It’s the best password manager out there, and they’ve had their code independently audited by security experts. Don’t even get me started on how ignorant / stupid it is for people to not be using a password manager.

Vim plugins

The list of plugins I’m currently using is generally in flux. I’m always trying to improve my vim setup. Check my .vimrc for the lastest complete list. Here are some that I think are definitely worth sharing by all.

Vundle Best vim plugin manager I’ve found.

Fugitive Spectacular git integration. If nothing else, check out the GBlame command.

Tabular Align your text! Make things more readable. Check out this vimcast for a good idea of what you can do with this.

tcomment lets you easily toggle if a piece of text is commented out or not.

airline it’s the successor to Powerline.

expand region is a Vim plugin that allows you to visually select increasingly larger regions of text using the same key combination. Doesn’t seem like much but in practice has proven pretty nice.

vim-renumber For folks who like to edit markdown in vim. This will renumber ordered lists for you.

Command Line

Oh My Git The best prompt enhancement I’ve found to tell you what branch you’re on, if it’s been pushed or not, and tons more. That link’s to my fork of the project, which has some visual tweaks. The original is here.

git-wtf Helps you know wtf the differences are between your current branch and the upstream branch it’s tracking.

The Fuck Every time you type out some long command and then git is all “did you mean…” because you made a typo? Yeah well, The Fuck fixes that. It picks up on the suggested correction, and let you type fuck to execute the command you meant to type.

Static vs. Dynamic Blogging

Sun, 18 Oct 2015 00:00:00 +0000

You’ve got a lot of software options when setting up a blog. Over the years. I’ve used or tried most of the options including, but not limited to: WordPress, Jekyll, Octopress, and at least 3 custom built systems.

What follows is my thinking on the pros and cons of each option, and why I’m switching back to a static blog system (Hugo this time).

Dynamic Blogs (WordPress, etc.)

Dynamic blogs, like WP, have a lot going for them:

Easy to use
Lots of plugins
Great media handling
Usable from any internet connected device with a browser.
Great selection of themes
Instant publishing
Scheduled posts
Multiple Authors

So, what’s the downside? It seems like every few months one of our WordPress blogs gets hacked and Google starts warning folks it has malware. You have to constantly log in to update it, and every time you do you run the risk of hosing your database (admittedly a rare occurrence), or breaking compatibility with one of your plugins (happened a few times to us).

Another big downside is when you do happen to write something popular, and thousands of people try hitting your site at once. Many a WordPress (and similar) blog has gone down under the strain of success.

Squarespace would be an excellent option except for the $8+ per month, per site price tag. $24 if you want to be able to actually modify the HTML, CSS, or JavaScript. Maybe, if you only have one, but I manage 11+.

Static Blogs

There are notably good things about static blogs:

The fastest possible page loads.
Can withstand crazy high request loads
Zero maintenance or security worries.
Minimal hosting requirements
Markdown support
- you may not care, but I demand it of a blogging platform.

There are a number of downsides though:

Can only blog from home computer (without bullshit hoop jumping)
- Prose is the only decent exception I know of. Tinypress may be an option too, but they’re too new to say.
Multistep publishing
- run build script
- sync files over scp / rsync / ftp / whatever.
Generally weak media support
- no auto-resizing
- no media players
- have to think about where the images live
- very limited selection of plugins (if any)
Typically poor selection of themes
Limited layout capabilities
- they all use markdown, and Markdown can only produce a restricted subset of HTML.
Slow site generation
- Hugo is the only exception I’ve seen to this rule.
Metadata gets mixed in with posts instead of stored in a separate database
- All static blogs seem to use Jekyll idea of Front Matter embeded at the top of your post.
Multi-author sites require either human organization or hacking. It’s not really supported well out of the box.
Geeky
- Very few of the static blog options seem particularly usable by the non-geeks out there.

Note

Being a geek, I’ve got some advantages. When I used Jekyll I wrote JekyllMail which lets you create blog posts via email. It even handles attached images. I could do that for any other platform too. That addresses what’s probably the biggest downside to static blogs. Again, using Prose would too, but that’d tie me to Jekyll on the back end, and I just wasn’t thrilled with it.

Why’d I Choose Static?

With so few upsides, and so many downsides, a dynamic blog would seem the obvious choice. So why would I switch back to a static blog?

At this point I require any dynamic system to also be a managed system (like Squarespace) that doesn’t cost a boatload of money to run a bunch of sites on. Also, I need to actually like the software. Ghost is a decent, and relatively affordable option but I’ve had problems with their import, and I’m not thrilled with the software.

Medium and Svbtle both have their proponents, but posting there doesn’t contribute to your success or credentials. It contributes to their’s.

Static blogs give me a few big things:

The ability to stop compensating for or worrying about hackers
The confidence my site will stay up when I post something popular
The ability to customize the look and feel
Unlimited blog sites for zero additional dollars.
- I just pay a monthly fee for hosting space with as many domains as I want.
- Or do it totally free by using GitHub pages…

Also, and I realize this is totally illogical, building a site with a static blog gives me a feeling of having actually been a part of it’s creation.

So, for now I’m using Hugo. I’m going to have to start converting my other blogs over because they’ve been hacked again. I just need to find a way to enable my wife to easily post to our shared blog at CorporateRunaways.

Want to debate this? Think I missed something? Hit me up on Twitter.

Why I won't be backing Mou's crowdfunding Campaign

Thu, 09 Oct 2014 00:00:00 +0000

Mou as your Markdown loving Mac geeks know, is a split pane Markdown editor. It’s been around for years and it’s really quite good. I even donated to its creator in the past to support it. Now he’s put together an IndieGoGo campaign to pay for people to work on it full time, but I won’t be contributing.

Some background first

Mou was never open source. I’m ok with that. I use a bunch of great proprietary apps. Unfortunately, that means that when its developer (Chen Lou) was busy with his life, Mou languished, and no-one could help improve it. Eventually he decided he couldn’t give it the attention it deserved and tried to sell it. Sadly, I found out about this after the fact or damn would I have been trying to put together the money to buy it.

Life Moves On

During the process of trying to sell it Chen appears to have decided to try and put together a company to work on it full time, which is great, but when the sale was announced UranusJr (otherwise known as Tzu-Ping Chung) got a bit concerned.

It came as a great shock when Chen Luo announced that he felt he could not actively continue the development, and wished to sell the ownership of Mou. No suitable offers surfaced (I honestly do not think there will be, either), and I decided that instead of waiting for others to do something about this, I should act myself.

And act he did. UranusJr’s been working like a madman on an MIT licensed clone of Mou called MacDown. He’s been adding features on a regular basis, and is constanly asking for and listening to feedback from the community. He allows those of us who use it, but aren’t skilled at Objective-C to feel that we are making some kind of worthwile contribution by trying out his beta code and discussing the ideas that he, and the community, come up with.

The crowdfunding

Meanwhile Chen Lou’s IndieGoGo campaign is offering the following:

“We’ll pick the most wanted features from our contributors, implement them in 1.0.”
Free license to Mou when it hits 1.0
Jumping metal frog
Metal stand shaped like the Mou’s “M” in various colors.
If we’re really lucky and it reaches $100,000 ( 5 times it’s goal ) he will open source it.

So, let’s compare those perks to what MacDown is offering:

MacDown implements the most wanted features from the community, not just a select few, and if you want a feature badly enough you can write it and there’s a good chance it’ll get merged in. Also, he’s regularly adding features just because he wants them himself.
MacDown accepts feature requests from everyone. Also, it’s not like Mou would ignore a great feature request from a non-backer. So this is kinda BS anyway.
MacDown’s already free so I don’t need a license
Don’t need a jumping metal frog
Don’t need a metal stand shaped like an “M”
ALREADY open source.

Mou’s campaign encourages us to “Forget the crappy clones, let’s open source the original Mou!” But why should we? UranusJr’s done a spectacular job with MacDown. It’s true that it’s not quite as polished as Mou yet. I does have a couple rough edges, but it’s polishing up quickly, and the driving force behind it is incredibly responsive to community feedback. With MacDown I’ve got a great app that I’m using daily, and it’s released under one of the most permissive licenses there is.

At this point I see no reason to back Mou. Not long ago I would have happily thrown Chen some more money to start working on it full time, but Mou missed its opportunity. Someone else stepped in to fill the need.

P.S

This post? Totally written with MacDown.

The Five Virtues of a Great Programmer

Fri, 03 Oct 2014 00:00:00 +0000

In Programming Perl Larry Wall (in)famously suggested that programmers had three great virtues: Laziness, Impatience and Hubris. Over the years I’ve kept coming back to those because there’s a real truth to the idea as he originally presented it, but it’s limited, and his definition of “Hubris” has no relation to the actual word. I believe that those may be aspects of real programmers, a great programmer goes beyond that. Building on Larry’s idea, I present you The Five Virtues of a Great Programmer:

Laziness

The quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don’t have to answer so many questions about it.

Impatience

The anger you feel when the computer is being lazy. This makes you write programs that don’t just react to your needs, but actually anticipate them. Or at least pretend to.

Hubris

The belief that you can do a better job than the people who came before you.

Humility

The belief that despite your hubris, there are more talented coders than you, and anything you produce could be better. This leads to well tested code, because you might have screwed up.

Unselfishness

The quality that makes you document your code, and leave helpful comments and commit messages, so that others don’t have to puzzle out what you’ve done. It makes you take the time to help coworkers understand things, and change your code to take their needs into consideration.

Vampire Bug [Definition]

Wed, 01 Oct 2014 00:00:00 +0000

Vampire Bug: n. something that worked when you went to bed at 2AM, but when exposed to the light of the next day dies horribly. Typically the exposure proves that it couldn’t possibly have been working at 2AM either.

How to enable GitHub 2 factor Authentication on new device / app

Tue, 30 Sep 2014 00:00:00 +0000

( as of Sept 30th 2014 )

These are the instructions for how to do it if you’ve already got it configured and need to add a new app / device. If you don’t have it set up already, GitHub’s docs are… probably passable.

Go to Settings
Click on Security
In the “Two-factor authentication” section click “Edit”
- Yes, even though you don’t want to edit it.
Under “Delivery options” click “Reconfigure two-factor authentication
- Yes, even though you don’t want to reconfigure it.
Click “Set up using an app” or “Set up using SMS”

What would you want to do?

Wed, 23 Jul 2014 00:00:00 +0000

This afternoon my intern asked me this simple question. She’s a new developer, and a friend of hers is working in a fresh codebase, with best practices. Everything is nice, and he can keep the entirety of it in his head. She’s working with my team, Support Engineering. We’re the front-line bug squashers at our company. We’ve got a legacy codebase with no tests and brain melting insanity around every bend.

So she asked me which environment I’d want to be working in if I was her. The question, and the answer speak a lot to what it takes to become a great programmer.

What I would want if I was her is simple. I’d want to be working in the new codebase. There’s no question. A new codebase is always more enjoyable to work on. But, what I would want is not what I would recommend with 19 years of professional programming experience.

My suggestion was that right now she was in the best place she could be: debugging a bad codebase with good instincts and helpful mentors, and that’s why I’m writing this.

I firmly believe that the most important skill you can learn as a programmer is how to debug: how to debug well, and how to debug fast.

New codebases are great, but they’re like kittens. One day they’re cute and fun, and the next thing you know they’ve grown into a tom cat who’s running around spraying your furniture. It’ll be too big to hold it all in your head, and large swaths of it will have been written by other people. Even if you’re really lucky, and people have written great tests, and some god has smiled down upon you and granted you the only significant codebase with no bugs, you’ll still need to use your debugging skills.

In the typical case you’ll need debugging skills to figure out where the problem is, and then what exactly is going wrong. In our mythical perfect codebase you’ll need to figure out where a feature is implemented and how it works in order to build on it. There’s really very little difference: hunt something down, understand it, make some changes, write some tests, move on.

People with bad-ass debugging skills get things done faster, in any industry.

That’s just the start of why our situation is a better one for her than the happy-fun-land her friend is in. New developers haven’t experienced pain yet. They’ve seen the patterns books but they haven’t internalized the problems that resulted in those patterns. They won’t know what problems those patterns were designed to avoid, so they won’t know when they’re about to create that problem. I think that even if they were to go read the best pattern book for their situation they wouldn’t be able to truly appreciate it because they don’t know the classes of problems they’ve got to deal with.

Debugging a legacy codebase though… If you’ve got good instincts, or good mentors (preferably both) you’ll be able to see all the ways to not do something. You’ll encounter things that just feel wrong, and have people who can explain to you why they’re wrong, or what piece of the puzzle you’re missing. Once you’ve found the bad, you’ll have to figure out how to make it good, and you’ll learn about tradeoffs, because professional coders rarely have the luxury of refactoring everything to be the best it could be, especially in crufty old legacy codebases. No, you have to find the balance. You have to figure out what you can do to improve the situation without spending so much time that the other bugs pile up. It’s a lesson I’m still learning nearly 20 years in.

When she eventually moves on from her job as a professional bug slayer she may not know the right way to write good code, but she’ll definitely know how to not write bad code, how to make code that other people can understand (because she had to wade through so much incomprehensible stuff), and why you don’t violate encapsulation.

A year from now her friend will just be starting to experience the consequences of his inexperienced decisions. A year from now she will be ready to tackle anything.

Writing good User Stories

Thu, 20 Feb 2014 00:00:00 +0000

First, it should be noted that not all stories are “User Stories”. For example a developer might be tasked with manually running some script. The Story might simply be “run the fooberry script”.

For everything that effects the UI, use a template:

As a < type of user >
I want < to perform some task >
So that < I can achieve some goal >

Note that it’s all about what the user wants. This isn’t about instructing what change to make to a system. It’s about advising implementers on what the desires of the user are.

Sizing, details, content

Now, everyone says user stories should be “testable”, and “small”, but what does that mean?

Stories should be “Testable”

You’ve heard it before, but its a horrible way of expressing the intent. In general, a story is not directly testable. A Story is only testable through its Acceptance Criteria.

Acceptance Criteria?

Each Story should have a compliment of Acceptance Criteria which cover every interaction, and outcome of the Story. Think of it this way. If you write code that meets every Acceptance Criteria and nothing else your coding work should be done. You should not need to write anything else in order to satisfy the Product Owner. Furthermore, you should be able to write a unit or functional test for each acceptance criteria. If you find your test is testing multiple aspects of the system then your acceptance criteria is too large in scope.

For example: if you’ve added a new page to your app one of the acceptance criteria might be “Administrative users will see a link to the new page in the upper nav. on all pages” This acceptance criteria would pass regardless of where the new link appeared in the “upper nav.” If the Product Owner cares where it appears then the criteria isn’t specific enough. Note that it also specifies what pages it will appear on. Without that you could put it on the “wrong” page and still pass the criteria.

In XP (Extreme Programming) they use a 3"x5" index card to create all their user stories. The story (in template form) goes on the front, and the acceptance criteria go on the back. The rule-of-thumb is that if the acceptance criteria don’t fit on the back of the card, then the story is almost guaranteed to be too big.

Story Sizing

How small is too small? A Story is too small if, by itself, it provides no business value, like this: “As an Administrative User I want to have a link to the new page so that I can navigate to it.” Unless someone’s already created and deployed the new page, it’s a link to nowhere. The next question, of course is how big is too big? I’d say it’s too big if it can still be decomposed into multiple smaller pieces of deliverable business value.

General Tips

Know your users, before you can write a story about what a user wants, you need to know who your users are. Put together, and commonly agreed upon set of user Personas, and use those persona names when writing the “As a… " portion of your user story. E.g. “As an Accounts Manager I want…”
Focus on the user, not the product. Keep your stories focused on the user’s goals, and helping them to achieve them.
Start big, and decompose It’s generally much easier to write an “Epoch” level story (one that comprises many units of business value) and break that down into increasingly smaller stories, than it is to start with fine grained stories.
Use index cards (to start with at least). The physical limitations of the card really help make it obvious when a story is too large, because you can’t fit it, or it’s acceptance tests on one side of a card (unless you write in verrry small print, and that’s cheating).
Acceptance tests should be automatable If you can’t automate the acceptance test, it’s probably not a good one. They should be very focused, and very precise.

Finding the Github Pull Request for a topic branch

Tue, 24 Dec 2013 00:00:00 +0000

Finding the Github pull request associated with a branch.

Work on a large enough project, with other people and sooner or later you’re going to find some commit, or branch, and want to know what was in the pull request that merged it in. Maybe you want to see what other commits got merged over at the same time. Maybe you want to see what the diff was at that point in time. But, how do you get from a branch name to a pull-request.

The key to solving this is knowing that pull requests are actually branches. They’re just… hidden branches. So, first you start tracking them…

Locate the section for your github remote in the .git/config file. It looks like this:

[remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = git@github.com:joyent/node.git

Now add the line fetch = +refs/pull/*/head:refs/remotes/origin/pr/* to this section. Obviously, change the github url to match your project’s URL. It ends up looking like this:

[remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = git@github.com:joyent/node.git
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Now, after a git fetch origin you can say git checkout pr/999 to checkout pull request number 999 as a local branch and diff it, or do pretty-much anything else with it.

Once you’ve got that set up, it’s just a matter of comparing your local topic branch to the other branches in your system to find other branches that point to whatever branch you’re interested in.

I use a shell script called git-find-twins which iterates over the known branches (including pull request branches) and finds any whose tree-ish matches that of the current branch. You can find the latest source here in Github.

[Note: My apologies for the disappearing code on the right side in these examples. Just grab the source from the link above.]

    #!/bin/sh
    # Finds other git branches whose HEADs point to the same 
    # treeish as this branch.

    # thanks to mockinterface on 
    # http://stackoverflow.com/a/20756047/13973
    # for showing how to do this.

    echo "Looking for branches pointing to: $(git rev-parse HEAD)"
    git for-each-ref --format="%(refname)" | \
        xargs -I refname   \
        sh -c '[[ $(git rev-parse HEAD^{tree}) == $(git rev-parse refname^{tree}) ]] && echo refname'
    echo "DONE"

Add that to your path, and make it executable then check out the branch you want to find the pull request for, and run your new shell script with git find-twins (note the space) and you’ll see output like this.

$ git find-twins
Looking for branches pointing to: cb3c2dcf606a0a26107131697dd37aef53d44aad
refs/heads/9284_vzw_bug_fixtures_without_fixture_types
refs/remotes/origin/9284_vzw_bug_fixtures_without_fixture_types
refs/remotes/origin/pr/530
DONE

That last one is what you want. 530 the number of the pull request, which you can put into an URL to see the pull request. Now, you’re probably saying “Yeah, but what URL?” well, one way to get the correct url is to just bring up any other pull request in the current project and change the number in the url. Or you can add this shell script, which I call url_for_pr which generates an url for the pull request number in the current repo. It’s based on the assumption that “origin” is the Github repo. If it isn’t you’ll need to tweak what remote it gets its info from. You can find the latest source here on Github

[Note: My apologies for the disappearing code on the right side in this example. Just grab the source from the link above.]

    #!/bin/sh
    # when run from a git repository, and passed the number 
    # for a pull request, it will generate an url for 
    # where to find it on Github. This assumes that
    # "origin" is pointing to the Github repo.
    # This will work with Github Enterprise too.

    if [ $# -eq 1 ]; then
        ROOT_URL=$(git config --get remote.origin.url | \
            sed s/.*@// |sed s/\.git// | sed s/\:/\\//)
        PR_NUM=$1
        echo "https://$ROOT_URL/pull/$1"
    else
        echo "Please pass in a Pull Request number"
        echo "Note that this should be run within a git repository"
    fi

Bonsai Coding

Fri, 06 Dec 2013 00:00:00 +0000

Writing code is a lot like maintaining a Bonsai Tree. If you stop pruning it it’ll stop being a Bonsai and turn into a bush. Little tweaks, frequently aesthetic ones, will help to keep it beautiful and under control. It will still grow in unexpected directions, as other developers make changes, but careful pruning will keep it balanced, and healthy.

What is “careful pruning” then?

Each file is a branch on our tree. The methods, are leaves. We come in to work and start examining one of the branches. Some days we need to encourage it to grow a specific way by adding a feature. Some days we make little snips to correct a bug. But what happens if, upon examining your branch for other reasons, you discover that it’s grown into spirals and knots. You can’t reach your clippers in to snip the leaves you need. You can’t do much of anything without difficulty and frustration, and frankly, it looks like crap. The unexpected spirals and knots need to go.

This, however, is the point where you’ll hear other developers saying “No! Don’t do that!” They’re upset, because your task wasn’t related to the knots and spirals. You were just there to trim some leaves. If you go and get rid of the “other” problems then how will they be able to tell where you trimmed?

To abandon the metaphor for a minute, they’re concerned that the diffs will be so filled with aesthetic changes that they can’t see the changes that were relevant to the bug fix, or feature add. And, they have a point. Being able to look back and understand the changes another developer made is a very valuable tool. But some developers get so obsessed with this idea, or so beaten down by others who are obsessed with it that they say things like this,

“The rule for controlled development is that if the line is not relevant to the fix, you do not modify it. If we want to go through and fix all the lines in our product that are over 80 characters, then we log a bug for it.” - A rule you shouldn’t follow

This solution will never leave us with a beautiful tree. I don’t know of any professional developer who has the time to deal with tickets that are that low priority, and no-one wants to anyway.

If you accept that there is value in making the line / file readable, then you must also accept that there will be change unrelated to any bug fix or feature request. You must also accept, that if those changes get put off for “later” our tree will become a bush, and require so much work that it will be almost unrecognizable the day after the change.

So, how do we balance these two concerns? How do we make readability changes to our code without obscuring the functional changes? My recommendations are as follows.

It should be acceptable for whatever method you’re directly trying to enhance or fix to be refactored for readability. Even if you’re refactoring a 20 line method, for a one line fix. To do otherwise is like having a child make their bed but leave their clothes and toys strewn about the floor. Don’t do a half-assed job. Leave the method better than you found it.
Separate other aesthetic changes out into separate commits. It would be nicer if you could commit the fix, then commit the aesthetic changes, but we frequently need to make the aesthetic changes in order to make the code readable enough to understand it. So, make it readable, but leave it broken. Commit that change. Then fix it and commit that change.

The downside to 2 is that you have to instruct reviewers to review specific commits, rather than the changeset as a whole. So, an alternative is to make the aesthetic changes, create a pull request / request review of your branch to be merged, and then, once that’s done create another pull request for the bug fix. I think it’s a judgement call, and the appropriate choice depends on the situation.

As per usual, if you’ve decent test coverage everything becomes much easier. Code reviewing the aesthetic commits can be just a matter of seeing if the tests pass, and giving it a quick glance to make sure the other developer didn’t go all crazy-pants with their changes, like changing the indentation style to something no-other files use. You don’t have to stop and consider the funcional impact of the changes, because there shouldn’t be any. “Yup, still compiles, still passes the tests, looks more readable. Approved!”

Summary Codebases are like Bonsai Trees. Regular aesthetic changes are as

important a part of keeping your codebase healthy as regular refactorings. Some trivial changes to how you commit your work can elimanate the diffing problems that arise when combining fixes / features with aesthetic changes.

The Daily Team Tracker Worksheet

Thu, 22 Aug 2013 00:00:00 +0000

The Daily Standup Meeting is a core aspect of Agile development. The simplified idea is that you want to start the day with a very quick status check of what everyone’s working on, and helps “…to coordinate efforts to resolve difficult and/or time-consuming issues”.

But, how do you keep track of the things your minions are working on today and deal with your own tasks, and 400 daily interruptions? For me the answer was to put together the Daily Team Tracker Worksheet.

The idea is simple. Each morning, as you go through your Daily Standup write down what each person will be working on today. If they expect to complete the task today there’s a little checkbox to indicate that. There is, of course, another to indicate it’s done, a notes section, a place for emergent tasks, and more.

When 3pm comes around and I’m wondering, “What was Charles working on? Was he expecting to finish that today? Should I be checking in or leaving him alone?” I can check my sheet and see.

It’s also good to have prior days sheets because you can easily see that at task that was supposed to be done “today” has been on someone’s plate for three days now, enabling you say “Wait, weren’t you expecting to finish that two days ago? What’s gone awry? Is there anything I can do to help, or any lesson we can take from that?” (It’s all about the Kaizen baby). Some of that will, of course, be covered in your stand-up, but sometimes it’s good to have that reminder.

There are two versions of this:

Daily Team Tracker PDF (for teams of over 3 people).
- Page 1 is a the 3 person view with section for notes and diagramming.
- Page 2 has sections for 5 more folks with a mini notes / diagram section
Daily Team Tracker PDF 2 Sided (for teams of 3 or less)
- Page 1 and 2 are the same 3 person view so that you can print it on both sides of a piece of paper and save some trees.
Daily Team Tracker OmniGraffle file If anyone out there has OmniGraffle and feels like tweaking the original.

This file is (cc) 2013 K Rhodes ( masukomi.org ) and distributed under the Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License.

[Review] CruxSKUNK iPad keyboard / case

Sat, 01 Jun 2013 00:00:00 +0000

The backstory

Once upon a time there was a Kickstarter to make the world’s most awesome keyboard / case … thing to “Turn your iPad® into a laptop”. As with most hardware projects on Kickstarter the expected delivery date came and went, and came and went again, but I feel the folks at Crux did a great job of keeping the backers informed, and the reasons it got set back almost always boiled down to them not being willing to accept half-assed Chinese manufacturing even if it would have gotten it into our hands sooner.

They really wanted to make the best product they could. They went so far with this that they actually lost money on each one that was made, and these are guys aren’t new to manufacturing hardware. They’ve had similar products built in China before. When it comes to something like this, I’m ok with having to wait a bit longer to get a better product.

So, did they deliver?

First impressions

The first thing you notice is the weight. This is not a flimsy POS product. They promised a CNC milled block of aluminum with a quality level that was right on par with the Macbook, and they came pretty close. Is it as beautiful as a Macbook Air? No, but we knew that going in. This is essentially a really fancy picture frame for your iPad with an attached keyboard. They could have put a sheet of aluminum behind the iPad’s back, but it would have made the whole thing thicker and heavier. The reason I have to say “pretty close” is that Apple’s manufacturing standards are very, very high and the tolerances aren’t just good, they’re precise. So, for Crux, or anyone else, to get “pretty close”, is pretty damn good.

The case it comes with is actual leather, with a layer of padding and a fuzzy fake fur lining to keep your baby safe. Will I use it? Probably not. Is it nice? Yes.

Setup

Inserting the iPad was pretty simple. By default the little hinges that hold it in at the bottom are configured for an iPad 2 I suspect. The iPad 3 and 4 are a bit thicker, so I had to grab the included alan wrench and loosen them up (as instructed by the user manual) so that they would fit over my iPad 3. I also managed to put the iPad in backwards which obscured all the ports, but as soon as my foolishness was pointed out I just opened the hinges, flipped it around, and voillá the cutouts for the the ports and button lined up perfectly, but the space around the ports is only barely adequate. The headphone jack works fine with the Apple headphones, but anything with a thicker plastic portion won’t fit. The main 30 pin port is only enough for the power adapter. I have to press the iPad “into” the case and / or pull down on the edge of the case to make enough room for my connector cable to fit. The adapters for the Apple Camera Connection Kit don’t fit at all. I have to take the iPad out of the Crux Skunk to use them. Not a huge deal, as I don’t use them that often, but I suspect I’ll be using them much more frequently on the road and it’ll be annoying then. The HDMI adapter does fit either, so you cross this right off your list if you’re hoping to use it for presentations because even with pressing you can’t make it fit while in the case. I can’t comment on how accessible the Lightning port on the iPad 4 would be.

My first thought upon seeing my iPad in it’s new “laptop” incarnation? “It’s so wee!” Visually it’s pretty good. The keyboard comes up through an aluminum plate, which is fine, but I’m not thrilled with visuals the seam that follows around its edge meets up with the base. Apple chose put the flat plate on the bottom of the Macbook so that you’re not seeing it every time you use your laptop. I think this would have been a better choice for Crux, even if it did necessitate the use of screws, which Crux has managed to avoid. Also, the tolerances along that seam are good, but not Apple good. You can see it in the top right photo. I just can’t help but think “Oh look, there’s a metal plate that’s been snapped to the base”, every time I look down at it, and I don’t want to think that. I don’t want to be aware of that at any level. It should be hidden from me.

Pairing

Pairing it was pretty straightforward, except that I pushed the “LED window” instead of the “Sync button” because the “LED window has the light that they were talking about seeing. Doing so felt wrong, but it still moved significantly as if it was a badly done button. But no, it’s a thing that looks like a button but really isn’t, and moves in a disconcerting way when pushed by someone who’s not paying close enough attention. Fortunately, I should never have to push the “Sync button” again, and it should be noted that if I’d read the instructions more carefully I wouldn’t have pushed it in the first place.

Keyboard

The keyboard itself feels… well it feels pretty good. The keys on a Macbook Pro have a softer feel at the terminus of your stroke. These have a little bit more of a “whack” at that point. Is it bad? No. It’s just different. You might start to feel it after an hour or more of typing. As for the layout, my fingers don’t feel even remotely cramped like they do on a typical netbook, but the key layout is smaller than that on the Apple Wireless Keyboard.

The CruxSKUNK comes with a variety of useful specialty keys: home, search, slideshow, languages, screen toggle, copy, paste, a lock button, plus music and volume controls. Some work, some don’t. I don’t know if this is a bug in Crux’s bluetooth software or just functionality that’s not supported by my older iPad 3. The ones that don’t work are: language, copy, and paste. I was really hoping those copy paste buttons worked. Alas, “comnd+c” and “comnd+v” (not a typo) do not copy / paste either. But, You can use shift+arrow keys to select text like with any other keyboard, and that’s a hell of a lot better than the touch based text selection tools.

I’ve typed about about 1,500 words on the thing so far, and I’m enjoying it. I’ve always been painfully slow typing on iOS devices. Now, I can touch-type full speed (~100 wpm) without issue. Geeks like me will be happy to know there’s a way to convince your iPad to use a Dvorak layout with bluetooth keyboards like this one. So all 4 of you can rejoice. Yay.

The lid / hinge

Closing and opening the lid sleeps and wakes the iPads screen respectively, as you’d hope. The hinge is designed such that you can keep opening until the back of the iPad is directly against the bottom of the case. They call this “Movie Mode.” I guess the idea is that you could flip it over into an A-frame and set it on something. Nifty. Will I use it? Possibly. Only time, and travel, will tell. I doubt I’d use it in day-to-day life.

Speaking of the hinge. There were a couple revisions in the hinge during production and I think they’ve absolutely paid off. It feels solid, and reassuring. The iPad’s weight is not going to gradually pull it open. On the downside, the hinge is so strong that you can’t actually close the “lid” all the way, or more accurately, you can close it all the way but the hinge opens it back up about an eighth of an inch as soon as you let go (see the photo above), which looks a bit crap if you ask me. It makes me wonder if that’s one of the reasons they included a case.

Conclusion

I recognize that, having just received it, and only typed a thousand or so words on it, it’s still pretty early to make any claims about it’s long term value, but I think that this is just the beginning of a radical transformation in how I interact with my iPad. Previously, typing on the thing was so frustrating that I wouldn’t even respond to tweets. I’d switch over to the laptop. Now, I’m typing 1,500 word articles on it.

But, it does what it claims and turns your iPad into a laptop, which is absolutely not what some people want. The iPad is a spectacular tablet, so you definitely sacrifice something when making it into a laptop, and while the wee hinges that hold in the iPad are easy to open or close, it’s not really the kind of thing that you’ll be wanting to pop your iPad in and out of constantly.

Is it better than just using an Apple Wireless Keyboard? That depends on who you ask. I think the Apple Wireless Keyboard is great, but using it with an iPad is crap unless you’re sitting at a table or desk. With the CruxSKUNK I can type on my iPad with it in my lap, at a desk, or anywhere else.

Postscript

For those curious, yes, this post was created entirely on the iPad using Writing Kit, and Diptic, and typed on my CruxSKUNK. If you like Markdown, and you need to lookup information (and URLs) on the web whilst writing things, I highly recommend Writing Kit.

The Thing About Today

Tue, 16 Apr 2013 00:00:00 +0000

The thing about today is that we have the power.

We, can destroy this fear.

Not by being stoic. Not by being “strong”. By smiling. By being human. By being the neighbors we wish we were surrounded by.

Go outside.
Smile at a stranger.
Ask someone how they’re doing and mean it.
Listen.

Yesterday’s act was horrific, but I will light up this mother fucking town with smiles, because we are alive, and this world is filled with brilliant people with warm hearts, and their own 200 watt smiles, just waiting to shine.

Git push is not what you think

Wed, 13 Mar 2013 00:00:00 +0000

tldr;

git’s default configuration with regards to push is potentially very dangerous.
make sure you’ve run git config --global push.default current
There are other options for push.default but make sure you read the docs before setting them.
setting current as your default behavior means no more complaints about setting upstream when pushing.

Perception vs. Reality vis-à-vis git push

When it comes to git push most people think “It pushes my current branch’s updates up to the remote server” but that’s only a small part of what’s happening, and ignorance about the rest can leave you with very upset coworkers. I know, because that’s exactly what happened to me today when I ran git push -f on a coworker’s computer that happened to have the default configuration.

I mistakenly believed that “Hey, git push just pushes the current branch up, so git push -f will just force push this current branch up. I want to wipe out history on this topic branch, so no worries.”

git push

“Updates remote refs using local refs, while sending objects necessary to complete the given refs.”

Note that nothing in that statement is singular: refs… plural.

push (in its default configuration) is effectively the opposite of fetch. Fetch pulls down all the changes from branches you’re tracking. push uploads all your changes to branches you’re tracking. Now, normally this won’t get you in trouble. The branches you’re not currently working are either: older (or current) versions of what’s on the remote repo (in which case nothing happens), or incompatible versions of what’s up there (in which case they get rejected), or possible new commits that can safely be updated. The latter case can be annoying, but it’s rarely that bad, and can be easily backed out.

The problem is when you add -f to push in a default configuration and don’t specify what repo and branch you’re pushing to. This essentially says “Hey remote repo. All these branches I’m tracking? Yeah, make yours match. No. I don’t care that I’m blowing away work. You can take those rejections and shove them where the sun don’t shine.”

The more remote branches you’re tracking, the more damage it can do. And, you’re probably tracking master, which is usually the most important branch in any repo, which means there’s a good chance you’ll be doing some notable damage.

But, if you change your default configuration by running git config --global push.default current then the default behavior stops being “everything I can find a matching name for” and starts being “the current branch” which is what everyone generally assumes is happening anyway. People don’t want, or expect this “reverse fetch” behavior. They expect something akin to “my branch will go up”.

Making this change to push’s default behavior also means that when you do do git push on a brand new branch it won’t complain about you not having set upstream. Instead it will just create a new remote branch for you that matches the current (new) branch.

What to do when you’ve run push -f

In the default configuration?

pray
apologize profusely to everyone who’s working on your repo.
ask very nicely if every could please do a push to all the branches they’re tracking.
thank the deit(y/ies) that someone came up with a distributed version control system where everyone’s got a legitimate copy of the repo.

The only circumstance under which 3 will fail to recover the data is if you did the most recent work that was pushed to a remote branch, then reset or rebased your local copy of it to some prior state, then force pushed before anyone else had a chance to download your changes. Alternately, everyone hates you and refuses to push their copy in order to force you to recreate all the work you blew away. If that’s the case you should probably go look for another team.

Setting the Atomic Clock

Thu, 21 Feb 2013 00:00:00 +0000

This morning’s shower brought me an interesting series of thoughts that I thought you might appreciate, and it all started with the simple question of “How do you set The Atomic Clock?”

My first thought was that at some point you have to find some other clock and precisely sync up with it. Then again, they may have said “fuck it” and just had Bob press a button when some other clock flipped over, but then I wondered “How do we know what time it is in the first place?”

Well, our calendar is based on the birth of Jesus, and we claim we know what day that was, and what town that was in. I’m ignoring that the details in the Bible point to a date that’s nowhere near Dec. 25th. Anyway… The first moment of the first day would, I suspect, be associated with the moment at which dawn broke in Jerusalem that morning. Or maybe some more esoteric moment that day. Regardless, let’s stick with dawn for the sake of attempting to figure out what time it is.

So, dawn, in Jerusalem, on day 1. Great we can work forwards from there. But, wait… how do we know how long a year is?

A year is the time it takes for the Earth to travel around the Sun, but how do we know when we are at the same place in the rotation we were exactly one year ago? You could try and position yourself relative to other heavenly bodies “When star X is directly behind the Sun.” But our orbit’s not circular, it’s elliptical. Actually, that’s not true either “The Earth travels around the sun in an elliptical orbit that varies in shape, with time from nearly circular to distinctly elliptical.” Then there’s the fact that every galaxy in the universe is shooting out away from the center of it.

If you ignore the orbital complication and say “ok, we can compensate for orbital weirdness”, how do you verify it with observation? Well you’d look up on… wait a minute. How the fuck do know where the same up is? In order to calculate our point in the Earths solar orbit we have to first be able to look up at the same point on different days. Which means we have to calculate exactly how long a day is, but “The tilt of the earth changes cyclically between 21 3/4 degrees and 24 1/4 degrees. The period of cyclicity is 42,000 years.”. On top of that we’re going around the sun.

So, even if the Earth wasn’t wobbling, and even if I knew exactly how long it took to spin 360° when I looked up the sun would be in a different place because we’ve moved around it. The stars would be in a different place because we’ve moved around the sun, and even if we hadn’t done that, the contents of the universe is still shifting outwards.

Back to figuring out how long a day is. So, we look up. We find something in the universe that we’re not rotating around to mark as a point of reference. We can compensate for the universe’s expansion by observing its Redshift (i think). So, we look up but once 23 hours have passed and we’re ready to start looking straight up again to observe the exact instant we’re lined up with that distant star (or whatever) the planet has wobbled on its own axis and now “up” will be pointed in a different direction than it was exactly one day ago. So, now we have to calculate the the wobble of the planet…

At that point I needed to get out of the shower. But I do know that the wobble’s going to be affected by the fact that we’re on a large ball of rock that’s got a molten core, which means liquid sloshing around in the center (for some definition of “sloshing”). I’ve no clue how one would determine that we even have a liquid center. Maybe by the fact that we’re wobbling?

To summarize:

In order to calculate the correct time you must:

Figure out the speed at which the universe is expanding so that we can use a distant star as a reference point to observationally confirm all the other things we need to figure out.
Figure out the Earth’s eccentric wobble. No clue how to do that. My shower ended. Once you’ve got that you can then figure out how long a day is.
Now store away what you’ve learned about our wobbling rock with a liquid center. We’ll need that.
Once you know how long a day is, and what direction you’re pointing after a given span of time, you can then start observing our orbit by marking the location of the sun relative to you and some distant star. So, now you can figure out how long it takes you to get around the sun. Unfortunately that’s going to change every single year as our orbital path changes.
So observe those changes for enough years to calculate how our orbit changes. Then factor in the effects of a wobbling mass on an orbit.

Once you’ve done all that you can then work backwards to calculate out where the hell the sun was over Jerusalem on December 25th 2013 years ago, and then you can work forwards to figure out what time it is.

You’re still going to have the problem of actually syncing the clock with the math though.

P.S. How was your shower?
P.P.S. Those links? Missouri Department of Natural Resources, Division of Energy. “Global Climate Change: Effect of the Earth’s Orbit”
P.P.P.S. I’m not a Physicist. I just play one on the Internet.

Some useful Vim plugins

Wed, 20 Feb 2013 00:00:00 +0000

There are two things that make using vim awesome… no there are about 200,000 but most of them involve adding a few lines to your .vimrc to enable them, or installing a plugin. My .vimrc is just over 300 lines after all these years of use and customization. But, rather than go into all that, I figured some of the vim geeks out there might appreciate a pointer to some of the plugins I use. I’d also be happy to hear suggestions any alternatives to the ones I am running.

I should note that some of these rely on the use of ctags which seems to be a dying art these days. So many people are unaware of the awesomeness contained therein. If you don’t know about ctags, go read this.

Vim Plugins I use

AutoComplPop (acp) Autocomplete popup. It’s a little too aggressive. I need to find something that’s mare accepting of me not wanting what it’s offering.
AutoTag Automatically reruns ctags on a source file when you save it.
bclose Deletes a buffer without closing the window.
bufexplorer allows you to quickly and easily switch between buffers
FuzzyFinder (fuf) allows you to search for a file by name or via ctags… has a tendency to totally hang vim far too often.
indent_guides visually displays indent levels in code. I don’t use it much, but it’s nice to have sometimes.
powerline makes the vim statusline awesome. For extra awesome install the modded font.
rails I have never used this, although I probably should.
Fugitive Install this, if for no other reason than to have awesome Git Blame integration
taglist I never use this but really ought to. There’s a video on it here
gitgutter Puts a little indication of what lines have been added, modified, or deleted in the left hand gutter. Read the FAQ after install if gutter section for non-modified lines looks ugly.

Plugins I’ve installed but should probably get rid of

scratch I’ve never used this.
vcscommand for interacting with version control systems. I should probably kill this as there are better ones that are git specific like…
gitv gitk for vim… I can’t remember using this and I’ve got Kaleidoscope and SourceTree which are awesome so I don’t really need it.
l9 I have no clue why I installed this, and I’m somewhat unclear on what it does (documentation sucks).

Mage Knight Co-Op Rules

Sun, 17 Feb 2013 00:00:00 +0000

We love the game Mage Knight, but the co-op rules are widely regarded as crap. The following rules have been collected primarily from Board Game Geek, an tweaked ever so slightly here, and there, in an effort to make the game cooperative and yet, still balanced.

This document covers:

Assistive Spellcasting

Any number of players are able to cast spells on an ally’s turn so long as they are within 4 hexes of the ally they wish to help. The spell resolves as if the active player had cast it. The inactive player may use a die from the source in addition to the die used by the active player. If he does, he can’t use a die from the source during his next turn.

To prevent the inactive player from accidentally drawing up, or anyone else using the inactive players spent die before they can re-roll it at the end of their natural turn, leave the spent play card (and spent die) in the play area until the end of their natural turn.

Dispersal of Loot, Fame, and Rep

Inactive players share equally in the fame at the end of the active player’s turn. If the total number does not divide evenly the remainder goes to the active player.

Positive and Negative reputation go to the active player only.

Any loot (artifacts, spells, etc.) go to the active player, but may (at the active players discretion) be traded via Adjacent Trading or Keep Trading.

Adjacent Trading

Players are able to trade units, crystals, and/or artifacts. When adjacent to another player, but not in the middle of combat, they may give or take spells, artifacts, and advanced actions. When invading a city, all trades must take place before revealing the city’s monsters.

A player receiving crystals may not exceed the normal three crystals per color limit. Artifacts are traded from one players hand to the other’s discard pile.

Trading of Units

Units may also, be traded but only if the receiver ends their movement on a space adjacent to the giver. Furthermore, the receiver must have greater reputation than the giver. Influence may be used to boost this number, but only during the receiver’s turn.

The idea here is that you have to convince the troops that they’ll be better off following you instead of their current leader, and that it’s going to take a little time to do so (thus ending movement there). You can not woo troops and continue to move in the same turn.

Any traded units are placed under the new owner’s command token, which may require another unit to be discarded to make space.

Command tokens may not be traded.

Keep Trading

Player are able to trade units, crystals, and/or artifacts at keeps. A player who ends his movement on a keep may throw away a unit, crystal, and/or artifact from his hand. Another player may end his turn on any keep and take the cards or items.

Any acquired units are placed under the new owner’s command token, which may require another unit to be discarded to make space. A player receiving crystals may not exceed the normal three crystals per color limit. Artifacts are placed in the receiving player’s discard pile.

Modifications for PVP Cards

Mana Meltdown/Mana Radiance → Mana Growth/Mana Radiance

Mana Growth

Each other player may choose a crystal in their Inventory and get another crystal of that color. You may gain one crystal any one other play got in this way.

Mana Radiance

When you play this, choose a basic mana color. Gain two crystal of the chosen color to your Inventory. Each player who has no crystal of that color gains one.

Mana Claim / Mana Curse → Mana Gain / Mana Blessing

Mana Gain

Take a mana die from the Source and set it to any basic color. You gain 3 crystals of that color. Do not re-roll this die when you return it to the Source.

Mana Blessing

Same as the basic effect. In addition, until the end of the Round: Each time another player uses mana of that color from the Source on their turn it doesn’t count to the limit of one die per turn you can use from the source.

Mind Read / Mind Steal → Mental Recovery / Mental Heal

Mental Recovery

Choose a color. Gain a crystal of the chosen color to your Inventory. Each other player may search their discard pile for a basic action card of that color and put it to their hand.

Mental Heal

Same as the basic effect. In addition to that , you may search your discard pile for any action card of that color (no Spell) and put it to your hand.

Energy Flow / Energy Steal → Energy Gain / Energy Boost

Energy Gain

Ready a Unit. If you do, you must ready one Unit of level II or less in each other player’s Unit area.

Energy Boost

Ready a Unit. If you do, that Unit also gets Healed, and you must ready one unit of level III or less in each other player’s Unit area.

Modifications for Interactive Skill Tokens

Tovak

Mana Exploit

Once a round: Choose a color other than gold and gain a mana token of that color. Until the start of your next turn, other players heal 1 when they use mana of any other color on their turn, limit 1 healing per color per player. Then take this token back and flip it.

Norowas

Prayer of Weather

Once a round: Put this skill token in the center. Until the start of your next turn, the Move cost of all terrain is reduced by 2 for you (to a minimum of 1) and is reduced by 1 for all other players (to a minimum of 1). Then take this token back and flip it.

Arythea

Healing Ritual

Once a round, except in combat: Flip this to throw away up to two wounds from your hand. One other hero may throw away one wound from their hand.

Goldyx

Source Freeze

Once a round: Put this skill token in the Source. While it is there, other players can use one extra die from the source. On your next turn, gain one crystal of any basic color represented in the Source to your inventory (do not reroll that die), then take that token back and flip it.

Credit where credit is due

Most of the suggestions originated on the following threads on Board Game Geek:

Rebasing A Pull Request on GitHub

Thu, 07 Feb 2013 00:00:00 +0000

It’s generally good practice to rebase commits on a topic branch into a single commit before merging. It results in a much cleaner commit history, and makes rollbacks easier.

The Question

However, the question was raised: what happens if you…

fix a bug (commit 1)
create a Pull Request
get feedback via the Pull Request
fix the bug fix (commit 2)
rebase those two commits together (new tree-ish)
push that back to GitHub (requires push -f )

The answer is based on understanding that a GitHub pull request has two forms of commenting: * comments on the pull request itself * comments on the commits that the pull request encapsulates. These are the comments made on specific lines in the diff.

The Answer

When you rebase and then force that changed version of history up onto GitHub you are effectively throwing out the old commit (the old tree-ish no longer exists) and replacing it with a new one.

As a result any comments created on the diffs (and thus tied to a specific commit) will be lost, but the comments on the pull request itself will be preserved.

So, the proposed rule of thumb is to simply NOT rebase once you have made a pull request. Instead, just add commits to your topic branch. This will maintain the comment history for future people curious about this piece of code.

Alternate Solutions

There are alternate solutions, of course, but the consequences of them tend to not be worth it.

Rebase Anyway

Decide that you don’t care about maintaining the inline comments, then rebase and push -f back up to the server. The downside here is that at this point someone has already started looking at your code and has likely pulled it down. They will now be forced to blow away their old branch (or at least reset --hard back to a point in its history before your commit), which is a pain and not obvious unless you tell them directly.

Make A Second Topic Branch

You could close the first pull request after having gotten the set of commits to an approvable state, and then open a new pull request from a separate topic branch with all those commits having been rolled up into one. The problem here is that if your new pull request is merged in then git blame will point to the tree-ish of the new one and no-one will ever see the comments on the old pull request unless they search, but when they do they may find that the commits in the original request don’t exist in the codebase (they’re all under the rebased commit).

[Review] The Sketchnote Handbook (Video Edition)

Thu, 31 Jan 2013 00:00:00 +0000

Who should read this?

Anyone who’s seen The Sketchnote Army and wished they could do that. Anyone who’s sick of useless meeting notes they never remember, and never go back to read. Anyone who wants a way to provide information to people in a way that people will actually enjoy consuming, and not just skim through.

The best laid plans…

My initial intent was to create this review in Sketchnote form, but Sketchnoting is, in no small part, the art of filtering essential ideas from a stream of words, and presenting them in a semi-visual fashion in order to help convey and emphasize the important points. The problem is that The Sketchnote Handbook has already done this. Every point I wanted to note was something Mike Rohde (the author) had already created a succinct Sketchnote about. To create an even remotely comprehensive review I’d have to draw out most of the book.

So, I’m left with words.

Some background

Most people know me as either a programmer, or an adventurer, but not many know that I occasionally do illustrations for folks too.

I ordered this book because I’ve been fascinated with Sketchnotes; their look, their personality, and their ability to convey the essential information from any event. Dachary and I have been pondering not just writing our next adventure but Sketchnoting it as well. If we can pull it off, the result would be an incredibly engaging way of keeping up with an adventure.

I’d seen plenty of Sketchnotes, and with a childhood spent in art classes the technical details of how they were created wasn’t a question. Anyone who applies any thought to the matter should be able to figure that out (text + related doodles equals sketchnote). From a technical perspective they’re pretty trivial. What’s been missing is information about the approach. How does one go about sketchnoting? How do you manage to keep up with a speaker? What is the process by which one chooses what things to emphasize, what layout to use, when to draw and when to write?

And that, is where, and why the Sketchnote Handbook excels.

The Book

By page 18 this book has addressed the common problem of people running around claiming “I can’t draw”. It does this, by conveying the simple fact that Sketchnotes are about “IDEAS NOT ART”, points out that everything can be drawn with 5 simple elements (Circle, Square, Triangle, Line, Dot), provides a handful of quickie examples, and then proceeds to do what every other Sketchnote resource should have done: moves on.

To me, that was the moment I realized “Holy crap! This book is actually going to be about Sketchnoting not ‘Stick Figures 101’.” And that’s what makes this book incredible. Seriously, this is an incredible book, and one you must buy if you have any interest in learning to create your own Sketchnotes.

What makes this incredible is that it’s about the process of Sketchnoting. It says “Hey, this is what Sketchnoting is. This is why it’s valuable. Here’s how to listen. Here’s how you make a Sketchnote. Here are common patterns, and approaches people take to making them.” Only then, once he’s given you everything you need (146 very quick pages in) does he go back to the “Stick Figures 101”, which is probably good, because drawing is a lot like singing. People are convinced they’re horrible at it, which leads to them not having the guts to try it and find out that that can be pretty decent at it if they would only give themselves permission to try.

Because the book is itself a Sketchnote, there’s no need to skim to “the important part”. It is exclusively important parts, and key concepts. While you don’t need to be an artist to create amazing Sketchnotes, Sketchnoting is itself an art form, and as such you can’t define it with explicit rules. There are core concepts, and basic techniques that are shared across all Sketchnotes, but like all art, there’s no “correct” way to do it. There are only guidelines that you may or may not choose to follow, and Mike’s done a wonderful job of conveying those, and showing how those concepts play out through examples from many talented Sketchnoters with diverse styles.

The Video Edition

The quality of the videos is quite good, even though, for the most part, you’re just watching Mike at a desk or literally looking over his shoulder as he’s drawing. But… I’m not full sold on them.

I think that, for the most part, the book does a better job of conveying the information. Much of the video feels like “Highlights from the book”, but there is definitely some additional value there. There’s a surprising difference between reading that he’ll bring a speaker’s photo up on his iPhone and seeing him holding the iPhone whilst propping up a corner of the notebook with the same hand and drawing with the other. Watching him draw even the simplest of visual elements like dividers and lines is somehow much more… accessible, and achievable, than seeing a static page of them. This is, I think, incredibly valuable for people who don’t have faith in their drawing ability.

The 9th video is the most important one in the series, because it’s just watching over Mike’s shoulder, in real time, while he Sketchnotes a talk. It’s fascinating to watch what information he chooses to incorporate, and what information gets left out, to see some things the speaker said earlier on enter the page a minute or two later, when you thought he was going to leave it out entirely.

I have to say though, I wasn’t thrilled with the way that most of the videos were edited down into two to three minute clips. To me that was more frustrating, because you’re not going to watch just one. You’re going to watch a swath of them, but you keep having to go back and click on the next one. I think it would have been much better served by breaking the 70 minutes of footage down into three of four sections.

If I had to do it again, knowing what I know now, would I buy the video edition? Yes, if only for the 9th video. If I was to recommend this to someone who wasn’t confident in their ability to doodle though I would absolutely recommend the video. It really helps to show that Sketchnoting is something that anyone can do.

With that said, I can’t recommend buying the “Video Edition” of the physical book. When you buy it there’s a stiff square insert in the back that looks like it contains a DVD. It doesn’t. There’s a pull-tab that reveals a code to the web site where you can watch the video on the Peachpit website, which feels like a total deception to me. There is, however, a “Multimedia DVD” edition which does come with a DVD. Buy that if you want the video, or get the regular version and go to Peachpit.com and pay for the video separately.

Summary

If you’re interested in trying you hand a sketchnoting, then buy this book ( or get it with the DVD).

Contest!

Yup. To all those lovely folks who’ve made it this far I offer you a simple contest. Draw me something that makes me smile. Ball point pen, watercolors, crayons, charcoal, whatever. Stick it online and tweet me a link. First one to make me smile wins a copy of the regular (sans video) edition.

[Update: Too late! I’ve been made to smile! Thanks for reading this far though. Now, go buy a copy. It’s worth every penny.]

Git: pushing and pulling from multiple repos

Thu, 31 Jan 2013 00:00:00 +0000

Lets assume you’ve already cloned a remote repo and have been working with it. Now, someone has set up a second repo out there for the same codebase, and you’d like to interact with both.

*Please note: The following is based on the assumption that you have write privileges to the second repo, but don’t worry, you do essentially the same thing if you don’t and I’ll cover the differences at the end. *

git remote add <local_name_for_remote_repo>
git checkout -b
<local_name_for_remote_repo>/master
- could be any branch on that repo, not necessarily master

Now, your new local branch is now set up to track (push and pull to/from) the remote repo’s “master” branch. All your pre-existing branches will continue to track whatever they were tracking previously

A practical example:

git remote add repo2  git@github.com:masukomi/kudos.git
git checkout -b repo2_kudos -t repo2/master

Workflow

Let’s say you’ve decided to add a new feature in the kudos repo we just connected to.

Checkout the repo2_kudos branch
git pull to get the latest code from repo2/master
git checkout -b adding_feature_x
- this new topic branch is not yet tracking anything so if you attempt to push or pull it won’t work, because it won’t know what endpoint you want to interact with.
Make your changes on this topic branch.
When you’re ready run git push -u repo2 adding_feature_x
- This will do three things:
  1. It will create a new branch in the repo2 repository named “adding_feature_x”
  2. It will push the contents of your adding_feature_x branch into the corresponding one on repo2.
  3. It will configure things so that your local adding_feature_x branch is now tracking the remote adding_feature_x branch so push and pull will work without additional arguments. You must pass the -u parameter for tracking to be set up here. If you fail to pass the -u parameter at this point then push and pull won’t work without additional parameters. You can, however, set up tracking after the fact with git branch -u repo2/adding_feature_x

Now that you’ve pushed your changes to the new branch on the remote repo you can initiate pull requests from your topic branch into the main branches (if you’re using github) or you can simple tell others about it so that they can interact with it.

Keep in mind that it’s best practice to regularly pull from your main branch into your topic branch (repo2_kudos into adding_feature_x in this case) so as to avoid large merge conflicts. Alternately you could pull from the corresponding main branch on the second repo (repo2/master in this case) since they should be equivalent.

When you don’t have write privileges

If you don’t have write privileges to the second repo things change slightly. The difference is in where you push your new topic branch (adding_feature_x) to. You can either push as a new branch on whatever repo your local repo was cloned from (if you’ve got write privileges to that) or you can create a third remote repo that you control, and push the branch to that. The third repo would be configured in the same way as the second, and you should be able to push to it in the same way we pushed to the second. Git makes it easy to flow code from one repo to another, or through multiple repos.

Why you should wear a bow tie

Fri, 25 Jan 2013 00:00:00 +0000

In many situations, the standard tie has become de rigueur, and so commonplace that it is generally only noticeable in its absence. This is not something that can be said of the bow tie.

Imagine you’re going to a job interview. If you wear a tie no-one will take note of it (unless you’re a lady). It’s simply what you do. A bow tie on the other hand, says a number of things about you, and makes you more memorable.

A bow tie says that you have made a conscious decision to improve your appearance. It says that you are capable of making your own decisions, and not just follow some common list of what you “should” wear.

A bow tie says you are capable of not only making your own decisions, but are willing to display them publicly, and defend them when needed. - Sooner or later someone’s going to ask why you’re wearing a bow tie, and you’ll have a good reason or four.

A bow tie says that you have taken time to learn a skill that the vast majority of the men around you don’t have (learning to tie a bow tie).

A bow tie is memorable, if for no other reason than the fact that they are so rarely worn.

Bow Tie Wearers: Sir Winston Churchill, Pee-wee Herman, PSY, The 11th Doctor, Indiana Jones, and the classic Playboy Bunny outfit (can’t forget the ladies).

Where to get one? Well, there are a variety of places, but I like checking OoOTie first, because they’re great guys, and second because have the best paisleys, plus nifty things like embroidered mars rovers, silk screened mustaches, and more. And no, I get nothing from promoting them.

P.S. For those days when you’re wearing a standard tie, please learn how to tie a Half Windsor or a Windsor. There are far too many lopsided tie knots in the world.

Life: An Instructional Flow Chart

Thu, 10 Jan 2013 00:00:00 +0000

An instructional flow chart to help live a better life.

(click to embiggen)

I’m thinking I need to artify this and make it into a t-shirt. Drop me an e-mail if you’d be interested in one.

Office Memo

Thu, 06 Dec 2012 00:00:00 +0000

Dear Sir or Madam:

You may not be aware but liquids are capable of flowing through holes. If you place a container of liquid in such a manner that its opening is below the level of the liquid, the liquid will flow through that opening.

Please take a moment to consider the implications of this, and discuss them with your coworkers, as some of them are apparently unaware of this fun fact. Yesterday, one of them placed a carton of cream on its side, with the opening below the level of the fluid inside. As a result, we now have cream all over the bottom of the fridge.

P.S.

The responsible party may want to consider taking a sick day, leveraging our health plan, and going to see a doctor. Potential brain tumors should not be treated lightly.

Never register a domain name with your hosting provider

Mon, 19 Nov 2012 00:00:00 +0000

A smart developer I respect recently asked my why I didn’t just register my domain names through my hosting provider. I hoped he was joking, that he knew why this was a horrible idea. He did not, and I know some other smart people who register domains with their hosting providers. Education is needed.

The problem is simple: conflict of interest. Should you ever decide to switch to a different hosting provider it’s in their best interest to prevent you from moving your domain. Why? Because if you point it to some other hosting provider you stop having to pay them.

It doesn’t matter how great your current hosting provider is. It doesn’t matter how great their morals, customer support, or promises are. There is no guarantee they won’t be bought by an ass-hole tomorrow. There’s no guarantee some greedy concepts won’t start to permiate their management.

Your domain name is your online identity, or that of your company. Do you really want to risk the possibility of having it stuck at a company with rapidly declining quality of service or support? Or, maybe a company that starts jacking prices through the roof? If your hosting provider controls your domain name’s registration you are taking this risk.

The solution, however, is simple, and cheap. Transfer your domain to a company that is primarily a registrar today. You don’t need to change your hosting setup, and you don’t need to wait until your current domain regstration is about to expire. When you transfer a domain name you get the current time remaining on your registration plus the year, or more, you choose to pay for at the new registrar.

Currently I’m recommending people go to Hover.com. I don’t get anything for referring you there. They’re just refreshingly easy to use and don’t try and sell you any other services.

Before you say “my hosting company would never prevent me from leaving.” I would remind you of the famous saying

Those who cannot remember the past are condemned to repeat it.

George Santayana

While it may not happen much these days, back when hosting providers started offering registration services this practice of locking customers in was actually quite common. I encountered quite a few people who were forced to abandon their domain name because they wanted to leave a corrupt, or at least bad, hosting company.

There are some measures in place to help prevent this, but you will still have a miserable time getting your domain away from a hosting provider that doesn’t want you to go and tries to thwart your exodus.

If you have any domain names that are currently managed by your hosting provider, please transfer them away ASAP. Most of you won’t have a problem. Some of you will. For those who will, keep in mind that it’s much better to learn your hosting provider is an ass now, then when you actually need to move it at some point down the road.

Update: A response to the comments

The key to this happening is that hosting providers your register a domain name through will frequently set themselves as the administrative contact, because, they would argue, they are the ones administering the domain. You’ve paid them to do so. BUT the administrative contact also holds the keys to the kingdom as it were. It’s their email address that will be involved in the confirmation process during a transfer, and their approval of the transfer that will be required.

It’s absolutely true that the situation has gotten better, and that you’re safer with the large, well established hosting companies, but I’m not trying to spread FUD here. This has happened in the past to many companies and individuals, and I would not be surprised to hear that it’s still happening. Yes, there are higher authorities you can go to, but in the end most people who encounter this problem fight with their evil host for a month or more, and don’t know who that higher authority is, know how to report it to them, or have enough fight left in them to bother starting the whole process over again.

Some helpful folks have mentioned some other great registrars in the comments, and I do have domains at Gandi.net but I’m recommending Hover because they don’t try and sell you anything else and the’ve got a nice uncluttered and easy to figure out UI.

An unexpected benefit to being an adventurer

Mon, 29 Oct 2012 00:00:00 +0000

The edges Sandy were upon us last night and Dachary commented about how I wasn’t taking the storm too seriously. It’s true. I’ve been pretty chill about it. But here’s why: we’re adventurers, and are pretty much good to go on a worldwide adventure at a moments notice, and it turns out that our “life on the road” kit makes a pretty damn good disaster kit too.

If the power goes out we’ve got a JetBoil propane stove with a backup canister. If we run out of propane we’ve got the multifuel stove and spare gasoline. If we run out of gasoline we’ve got oil. If we run out of oil we’ve got some alcohol. We’ve got a pretty good first-aid kit (including sterile needles and syringes and splints). We’ve got a little camp food and we’ve got a bad-ass water purifier that can filter out things as small as viruses (Brita’s can’t dream of this) so I wouldn’t be too bothered if I had to go suck up water from puddles on the street.

We bought six gallons of water, and filled up another six liters worth of camelbacks (we have at least another 25 liters worth of bladders and Camelbaks we could fill up if we wanted to). We bought some non-perisable things at the store, but not too much as it’d be pretty surprising if Boston fell into Katrina level badness from this.

If it gets too cold we can set up a tent in the house to conserve our radient heat. We’ve got plenty of sleeping bags and air mattresses for us and the dogs. Living in New England, and occasionally riding motorcycles at speed over mountain ranges, we’re also set on the cold weather clothing front.

And, when it goes dark we’ve got headlamps, tent lamps, and spare batteries.

So yeah. I’m not too worried.

Creating an Interview Worksheet

Fri, 12 Oct 2012 00:00:00 +0000

Once again, I’d like to pick your brain.

I’m working on an “Interview Worksheet”. It’s a simple form that you’ll fill out while interviewing someone, and prepping for an interview with them. There is, of course, a section for questions you want to ask them, one for taking notes during your discussion, and one for the common “How would you rate yourself on skill X” questions. But, I’ve also got a section where you can quickly rate the person on various attributes that you tend to look for.

There are two things I’d like to hear from you:

Suggestions for other rateable attributes that you look for that aren’t in my list below.
A quick piece of advice for other interviewers: just one or two sentences, something you try and look for in a candidate that others should consider looking for too, or maybe something you do in an interview that reveals important details.

My idea is to collect the advice and put it on the back of the sheet. Better to have helpful suggestions from other smart interviewers than a field of white.

Here’s my current list of rateable attributes. Each will be presented on the form in such a way that you could fill them out whilst keeping the meaning of your actions hidden.

Experience (how much?)
Personality (how good?)
Skills (how skilled are they?)
Group Fit (you may love them, but how good will they be with the team?)
Communication (you know, like… with the words ’n stuff)
Passion (how passionate are they about the task you’re interviewing them for?)
Additivity ( A measure of how many talents / skills they’d bring to your team that you don’t already have. I could really use a better word for this, and would love your suggestions.)

So, what do you look for? What tips do you have to share?

There's always more to learn

Wed, 10 Oct 2012 00:00:00 +0000

My mother was an incredibly talented artist. For most of my life, she made here living teaching private students, and getting them ready for entry into art colleges.

Once upon a time a student of hers got her a present. It was a Horse-hair calligraphy brush, a solid ink stick (add water and rub), and an instructional book on Chinese calligraphy.

She was very worried about giving the gift though. She didn’t want to instruct a teacher she greatly respected by giving her an introductory how-to book. But it was a gift from the heart, and one she believed my mother would enjoy.

My mother was a master of all the traditional western fine-arts media: oils, pencils, sculpture… but she had no direct experience with Chinese calligraphy, and I suspect they’d had had a discussion about it during one of their lessons.

It was one of the most precious gifts she ever received. It taught her something, and meant all the more because of the students courage in giving it. She gradually worked through that ink stick, playing with calligraphic brush lines, and remembering who gave it to her.

She never let ego get in the way of learning, and it was a lesson I’ll never forget.

There’s always more to learn, and sometimes, it comes from unexpected places. Always welcome it with open arms.

Don't talk about what your product is

Mon, 01 Oct 2012 00:00:00 +0000

It’s really important, not to talk about what your product is.

Nobody Cares.

Talk about what the customer feels, wants, dreams of, etcetera.

That’s what they care about.

– Amy Hoy

Speaking on the Ruby Rogues Podcast #72

The Entrepreneur's Notebook (part 1)

Thu, 27 Sep 2012 00:00:00 +0000

Part 1 of 3

What is an Entrepreneur’s Notebook?

Simply put, it’s a collection of entrepreneurial ideas for businesses you have, or are thinking of creating: products, marketing, sales, strategy, etc. The techniques that follow will help you to massively multiply the quantity of ideas you have, your recall of past ideas, and your ability to create connections between ideas. And the only thing you have to buy, is a notebook.

These three posts will lay out the process, why it works, techniques for making a more useful notebook, backup strategies, and tips for choosing a good notebook, and more.

Step One: Get a good notebook.

(CC photo by thomas@flickr, on Flickr)

First, you need to get a notebook; a real, paper notebook. Lots of you will think “But I love [insert favorite note-taking app here].” Trust me, you want a physical notebook. A physical notebook always exists. It doesn’t disappear when you quit it. It doesn’t need to be launched. It doesn’t get low batteries, or need to be woken up, and you won’t be able to forget about it when you’re constantly carrying it around. It sits there, on the edge of your vision, silently encouraging you to write in it.

It’s easy to ignore, or forget about something you wrote down in an app, especially when it isn’t visible at the moment, but, your notebook is right there, and as you flip through it, looking for the next blank page, you are reminded of all the other ideas you’ve written down in it, and connections begin to form that wouldn’t otherwise.

Now, “Good” is very subjective when it comes to notebooks, but you’ll find my suggestions on what to look for in Part 2.

Step Two: Carry it with you everywhere.

cc mush m.

The act of carrying your notebook with you constantly is far more important than which notebook you choose. Make sure you’ve always got your notebook and a couple spare pens or pencils. While you’re buying your notebook, take a moment to grab yourself some writing instruments that you’ll actually enjoy using, rather than whatever cheapy ball-point you found on your desk.

Don’t leave your notebook in your bag

Pull it out and put it on your desk when you get to work. Set it on the end-table when you relax at home. Make it a constant part of your daily routine.

(CC photo by koalazymonkey, on Flickr)

Step Three: Write every idea down in it immediately.

Time and again you’ve sat at your desk, read an article, and had some little spark of an idea go off, and then kept reading and promptly forgot all about it. Don’t ever do that again. It doesn’t matter if it’s a good idea or not. What matters is the act of capturing and exploring it. Whenever you have one of these ideas, stop your self immediately and write it down in your notebook. The article / video / TV show / boring business meeting will be there when you’re done.

My ideas notebook travels in my backpack, which goes with me just about everywhere, but I also carry a tiny pocket reporters-notebook in my jacket pocket so that, if I have an idea while walking down the street, I can just stop walking, pull the pocket-notebook out, jot down my idea, and keep going. Interesting ideas are not allowed to escape undocumented.

If you can take a few minutes to explore the idea, do so. You don’t have to flesh it out completely, just let the thoughts flow, unjudged, and unimpeded until they come to a natural stopping point.

If you have an idea for a web interface, sketch it out. If you thought of a great way to market something, write it down. If you thought of a gotcha that might send everything swirling down the drain, write it down. Thought of some software that would make creating it easier? Write it down.

It is very important that you do not worry about the quality of the ideas at this point. Just get them down on paper; good, bad, and mediocre.

Repeat.

The more you do this the more ideas you’ll capture, and not just because you’ll be accreting them over time. The act of capturing these ideas helps you to notice them more, and the more you notice, the more you write down. You’re having interesting ideas constantly, everyone is, but they slip through the graps of most people because they simply haven’t trained themselves to capture them.

Don’t use it for grocery lists

You’ve got to draw the line somewhere. Doodling doesn’t affect the quality of the content in your notebook because it doesn’t contain information your brain needs to parse, but things like grocery lists contain information that’s irrelevant to your projects and become random noise that pollutes an otherwise useful resource.

With that said, you may find it to be a good place for to-do lists related to the projects in your notebook. I generally avoid this myself. My task-lists are constantly growing and changing.

Step Four: Evaluate

The more you do this the more your brain will start buzzing about all these possible businesses you could be starting or projects you could be working on. Choose whichever one you’re most excited about at the moment and dive into it. With me, I just hit a point every couple days where my brain is so abuzz with ideas for some app I want to create that I have to just stop and write for the next ten to twenty minutes. It’s almost always one that I’ve accreted a page or two of notes on already.

When you find one that you really think might be worth starting as a business, take some time to try and figure out every possible way you could monetize it. How would you have to market it? Where would you have to market it? How bad is the competition? If there isn’t any, take a minute to figure out why. Do a little research and see if there are actually enough people interested in this type of thing.

Draw circles and arrows. Make connections. Read Dan Roam’s: Back Of The Napkin. It is an incredible resource that is guaranteed to quickly, and easily improve the quality of your notes.

Why this works

At the start of this post I promised this technique would “…help you to massively multiply the quantity of ideas you have, your recall of past ideas, and your ability to create connections between ideas.” Here’s why:

Physically writing creates links between the spacial and verbal parts of the brain, and studies have shown that by some strange quirk of biology, the brain thinks that writing something is the same as if we were actually doing it. This is similar to how the practice of actively visualizing something can trick the brain into thinking it’s actually doing it.

Conversely, the more time you spend trying to recall something, the more likely you are to forget it in the future. It is better to look something up directly, than attempt to dredge it from your hazy recollection of a half-remembered thought stream.

Studies have shown that writing things down longhand improves recall. In part this is due to the fact that it increases blood flow to the parts of the brain that handle memory. If I remember correctly your recall is typically improved by 10%. Alas, I can’t find the study to quote for you.

“…a psych professor at Dominican University of California found that people who wrote down their goals, shared them with others, and maintained accountability for their goals were 33% more likely to achieve them, versus those who just formulated goals…* and a survey of note-taking studies found several examples where [longhand note-taking] helped students with recall and academic performance.” - LifeHacker

Now, there haven’t been any studies I’m aware of that address my claim as to quantity of ideas, but I find that entrepreneurial thinking is a skill that improves with practice, just like any other. Carrying an Entrepreneur’s notebook is just as much about having a central place to capture and connect ideas as it is about having a process that encourages you to think entrepreneurially on a regular basis. As I mentioned above, by getting in the habit of writing down every entrepreneurial idea the moment you have it you become more aware of them.

As to my final claim of creating connections to ideas, that should be obvious. You’ll have a book of them that you’ll be regularly flipping through. How can you not make connections in that situation?

What next?

Go get yourself a blank notebook!

If you want some helpful suggestions that will improve the usability of that notebook, continue on to Part 2.

The Entrepreneur's Notebook (part 2)

Thu, 27 Sep 2012 00:00:00 +0000

Tips for more productive note-taking

Part 2 of 3

One notebook for everything

While there are some good arguments to be made for per-project notebooks, I’m going to strongly recommend you avoid this approach until you find yourself with a project that is starting to overwhelm your main notebook and is likely to consume many more pages.

The problem with multiple notebooks is that two things will keep happening if you take this approach: 1) you won’t have the “correct” notebook with you when an idea strikes 2) you’ll end up with a lot of notebooks with almost nothing in them, which isn’t just wasteful, but leaves you feeling like you’ve let the ball drop on an idea.

Title every page with the project name

Don’t worry about getting a good name for it at the start. Just write down something that describes it well enough for you to know what you were talking about like “Chihuahua Jackets”. I typically write my title over a thick black line that extends to the edge of the page and is always at the same place on the page so that as I’m flipping through pages I can easily find the ones pertaining to the idea I’m looking for.

When I eventually do figure out a domain name for the site (and have bought it) I’ll go back and write the new name above the old titles, so that the new name is on all the pertinent pages.

Only one project per page

Sometimes you’ll just have one wee idea to write down. Don’t be tempted to use that empty space on the bottom of the last page. If you do you’ll end up with a notebook where everything is mixed together on every page and hard to find.

Just flip to the next blank page, give it a title and start writing. Don’t worry about wasting paper, because you will have more thoughts on the topic later. When you do, use your Table of Contents (see below) or flip back until you find its page and add the new thoughts to it.

Doing this, you’ll wind up with one project’s notes interspersed with pages of notes from other projects. This isn’t a bad thing. When you’ve got an A5 sized notebook (or larger) you’ll have a decent amount of text (or drawings) on each page, and seeing the titles from your other projects as you’re looking for something will help keep those projects fresh in your mind.

I find that a typical pocket-sized Moleskine is detrimental to this kind of note-taking because you simply can’t fit much on a page. The extra portability just isn’t worth it in the end.

No spare pages

Sooner or later you’ll have an idea where you’ll be tempted to leave a few blank pages at the end of your note for the thoughts you plan on adding later. Don’t do this.

You will never guess the right number and you’ll end up with notebook filled with swaths of blank pages, which leaves you feeling that you’ve failed to flush out an idea, and that you’ve been wasteful to boot. Plus, good notebooks aren’t cheap.

Number each page

This will be important in the next step, but don’t bother numbering them all in advance. That’s just annoying. Number them as you go. Maybe pre-numbering a dozen or so pages ahead if you really feel like it.

Create an Table of Contents

It’s easier to do than you might think, especially if you’ve followed the two steps above. First, set aside the first 3-5 pages of your notebook, and write “Table of Contents” on the first one. This is the only exception to the “No Spare Pages” rule.

Since you’ve only got one project per page, each page has a page number, and you’re titling each page by project, it becomes much easier to reference where things live in your notebook.

When a new project / topic gets entered flip back to the table of contents and add a new line. I recommend skipping one line between projects, because it’s hard to predict which ones your brain will get all excited about in the long run, and the ones that do will end up with a lot of associated pages. Write down the name of the project and follow it with the page number of the page you just added about it. Just write in the new numbers as you add pages. For example:

Entrepreneurs Notebook: 11, 27, 29-32, 44

I find it easiest to add to, or update the table of context when I’m flipping through the book later. Trying to remember to write down the page number in the index when I’m having the both risks distracting yourself (“oh yeah, I forgot about that other project…”) and feels a bit too much like work. My table of contents frequently languishes until I am reviewing or need to find something specific, then I’ll go through and add the new entries that hadn’t been noted since the last time. Usually it’s just a handful.

If you’ve got a page that really important to the project, and you’re likely to need to reference repeatedly, then circle (or similarly highlight) the page number here.

Doodle in it

Seriously. Even if it’s just silly swirly things to alleviate the boredom of a meeting. The act of using your notebook for something as inconsequential as doodling lowers the barrier to writing in it. If you just use it for “serious” stuff then you’ll be more hesitant to open it up to note those half-formed ideas that are still just tickling the edges of your brain.

A new notebook can be somewhat daunting. I recommend that the first thing you do with a new notebook is to give it a title page, and doodle on it. Once you’ve done that it’s no longer perfect, and pristine. It’s no longer limited to pretty or good things. Now, you don’t have to worry about the quality of the stuff that comes next.

Emphasize the Important

Wrote something down that’s particularly important? Draw a box around it. Circle it. Underline it. Use big arrows. Use red ink. Do whatever it takes to emphasize the things that are important to you. It’ll make them stick out when flipping through, make them easier to find when searching, and just make your notebook more interesting looking.

Save non-business ideas too

While I wouldn’t recommend using your Entrepreneur’s Journal for diary style journaling, or throw-away things like grocery lists, you are going to have some interesting thoughts that aren’t necessarily related to business. Maybe you’ll encounter a great quote. Maybe you’ll watch a a great talk and think of some new goal to work towards. This will help reinforce the idea that this is where to go when you have a neat idea.

Accept the rough edges of life

Doodling, especially if you doodle in margins, has the side-effect of making it easier to accept the times when you’ll need to cross out a misspelled word, or scratch out an “incorrect” thought.

Accept that you will make mistakes and scratch things out. It’s ok. This isn’t a notebook of perfect things. It’s a notebook of thoughts, and ideas.

Making things readable.

(CC INK photo by anroKath on Flickr)

Most people I know are convinced that their handwriting is crap. Some of them are correct in that belief. Improving it really isn’t that hard though. All it takes is a little practice, and a little mindfulness. Austin Kleon has improved his by finding examples of beautiful handwriting he admires and working to emulate it. My recommendation, if you want to improve yours, is to write the alphabet once a day, and be mindful as you write. If you create a particularly egregious piece of handwriting, scratch it out and redo it, or endeavor to make the words that follow it as readable as possible.

As a side-effect improving your handwriting will increase the chances that handwriting recognition software (OCR) will be able to understand it (see Part 3)

The Entrepreneur's Notebook (part 3)

Thu, 27 Sep 2012 00:00:00 +0000

Notebook choices, and backups

Part 3 of 3

What about backups and searchability?

This is one place where the digital age is unquestionably superior. Dropbox, iCloud, email… there are myriad ways to back up your digital writing, and text is easy to search. On the mac, Spotlight gives you great search across every document you’ve ever written and searching within a document is easy in any text editor. Paper… not so much.

Searchability

In practice though, searchability is not a big deal, especially if you’ve got a Table of Contents (see Part 2), but even without one, you’re just flipping through a notebook’s worth of pages, that are all clearly titled by project. Finding your notes on a given idea turns out to be fast and easy, and as I mentioned in Part 1, the process of flipping through pages helps to keep other ideas fresh, and connect things that wouldn’t otherwise be connected.

Backups

This, is a notable limitation. The best strategy I’ve found is to simply take a picture of it. If you’ve got a smartphone the quality should be plenty good to zoom in on your computer and read whatever’s there. If you don’t have a smartphone any digital camera should have decent enough resolution.

I should call out the Evernote Smart Notebook. “For the Evernote Smart Notebook by Moleskine, Evernote finds the dot pattern and even corrects the skew of the photo. This means that the images that end up in your account are perfect for Evernote’s handwriting recognition, so that you’ll be able to find you thoughts anytime. "

Having had personal experience with handwriting recognition I can say that it absolutely can work, if you have clean handwriting, but, if you’re scribbling down ideas as fast as they come to you, you’re handwriting is not going to be “clean”, and OCR software is terrible about dealing with the more visual note-taking styles. Imagine you wrote “bigger” in a bubble with an arrow pointing to a diagram? How is the software supposed to know where to put it in a text only version of your page? I wouldn’t even know where to put it. With that said, Evernote is probably the best tool currently available for backing up your notebook pages, and there are very few people trying to tackle this particular problem.

Scanning vs. Photographing

In general scanning a bound book is annoying. You can’t run the pages through an automated scanner, and on a flatbed scanner you have to press down consistently on the spine for the length of the scan or risk having a shadow over everything written close to the spine.

While scanning is always going to take longer, and be more annoying than simply photographing your notebook’s pages, it will always get you better results. But, you have to ask yourself if it really matters enough to bother. In my experience it doesn’t. I almost never reference scans, and if I did manage to loose a notebook I’d previously photographed or scanned I suspect that I’d just print out the relevant pictures and staple them into my current notebook, or just copy the info.

The Boundless Notebook mentioned below sidesteps the major scanning problems by letting you use standard 8 1/2” x 11" paper which you fold in half (approximately A5 size). When you’re done you can pull it out, flatten the fold, and put in in a scanner with an automatic feed, or do them one by one on a flatbed scanner, without having to hold down the spine and worrying about shadows. As a bonus, they’re easy to put back together when you’re done.

If having high quality backups is important to you, I can’t think of a better solution than the Boundless Notebook, especially when combined with an automatic feed scanner, which you’ll frequently find on those ginormous copy/scan/fax machines at work.

Scanning Tip

Most scanners have a white surface behind whatever you’re scanning in order to reflect the maximum amount of light back to the scanning head. This is a problem when scanning something with writing on both sides because it can make the back side visible through the paper. To get around this, put a piece of black construction paper behind whatever you’re scanning. The light that passes through your paper won’t be reflected back to the scanning head. You can try scotch-taping the black paper to the top of your scanner but it may cause issues with automatic-feeds.

Notebook suggestions

If I was to recommend a traditional notebook I’d vote for the Rhodia Webnotebook in the A5 size with “Dot Grid” pages. A5 is roughly the same size as an 8 1/2" x 11" page folded in half. It’s small enough to carry around but big enough to fit decent sized sketches of your next brilliant ideas. A dot grid is what you’d get if you removed all the lines from grid paper but left a dot where each of the intersections used to be; a literal grid of dots. Grid paper feels like it simply has too much on it for me, and lined paper feels too restricted to writing. Dot grids provide a nice balance. The dots stay out of the way. Your paper isn’t covered with lines. Your writing stays relatively straight, and it’s easy to sketch things with the grid of dots to guide you.

If the dot grid doesn’t seem your style, I’d recommend picking up an A5 (“Large”) Blank Moleskine.

(Look closely to see the dot grid - CC Photo by retro traveler, on Flickr)

Rhodia’s Dot Grid notebooks are somewhat hard to find, but you can get one from JetPens along with some nice writing utensils and free shipping, or pick up a Large Blank Moleskine from Amazon. Moleskine has recently come out with the Evernote Smart Notebook (see the section on this above) which comes in a variety of sizes, in ruled and dot grid variants.

Another interesting option is the Boundless Notebook by Jim Whittle. It’s essentially a large piece of leather with a couple carefully placed slits that allow you to slide your own paper in. What’s cool about this, is that the more creative folks out there can pre-print your pages with whatever structure best suits your needs. Kind of like those pre-printed day-planners, only designed by you to meet your needs perfectly. The downside to this notebook is that you’ll need to find something to do with the pages once you’ve filled them and need to insert new ones. But, maybe that’s a good time to just photograph them or scan them in for backup.

And, of course, there’s the Traveler’s Notebook by Midori:

(CC photo by guccio@文房具社, on Flickr)

This gorgeous soft leather notebook comes in two sizes and has an almost cult-like following, and a good variety of accessories, but the large version’s unique sizing means you can only get refills specifically designed for it, and there are only a handful of vendors in the US. There’s a good review of the Traveler’s Notebook here.

I’ve fallen in love with my Traveler’s Notebook.

Choosing the right instrument

In my opinion, finding a good writing instrument greatly enhances and encourages the continued use of your notebook. It doesn’t matter what pen, or pencil, you use, and it certainly doesn’t have to be anything fancy or expensive. What matters is that you enjoy the one you’ve chosen. Maybe you choose your pens for the looks, maybe for the feel, or the way the ink flows. Whatever makes you happy.

For a while my go-to pen has been the OptiFlow Rollerball from Staples, because I love how smoothly it writes, and how much ink it flows onto the page, and they have them in the supply closet at work ;) But I’m starting to use the Pilot Double-Sided Brush Pen for writing and the Kuretake No. 13 Fountain Brush Pen for drawing. I love pens with thick confident lines. They remind me of the felt-tip pen my father always used to use.

If you’re just “meh” on your current tool, check out the Selection Guides at JetPens. Then buy yourself a sampler of pens that sound interesting to you, and give them all a go.

Interested in getting an Entrepreneur’s Notebook?.

If 150 people express an interest, in an Entrepreneur’s Notebook style refill (supporting the workflow described in part 2) I’ll make one. It would have a section laid out for your Table of contents, a dark line to go below the project name at the top of each page, and a circle in the lower outside corners for the page numbers, probably with a dot-grid body. They’d be designed as refills for the Midori’s Traveler’s Notebook, but could also be used as stand-alone notebooks.

Please, let me know you’re interested so that we can make this happen. ;)

References:

Appcelerator: extortion is just part of the job...

Sat, 22 Sep 2012 00:00:00 +0000

Appcelerator was recently caught extorting one of its free users, and then that users client for £5000, and then others spoke up to say it’d happened to them too.

Initially it looked like it could have either been a bullshit company policy, or just a salesperson lacking in morals. In the end, it turns out to be both, but the response by the CEO is why I would strongly encourage you to never use an Appcelerator product (free or otherwise) for your project.

He starts out with a kind of hand-wavey apology that doesn’t really address what happened, and mentions “confusion over licensing” when the user’s real confusion was why they were being extorted. But, eventually he added a comment that did address what happened … kindof:

Let me first say that you are right, this should not have happened and it is totally unacceptable to have contacted your customer if that is what you say has happened. We should NEVER do that EVER without your permission or without your assistance. This is WRONG and if this happened, it’s not appropriate. I don’t know how to be more clear than that.

At first read, this part sounds good, but then you notice one very subtle, but important, thing that’s left out. He mentions that it’s “unacceptable” for them to have contacted the user’s customer… but there is *no mention of it being unacceptable to attempt to extort money from the user themselves. *

And then there’s the “if that is what you say has happened” clause. This is after they spent time looking into the problem, and then proceeded to apologize for it. The apology implicitly states that this incident occurred, otherwise why would you apologize? To essentially say “I’m truly sorry for our actions but really you could just be a lying schmuck” That’s bullshit. You should either have the balls to accept that the bad thing happened or to call the user a liar. But that’s not the truly egregious part…

However, not everything is done to be malicious and we certainly NEVER intend to extort money from anyone. I simply don’t see how you can draw a straight line from spending literally tens of MILLIONS of dollars this year alone on Titanium and providing it for FREE to well over 98% of the users – and then say that we’re “extorting people”. Let’s get some perspective.

Was the sales rep over eager and trying to hussle to get a deal? Probably. In my opinion, that’s the job of the rep and we work with hundreds of new paying customers each quarter and we’ve only had a few complaints about it.

“…we certainly never INTEND to extort money from anyone…” (emphasis mine). You don’t intend it but… but what? This is just “one of those things” that happens from time to time?

“…we’ve only had a few complaints about it.”

Wait… what?! You’ve had multiple complaints about your salespeople attempting to extort money from users in the past… and they’re still doing it?!

Notice, that in none of the CEOs responses is any mention of having reprimanded, or better yet, fired the salesperson in question. There is no mention of talking to the whole sales team to make sure they understand that they are not allowed to attempt to extort people. Obviously, since this has happened multiple times in the past this is either not something the salespeople understand, or something the company is actively encouraging.

If the former it speaks of a hiring process so broken that it repeatedly hires individuals with moral compasses so broken that they don’t understand that it’s wrong to extort people, and so stupid as to not realize that it’s illegal. If the latter, then you’ve got a company with a broken moral compass that is spreading that disease to its employees.

There is one other logical explanation. They’ve had one particular salesperson who has been repeatedly extorting people for money, received multiple complaints, and for some inexplicable reason is still employed there.

So, which is it Appcelerator? Are you morally bankrupt and encouraging your employees to follow your lead? Are you repeatedly hiring morally bankrupt individuals? Or, are you so lacking in concern for your community that you refuse to fire a salesperson who keeps extorting its members?

I hope you’ll give us the same respect and professionalism as well.

You know, I think I’ll do just that: “Fuck you Appcelerator.”

Oh, was that not respectful, or professional? NEITHER IS REPEATEDLY EXTORTING YOUR USERS YOU FUCK!

The iPad app we’ve been working on is currently using a very useful plugin that can only be found in the Appcelerator ecosystem. I shall be ripping that out and finding some other solution to the problem. There are plenty of competitors in this space. I think it likely that none of them consider extortion an unpleasant but acceptable consequence of having salespeople.

Disclaimer:

This is an opinion piece. The logical conclusions are ones I have come to from reading the public comments by their CEO. It is entirely possible that I am 100% wrong.

But, if it were my company (and I’ve had a few small ones), everyone who was caught attempting to extort money from my customers would be handed a box and fired on the spot, along with anyone else who was found to be aware of the activity. If it turned out to be a persistent problem I would fire whoever had been hiring these broken excuses for humanity. I would call everyone together after each incident and make it clear that this type of behavior was 100% unacceptable. I would tell them exactly why person X had been fired, and I would make sure that nothing like that ever happened again.

I would call up the user who had been extorted and personally apologize, on the phone (not via a forum), let them know the salesperson had been fired and give them an free unlimited lifetime subscription to whatever the most valuable plan on offer was. Morals are not trainable. Simply saying you’re sorry, but noting that this stuff doesn’t happen very often is so fucking wrong it isn’t funny.

Do not work with this company. Please.

You’re better than that. 99.99999% of humanity is better than that, and if you’ve got clients you definitely don’t want to risk your reputation with them by working with a company this morally bankrupt. If you’re a one person operation you don’t want to end up having to rewrite your entire app, or hire lawyers when they start demanding payment for their free service, or additional payment for one of their paid ones.

Update:

It should be noted that my quotes were taken from the CEOs comments to his “accepted answer”. You may need to click to expand the comments to see them.

Cheshire [Definition]

Thu, 20 Sep 2012 00:00:00 +0000

Cheshire: the collective noun for sidecar motorcycles (alternately known as “hacks”) owing to the extraordinarily high probability of generating smiles in the people they pass relative to all other vehicles.

Usage:

“Upon encountering a cheshire of sidecars one should strongly consider playing the lottery.” or “Wow! There goes a cheshire of hacks.”

Blog post dates: Precision, or freshness. What's important?

Fri, 24 Aug 2012 00:00:00 +0000

Not too long ago I sent out a question. I asked people when, and why, dates were important to them on blog posts. The responses were revealing, both for what they did, and did not contain.

There are some situations where having a date on your blog posts is obviously needed. If you write about anything techy you absolutely need them. I come across tons of sites with perfectly good code examples, that have been obsolete for years. Ditto for how-to’s related to software and operating systems. The other place where dates are critical is anything related to news or politics.

Basically, if you’ve written something that will be used as research material later on, you need a date. Everyone seems to agree on that. But, what about pieces where the passage of time really doesn’t have much of an effect. For example, I wrote a post about a paper-based task management system. Read it today, read it two years from today… it doesn’t impact the usefulness or relevancy of the content at all. And that was the basis of my questioning. If you had a blog filled with posts like that, would there be any real value in including dates on the post?

The responses were overwhelmingly “YES”, but not for the reasons I’d expected.

Freshness and Precision

While they used different words, everyone was in agreement that an indication of freshness was very important to them. Sometimes, it was just to help them know if the blog had been abandoned or not. More often, it was simply to know if the information in the posts was still relevant or not.

What was interesting, was that when pressed for details, almost everyone claimed that a simple freshness indicator (e.g. “three months ago”) wasn’t sufficient. They claimed that they needed to-the-day precision. They claimed that having this level of precision allowed them to compare it to what was happening in their lives at the time; they could look compare the date to their calendar, and see what they were doing then.

These claims seemed… suspect to me. They felt like the type of answers people give when they’re trying to explain something they’ve accepted as true, or necessary, but have never actually thought about. Like, the idea that going out in the cold will lead to catching a cold.* So, I pressed for details. I wanted someone to give me a real world situation when they would look at a date on a blog post and actually do what they claimed. When would they ever compare the date of one to what was going on in their lives at that time, or to what was going on in the world at large at that point. The response, was a resounding silence.

Conclusions

As far as I can tell, if you exclude the types of posts where dates are obviously required (news, politics, content that will become obsolete) no-one actually needs dates with any real specificity, but because everyone believes they need them, their absence makes them uncomfortable, or at the very least, slightly annoyed.

I believe that relative dates are a much closer match to what people need, and much easier to actually use. “Three months ago” translates quickly to “recent, but not too recent”, whereas 5/24/12 requires you to figure out what month 5 is (“let’s see that’s…May”), compare the day of that month (24) to the day of the current month (“Are they the same? Is that one earlier in the month than this one? Does that make it more time or less, and is that enough to bother worrying about?”) before you can actually leverage the information in a meaningful way. But, what we need, and what makes sense logically, isn’t always what we want.

I believe that Kirk’s proposal of “mid-June 2011” is probably the best compromise between usability and need. It’s easier for a human to parse than 6/15/11. It feels much more useful than “over a year ago” or “15 months ago”, even though once you get that far from a dates post your true need for even to-the-month specificity is doubtful.

With that said, the more recent something is, the more precision seems to matter to people. So, you could probably improve on Kirk’s suggestion by a building a system where dates are written with to-the-day specificity for one month, and then switching to “early May 2012” style dates after that.

Closing Thoughts

When pondering dates in blogging, context is everything, and many, if not most, blogs have posts from multiple contexts. Hardly anyone writes a blog where the value of each post is unaffected by time. With that in mind, a blog’s posts should be dated using a method that supplies the maximum level of precision required. If you write a blog of fictional stories, but occasionally comment on news that affects writers you need to-the-day precision, either that, or use a different level of precision on every post, but really, no-one wants to go through that much trouble.

* As it so happens, it’s probable that being exposed to the cold for a while will increase your odds of catching one. Some scientists did an experiment where they had some college students stand in buckets of cold water for a while, and compared which of them got colds soon afterwards. The kids who stood in the cold water got more colds than the kids who didn’t. I just wish I could find the research again…

An offer for Web Geeks

Fri, 17 Aug 2012 00:00:00 +0000

I’d like to make a simple offer to the web geeks out there:

One hour of one person’s skills, to make the web a little bit more awesome, and raise $75 for your favorite environmental or medical charity.

Information Architects (the people behind iAWriter) have come up with a really spectacular JavaScript / CSS widget. When you load one of their long articles (like this one) you’ll see a widget in the top right corner that says “Older | Newer” and links you to the previous or next article. No big deal. What’s cool, is that as you gradually scroll through the article the widget disappears, then returns, hovering beside your scroll bubble (wherever that may be in its track); its message now telling you how many minutes it’ll take you to finish the article, at an average reading speed. When you get to the bottom it reverts back to the “Older | Newer” state.

This is something that I’d love to see flourish.

The CSS and JavaScript that powers it isn’t particularly complicated, but I don’t have time at the moment to break it out into a reusable library the way I did with Kudos. So, here’s my offer. For the first person to create a public domain or MIT licensed repository on Github that makes it trivial to add similar functionality to any blog, I’ll donate $75 to the environmental or medical charity of their choice.

I’m thinking a repo with one JavaScript file, one CSS file, an example HTML file, and a README. Simple. Less than an hour’s work for a good front-end geek.

Please note: IA’s stuff is copywritten so, while you can take inspiration for them, you can’t just extract (steal) their code. If you did, the MIT License wouldn’t be valid.

I love the internet

Thu, 09 Aug 2012 00:00:00 +0000

Something kind-of amazing just happened.

Background:

Unglue.it is a really cool site, that I’d never heard of until Amazon decided to stop processing payments for them. Think Kickstarter for freeing out-of print books. They get people to create a wishlist of books they’d like to see released as Creative Commons licensed DRM-free ebooks. They then talk to the authors and publishers of the books people want to find out how much money it would take to “unglue” them. Then they crowdsource that amount.

Cool as that is, it’s not the amazing bit. The amazing bit is what happened next.

The Amazing:

Having read of their plight, and pondered their coolness, I started thinking about alternatives. Dwolla is a similarly cool service that aims to replace PayPal and Credit Cards with something that doesn’t screw everyone involved. They’ve already started to change the way banks do business with each other, and I’ve got really high hopes for them. At the moment they don’t do the kind of delayed payments that crowdfunding sites need, but there’s a lot of money to be made by payment processors who can help crowdfunding sites manage their pledges, so I figured that Dwolla had probably been thinking about this.

How amazing would it be if projects didn’t have to give up 5% of their crowdfunded revenue to a payment processor? Dwolla only charges $0.25 per transaction, and only on ones over $10. I really wish I could chose to pay with Dwolla on the projects I help out on Kickstarter. And, while Unglue.it is still fairly small, it’d be great press. “Dwolla enters the crowfunding scene by helping to free out-of-print books.” Sounds good to me.

So I sent a little tweet pondering the connection…

masukomi: I’m wondering if @dwolla wouldn’t be able to help @unglueit out with their current problems with Amazon payments. http://blog.unglue.it/2012/08/09/ope…

And that’s where the amazing began. Ben Milne (bpmilne) is the founder of Dwolla, and while I didn’t directly message him, he’s (unsurprisingly) watching the @dwolla stream.

bpmilne: @masukomi @dwolla @unglueit sure - drop us a line.

unglueit: @bpmilne Emailed you via contact form on your web site.

unglueit: @bpmilne Will do. @masukomi @dwolla

bpmilne: @unglueit @masukomi <> @ajt

ajt: @bpmilne @unglueit @masukomi Hey- email me at [censored] and/or API@dwolla.com happy to help! :)

bpmilne: @ajt @unglueit @masukomi connected- i love the internet.

I couldn’t agree more.

I hope it works out for them. I’d love to see Unglue.it succeed, and I’d love to see more places start letting me use Dwolla to pay them.

Turning Down Apple

Thu, 09 Aug 2012 00:00:00 +0000

I just turned down an interview with Apple.

There are a few companies who, when they call with a job offer you’ll respond with “fuck yes”. Apple is on that list for me. And yet…

A recruiter called me the other day. Apple needs someone and my particular skillset and background. It seemed to be a pretty good match, and she’d been looking for a while. An internal tool building kind of job, in a language I enjoy, for a company I admire? Fuck yes. Would you be willing to move? “Fuck yes.”

Examining the actual job posting and pondering some of the recruiter’s comments made me wonder if the skillset they were asking for was actually the what they really wanted, but it was still close enough to be worth trying for. It’s Apple after all.

But then we did a little research. For an additional $600 per month we could get a one bedroom apartment in a complex in some nearby burbville*, versus our 2 bedroom house abutting a park in Cambridge. Yeah, I’d have a bit more cash at the end of each month, but I’d still be stuck in a cube, in a soul-sucking burbville, in an apartment complex. Even if we could find a place by the nearby state parks we’d still have to deal with burbs, sprawl, and strip malls every time we ventured outside for anything.

Alternately we could move to some beautiful portion of Vermont and I could telecommute to my current job. The drop in living expenses would be bring me about as much additional take-home as a salary bump from Apple. Yeah, the project’s not as interesting, and the company’s not as cool as Apple (few are), but being able to work in a home office I created? Being able to causally fuck-off for 20 minutes without stressing about pretending to work, as every coder I know has to do, because it’s not humanly possibly (excluding severe autistics) to focus on a single task all day long?

If you’ve got the self-discipline to work from home and still get your tasks done on schedule, the bump in your quality of life is so dramatic that it easily cancels out many of the workplace frustrations, and totally trumps extra cash. To me the idea of being able to look out my window and see trees, to take a break to play with the dogs or chat with Dachary… That’s worth so much.

So, I thanked her for her interest, and turned down what’s likely to be my only chance to work at Apple… unless of course, they find a position I could telecommute for. Or, if they set up shop in the middle of the woods. ;)

A good life is better than a good paycheck any day of the week. Even if that paycheck’s from a great company.

* I consider track housing to be the urban planning equivalent of the office cubicle. The lower half of California is rife with these things, and the more standard burbs aren’t much better if you ask me, but just to be clear: I do currently live in Cambridge MA, which is pretty far from a view of beautiful trees, but I do love this city, and if I’m not in the woods, it’s one of the few places I’d be happy living. That being said, we have been discussing finding a place in VT with trees, and a nice net connection. ;)

Major MObtvse Update

Wed, 08 Aug 2012 00:00:00 +0000

I’ve just merged the experimental branch of MObtvse into master. This represents a huge update and in addition to the feature list below there’s a nice update to the default theme, great new editor, improved Kudos integration on the admin screen, and a number of more subtle improvements. I’m really happy with the progress I’ve been able to make on MObtvse in my free time, and if you’ve been considering it, now is definitely the time to grab it from Github and give it a spin.

It should be noted that while it’s fairly easy to install, and the README attempts to cover all the details, people who’ve never installed a Rails app before, or used the command line, may feel a bit out of their depth.

Sorry non-geeks, we’ve got a little ways to go before installation is totally painless for you, but I’m working on it.

Current Feature List (as of Aug 7, 2012):

Kudos
Live Markdown preview
Drafts
Scheduled posts
Image uploads via S3
Disqus integration
Google Analytics integration
Archives page with Tags and Kudos integration (example here)

Pull requests will be happily accepted. ;)

Task Order Up!

Fri, 06 Jul 2012 00:00:00 +0000

I’ve been a big fan of David Seah’s Productivity Tools for a while now, but when it comes to task management his needs, and mine frequently diverge. As a freelancer he needs to track hours in a way that is totally irrelevant to me. He’s got no-one to answer to but his clients, whereas I’ve got a boss and coworkers who are asking for details on current and past tasks in ways that clients rarely do.

I’d seen his Task Order Up! sheets a while ago, but they just didn’t work for me. Upon revisiting his site the other week I had a little brainstorm. They could be just about perfect for me with a few tweaks. Throw in a couple office supplies and I’ve got a useful task management and archive system.

Task Order Up (re-imagined) - PDF

Requirements

must be able to show me exactly what I’m supposed to be working on now
must help me easily recap what I did in the previous week for my status report.
must help me out when the boss comes by and asks how I resolved that issue last week that I’ve entirely forgotten the details of.
must help me know who I need to talk to about a specific task

The System

I’ll cover the changes I made to David’s sheets in a second, but first I’d like to cover the system that transforms this from a glorified notepad into an extremely functional tool.

Now, David’s original idea was to use these similarly to how a waitress would take your order, put it on a little pad, go to the back and stick that sheet on a restaurant order check rail. It’s a good idea, but having a whole bunch of visible tasks is too distracting for me. I want my To Do list to show me exactly what I should be working on right now and keep me from pondering about all the other stuff. Also, I needed some system to be able to look back into the near past to answer questions about what I had been working on. Chefs don’t care what they made 30 minutes ago, they just care about what they need to cook now, and what’s coming down the line.

Four Stacks

In this system there are 4 stacks of Task Order Up! sheets:

A stack of blanks (silver binder clip)
A stack of tasks I’m currently assigned / working on (red binder clip)
A stack of tasks that I finished this week (yellow binder clip)
A stack of tasks that I finished last week (blue binder clip)

For the most part I don’t care about tasks that were completed at some point before last week, but for the odd occasion when someone does ask me about older tasks I take all the old ones and throw them into the “archive” which is actually just a larger black binder clip that lives on the back of the desk and holds the ever increasing stack. I could just as easily shove them in a drawer, but things in drawers may as well not exist to my brain.

The “current” stack (red binder clip) is prioritized, so the most pressing task is on the top, the next most pressing just below it, and so on. The completed stacks are prioritized by completion date (reverse chronological, like a blog) simply by virtue of the fact that new ones get added to the top.

Binder Clips

The color coded clips aren’t necessary, but I think they help. The clips keep the sheets together, should they accidentally get knocked, and the colors help me know which stack is which if they get moved around. This makes cleaning your desk much easier. Our office manager managed to find wee colored ones a little over a centimeter wide. If your office only has the larger binder clips you might want to go with colored paperclips instead. Most people don’t work on enough tasks in a week to exceed the holding capacity of a paperclip.

Flow

Tasks start on the left (with the stack of blanks) and proceed to the right as they pass through the stages (current, completed this week, completed last week). The archived ones from earlier weeks go somewhere out of the way.

Usage

New Task

Grab a blank.
Fill it out.
Put in in the current (red binder clip) stack.

Completing a task

Fill in the “Done” check-mark.
Move it to the top of the “completed this week” stack (yellow binder clip).
Start working on whatever’s on top of the “current” stack (red binder clip).

New Week

At the start of a new week your completed stacks are now a week too old and need to be shifted down the line.

Grab all the tasks that were completed two weeks ago (blue binder clip) and move them to the archive.
Grab all the tasks completed last week (yellow binder clip) and move them to the stack for tasks completed last week (the now empty blue binder clip).
Your “completed this week” (yellow) binder clip will just sit there waiting for you until you finish something. So get cracking!

The Task Sheets

Now David’s Task Order Up! sheet’s are pretty great, and if you need to keep track of billable hours his are definitely a better choice. “The System” will work with either, but my variant doesn’t have any hour tracking.

Other Changes

People

Across the bottom of the sheet is a “People” section, with a bunch of icons. If you’re a freelancer you could use this to indicate what client the job was for. If you’re putting these sheets on a shared board to keep track of what’s being worked on you could indicate the person the task has been assigned to. In my case I use it to note which of my coworkers have knowledge of that section of our codebase… who I should go to when I have questions.

The icons are intentionally simplistic so that, in your bored moments (translation: meetings), you can doodle little hats, faces, glasses, moustaches, and anything else on them.

Notes & Resolution

I’ve replaced the “Steps that need to be accomplished” with a generic lined field for “Notes” and “Resolution”. Sometimes I need to write down steps, but more frequently I need to write down notes, like what user encountered a bug, and how to replicate it. The “Resolution” lines are where I note how the issue was addressed, because people keep asking me. However, the “Resolution” text is intentionally light enough that you could write right over it and it wouldn’t hamper readability.

Job Code

I’ve brought the Job Code / Reference Number block up because our team, like many others, uses a web-based ticket system, and I need to be able to easily associate the task with its identifier in the system, or vice-versa if someone asks me about ticket #4238.

Done Check

I’ve added a little checkmark to the right of the Due Date field, so that when you finish your task you can fill in the check and enjoy that satisfaction of a job well done… and give yourself a nice visual indicator of which tasks have been finished.

Features from David

When’s it due?

David’s provided a couple useful ways for tracking when a task is due. Use whichever one works best for you.

The Due Date field is pretty much what you’d expect; a place to put the date the task is due.
The Week Num: If this is a multi-week project you can write the week number it’s due in, and then circle the….
Days of the Week: Circle the day of the week its due on, and AM or PM if it matters.

Due Date’s aren’t generally an issue for me. It’s ASAP for almost everything, but when there is a due date it’s generally in the same week and I’ll just circle the day of the week rather than trying to figure out what that date is.

Brainpower

David did all the heavy lifting here. My version wouldn’t be possible without his creative shoulders to stand on. Go to his site, check out his stuff.

About

Thu, 05 Jul 2012 00:00:00 +0000

I am an adventurer, a geek, an entrepreneur, an esperantist, and a writer. I’m passionate about about exploring the world and helping people to get out of their cubes and actually live their lives.

You can find out more, including all the latest contact info, at masukomi.org.

Want Some Kudos?

Sun, 13 May 2012 00:00:00 +0000

I think Dustin Kurtis’ idea of “Kudos” is spectacular. A simple tool for people viewing your post to say “I really appreciated this.” You can see it in action in the upper-right corner of every blog post in the Svbtle blogging network.

I really want to bring it to MObtvse, but first I had to figure out how it worked. So, I’ve put together an example implementation of Svbtle-style Kudos that can be incorporated into your blogging software with a few easy changes.

I want to see Kudos everywhere. I want readers like me to have a way to tell great bloggers like you when you’ve written something great. So, go grab the code and add it to your blog system.

UPDATE:

MObtvse now has Kudo support built in. This blog has a different UI implementation from Svbtle’s (and the example repo), but it’s still backed by MObtvse’s new Kudo functionality.

P.S. If you’re looking to add Kudos to your WordPress install checkout the wordpress-svbtle theme from scavone. It’s got them built in, and is where I went to figure out how this works.

P.P.S If you’ve got good CSS chops I’d love to see some improvements on the texts that’s displayed during the animation in the example implementation of Svbtle-style Kudos. Send me a pull request and I’ll happily incorporate it.

Introducing MObtvse

Tue, 01 May 2012 00:00:00 +0000

Today, I would like to introduce you to MObtvse. It’s a fork of Nate Wienert’s Obtvse, a Markdown based blogging system written with Ruby on Rails. Obtvse is itself, a reverse engineering of the Svbtle blogging platform / network.

The notable differences between MObtvse and Obtvse are that:

MObvtse uses MongoDB via MongoID
MObtvse allows posts to be tagged. Readers can click the tags to see all other posts with the same tag, and Administrators can use the tag cloud to help find specific, or related, posts.
MObtvse uses Haml (partially implemented)
Responsive CSS layout via the Foundation framework.
MObtvse has big plans for the future.

MObtvse doesn’t currently generate static pages, but support for statically generated pages is a top priority. The faster serving helps SEO and allows a single server to handle far greater numbers of readers.

There are a number of planned features like Disqus integration for comments, Mixpanel for stats (it already supports Google Analytics), easy image uploading, and much more.

Reasoning

Why another blogging system?

I know. I know. But, the reasons are pretty simple:

I love blogging with Markdown. It has totally changed my perception of blogging.
Wordpress is a bloated behemoth that can’t withstand serious load without a really good hosting package, and all the Markdown plugins for it suck in one way or another.
Blogging with command line tools like Jekyll and Octopress have serious limitations, frustrations, and complications.

Why a new fork?

I created a totally separate project, instead of working to extend the common Obtvse codebase, because there are a number of changes that I have made, and intend to make, that are far beyond what Nate appears interested in doing with Obtvse, which is fine. I’ll contribute back as I can, but MObtvse is quickly moving to a point where most of the new code simply won’t be compatible with Obtvse’s.

I started with Obtvse because writing something from scratch would have taken too much of my limited time, and Rails’ ecosystem allows me to rapidly introduce many of the features I want without having to code them all from scratch.

Why MongoDB?

Simple, by switching to MongoDB users can now throw an instance of MObtvse up on Heroku and use one of the free MongoDB hosting plans to store their data. These plans generally cap their storage but there are very few blogs out there that would even approach the limits they impose.

Why not stick with Octopress?

I’ve really enjoyed the switch to blogging with Markdown, but Octopress just hasn’t been cutting it for me. I spend almost all my working days staring at terminals, so it’s not that I mind getting down and dirty with the command line, but from the perspective of wanting to write, the process kind-of-sucks:

bundle exec rake new_post[“some title”]
select and copy the new file path it generates
open said file with a text editor (I’ve been using Byword lately).
skip the chance to preview what it would look like in the final version because that would require regenerating the entire site which takes forever.
add it to git.
push that to the server, which will then background the generation of the entire site for me via a git post-receive hook. Most people have to sit around twiddling their thumbs waiting for it to finish generating and then upload via FTP / SCP / Rsync / carrier pigeon.
wait a few minutes for the entire site to be regenerated on the server (even when you just upload one post).
View the post and hope you don’t spot any typos.

And if you want to write a quick blog post from work? No good way to do it without downloading your entire blogging system to your work computer or install and configure JekyllMail. Even then you can’t make an update. Actually… JekyllMail makes blogging with Octopress way easier. Just send an email, with attached photos and placeholder image tags and you’re all good.*

The YAML data structure embedded in the top of my Markdown posts drives me nuts (Octopress inherited this from Jekyll) even though Marked will auto-filter that out on preview for me. This is just wrong. Markdown’s supposed to be about simplicity and ease of writing. Embedding an incomptable, and manually managed raw data structure at the top of each post instead of a centralized metadata solution that would allow the app to make intelligent decisions about what needs to be regenerated and what doesn’t… UGH!

The problem, of course, is that right now Octopress is one of, if not the most feature-packed Markdown specific blogging platforms there is.

How about looks?

MObtvse will always strive to keep its interface clean, simple, and easy to use. The admin section is fairly close to that of Obtvse with the addition of tag support, responsive css, and modifications to better support mobile devices.

The Reading page currently (May 2012) takes many of its cues from weblog.masukomi.org but I expect that to change in the near future.

The Admin Page

Creating or Editing a Post

Reading a post

Like what you see?

Go to MObtvse.com for more details, or head directly over to MObtvse’s Github repo and grab (or fork) a copy. MObtvse is all about integrating kick-ass new features, so your pull-requests will be warmly met.

* Footnote: I’m mostly done with a complete refactoring of JekyllMail which fixes some bugs and makes it way more extensible. I just need to test it before releasing it into the wild.

Announcing ListfulThinking

Tue, 17 Apr 2012 00:00:00 +0000

Friends, Romans, Countrymen! Lend me your ears.

Actually, that should read, “Friends, Romans, and Countrymen who own iPads or Macs!”

Eight years ago I stumbled across a brilliant way of creating a self-organizing ToDo list. My initial proof-of-concept app was really ugly, but worked wonderfully. A few years later, I translated the method into a paper version, which looked great, and worked pretty well. Sadly, lines on paper aren’t very good about rearranging themselves on command. So this year Alexander ( our wonderful Russian programmer ) and I have been working to create a beautiful version of this app with all the features I wished the previous incarnations had.

If you find yourself staring at your tasks list wondering “What should I work on next?!” or simply feel overloaded by the size of the list, you need to go here and sign onto our announcement list. If you find little tasks slipping through the cracks, then go here and sign onto our announcement list. We’ll drop you a note when we’re ready for beta testers, and we’ll drop you a note when it hits the App Stores.

Want to help make ListfulThinking the best ToDo app for you? Take one minute and reply to the signup confirmation e-mail. Or poke @ListfulSupport on Twitter. Tell us what frustrates you about your current task management system. Are you losing tasks? Or tell us the most awesome thing about it that you don’t think anyone can beat. I don’t care if you’re using OmniFocus, pen and paper, or carefully timed carrier pigeons. We want to hear from you, because every insight helps.

So, if you’re wishing your ToDo list would organize itself, please sign onto our announcement list and be one of the first to give it a try.

P.S. ListfulThinking’s excellent logo was designed by Doug Fuller If you need a logo designed, and are willing to pay for quality, I’d highly recommend you drop him a line.

Using Git Bisect to Crush Your Enemies

Tue, 10 Apr 2012 00:00:00 +0000

Using Git Bisect

…to crush your enemies and/or bugs

Or, how to save countless hours and find out where things broke

Git bisect is the most awesome, and most poorly publicized feature of git. It allows git to walk through your branch and quickly find out which commit broke things.

The usage is simple. You point git to a bad commit ( usually the most recent one ) and you point it to a good commit (the most recent one you know of when things were working). So, if, for example, things were working on Tuesday morning, you bring up git log and scroll until you find one from Tuesday morning or maybe late Monday and copy its hash.

$ git bisect start
$ git bisect bad
	# that tells it that the current commit is bad
	# but you could say git bisect bad 48476f7b15022526393e6c4f44f610f552736fdc
$ git bisect good 71f45f2a0302b5fb2331c268ee2bfb3cfde452ab
	# that's the hash of some commit you know to have been good

git will then find the commit mid-way through and wait for you to tell it if it’s good or bad (git bisect good or git bisect bad). If it’s bad it knows the offending commit was earlier. If it’s good it knows the offending commit was later. It continues on in that vein, bisecting the commits with each step until it eventually says something like 54cb86bd35c226dc0df83dc2e2d4c8702fcf2c04 is the first bad commit

When you’re done you run the following to reset your branch to its original state

$ git bisect reset

Full Automation

But it’s even better than that. You can fully automate git bisect. Just kick it off and have it test each branch. All you have to do is write a script that can be executed from the shell and exits with 0 if the commit is good, and a number from 1-124 if it is bad.

You only have to do one thing differently. Once you’ve told it a good and a bad commit it will bisect the commits as usual and give you a system prompt and wait for you to tell it if it is a good or bad commit, but instead of telling it if it’s good or bad, you tell it what it needs to run to test it.

$ git bisect run my_test_script.sh

For example: I’m working on a rails project at the moment and just used this simple rake task which would blow up if the .fixtures method wasn’t loaded correctly:

# lib/tasks/location_test.rake
namespace :location_test do

	desc "tests location.fixtures classload issue"
	task :run => :environment do
		begin 
				Location.first.fixtures
				$stderr.puts "it worked"
		rescue Exception=>e
				$stderr.puts "it died: #{e}"
				exit(1)
		end
		exit(0)
	end
end

So, my run looked like this:

$ git bisect start 
$ git bisect good bebcc378d16d8fe74736c763c144753b2a382933
$ git bisect bad
$ git bisect run bundle exec rake location_test:run

And git bisect proceeded about its merry way until it found the offending commit. Then I ran git bisect reset and went about fixing the bug.

Pro-Tip

The Git Book adds this great note:

Note that the version which git-bisect checks out for you at each point is just a suggestion, and you’re free to try a different version if you think it would be a good idea. For example, occasionally you may land on a commit that broke something unrelated; run

$ git bisect visualize

which will run gitk and label the commit it chose with a marker that says “bisect”. Choose a safe-looking commit nearby, note its commit id, and check it out with:

$ git reset --hard fb47ddb2db...

then test, run “bisect good” or “bisect bad” as appropriate, and continue.

Obviously this won’t work if you’re running a fully automated bisect, and it points to the one gotcha of git bisect. If there are multiple bugs that inhibit your ability to test it ( either manually or via a more automated means) it can leave you with no obvious candidate. Most of the time, this isn’t a problem, especially when you have done your best to chose the most recent “good” commit that you are confident in.

Tourists and Adventurers

Wed, 04 Apr 2012 00:00:00 +0000

This post was written as response to The Travel Chica’s post about the flooding of the Atacama

The Travel Chica just discovered that “the driest place on the planet is flooding”.

The two most beautiful places on my itinerary for Chile have experienced environmental disasters just before my arrival. First, there was the fire in Torres del Paine. And now the driest place on the planet is flooding.

…
I just spent US$100 on a bus ticket to get here, dealt with the discomfort of an overnight bus ride, and left a city I loved and wanted to explore more. And I am not going to be able to take pictures of this landscape photographer’s dream destination.

…
People are being evacuated.
The military is handing out mattresses and blankets on the square.

…
The only thing for me to do is book a bus ticket out of here. …And wait until I can escape to northern Argentina…

So, let’s recap: People’s homes are flooded. Entire villages are being evacuated, and she’s complaining about a $100 bus ticket and the “discomfort of an overnight bus ride”.

She’s traveled to a “photographer’s dream destination” and when she finds out that she will not be able to take the same pictures everyone else has been taking for years, but instead has been presented with the opportunity to photograph something that has never happened within our lifetime “the only thing for [her] to do is book a ticket out…” Just imagine how extraordinary (literally) it would be to go to the same places of all those beautiful pictures she admired, and find beauty in a landscape transformed by an element that is almost never present.

This, is a spectacular example of the differences between a typical tourist and an adventurer. A tourist books itineraries, expects comfort everywhere despite the being in a land rife with poverty, and gets upset when things don’t go according to plan.

An adventurer says “Holy shit! How fortunate am I to be experiencing something that has never happened in my lifetime, to be in a place where the money I bring to the community when paying for food, guides, and shelter can have a real impact in this time of crisis, to be able to photograph things no-one else will have the opportunity to, to tell stories no-one else can tell, and to have the ability to hop the next bus out whenever I want.”

The adventurer thrives in the unexpected moments of life. The tourist gets annoyed.

I will never be a tourist.

I Saw a Man Walking Down the Street...

Mon, 19 Mar 2012 00:00:00 +0000

… and it reminded me of everything I hope for.

The man in question had serious physical disabilities. His left foot pointed almost directly inward. His legs didn’t seem to be oriented in the way that yours or mine are. I suspect his spine didn’t curve in a typical direction either.

He walked forcefully, arms flailing out to the sides. His feet stamped their way into the concrete. With every step you feared he might topple forwards, but he didn’t. My first reaction was to look away “don’t stare ate the disabled person and make them uncomfortable”. But, I forced myself to look back, as I always do. It’s unnatural to not stare at a sight like that. I think it’s doing them a great injustice to pretend they aren’t who, and what, they are. So I looked…

He wore a nicely trimmed beard, light blue dress shirt, navy blue pants, black socks, and brown leather dress shoes, and a face that demanded my respect, because he wasn’t “flailing”. He was walking, and he wasn’t giving up. He could have taken the easy route and used a wheelchair, but he didn’t. He got up, got dressed, and walked to work, despite all the looks he knew he’d get, despite the fact that he was burning more calories than a jogger on his way in to work.

I want to be that bad-ass.

Great Apps for Your New iPad

Fri, 16 Mar 2012 00:00:00 +0000

A quick listing of some of my favorite iPad apps, which I hope new iPad owners may find useful.

Reading

Early Edition 2

A newspaper style feed reader. This is the best app of this genre on any platform. It does crash from time to time, but not enough to be particularly annoying. My recommendation is to not put your full list of feeds into it. Instead, put a selected subset of them that would work well if you were reading them in a physical newspaper.

Warning: “Early Edition 2” was released separately from “Early Edition”. Be sure to buy v2. It’s a signficant upgrade in features from the original and there is no free upgrade path to owners of the original.

Instapaper

Instapaper is a great offline reading app. It’s main competitors are Read it Later and Readability. I recommend Instapaper though because it’s very well thought out, and by buying the app you’re supporting a developer who is dedicated to making this the best reading app out there.

Flipboard

Flipboard is a great way to see interesting things you Twitter and Facebook contacts have uploaded or linked to. It’s free, well made, and a lot of fun.

Tweed

Tweed watches your Twitter feed and pulls out all the links from the people you are following. Unlike clipboard it doesn’t bother with tweets that don’t include any links. It’s good enough to warrant mentioning here, but I find I don’t use it very much. Usually, if I’m interested in something like that I’ll just open Flipboard.n

Tweetbot

One of the best Twitter clients on iPhone or iPad.

Twittelator

Honestly, I think Twittelator is the most beautiful Twitter client available on the iPad, but it lacks Tweetbot’s ability to easily see an entire conversation thread. Right now I’m using Tweetbot, but if they add that I’ll switch back.

BeejiveIM

I’m not a big fan of using IM on the iPad, but if you’ve got to do it, this is the best app for the job.

Skype

It’s not that I love Skype so much that I think you ought to run out and get it for your iPad, but if you’re traveling and want to keep in touch with friends and family, Skype’s iPad client is a great option, especially on iPads with front-facing cameras (not the 1st generation)

Productivity

Soulver

“Soulver helps you work things out. It’s quicker to use than a spreadsheet, and smarter and clearer than a traditional calculator.”

Imagine you took a typical calculator app and dipped it in awesome-sauce. That’s Soulver.

OmniFocus for iPad

I hate to recommend someone-else’s todo app when I’m in the middle of developing my own, but there is no denying that OmniFocus for iPad is the best GTD app available right now.

MindNode

Most people seem to talk about iThoughtsHD when discussing mind-mapping software for the iPad, but I really dislike its graphics. MindNode looks good and is very easy to use. Dachary and I have gotten a lot of value out of this for helping to plan our adventures.

iMockups

A great tool for quickly mocking up web pages, iOS apps, and just about anything else. I have a copy of Balsamiq Mockups on my desktop but I’ll choose iMockups over it almost every time. Manipulating your mock-ups with a finger just feels, right, and has significant advantages when creating an iOS app.

Business Model Toolbox

I debated whether or not I should include this one. For most people pondering their business, or starting a business, I suggest just getting the book and skipping the app. For serial entrepreneurs, like me, who are constantly pondering different business models for potential new businesses it’s a great way to work out the rough numbers and customer or supplier channels for a business. The problem is that it has some significant limitations. For example, when mocking up an iOS app you can tell it that apple with take x dollars per sale, but you can’t say that it will take x percent of each sale. This means that every time you want to explore the consequences of changing your app price you have to go back and manually change the amount that apple will be taking. There are lots of little financial things like this that keep leaving me less than thrilled with this app. What’s worse, is that while it doesn’t have any bugs (that I’ve discovered) I can’t remember ever having gotten an update for the app. They’re just not working on it. Buying the book and just working out the numbers on paper may be a better option than buying this app. Or, better yet, figure out the channels, with this, or the lessons in the book, and then work up the numbers in Soulver.

Writing

I think the are two things that are required to do any serious writing on the iPad:

An external keyboard. The Apple wireless bluetooth keyboard is wonderfully thin and adds almost no space when you lay it over your iPad.
A willingness to use Markdown

Markdown allows you to use trivially simple markup, like sticking an asterisk on either side of a word to make it italic. With it you can quickly and easily generate well formatted documents on your iPad without ever having to use iOSs text selection tools to bold, italicize, create headings, bullet lists or any of the other common formattings.

Now, markdown can be created in any text editor, but an app that’s specifically designed to handle Markdown can preview the formatted text, and turn it into a good looking email or PDF.

The best app of the bunch is Writing Kit. ScreenCastsOnline has made an in-depth screencast on it, which you can find on WritingKit’s web site.

With that said, there are a bunch of really good iPad Markdown editors. If Writing Kit isn’t your style check out Byword and iAWriter, both of which sync very well with their OS X counterparts.

Blogging

Posts

If you want a more standard WYSIWIG interface for your blogging Posts is a beautiful app that works great. It’s the best looking blogging app I’ve seen on the iPad, and it works with Blogger and Wordpress

Poster

If you’ve got a WordPress blog and want to post with Markdown check out Poster. I haven’t used this personally but it’s been getting great reviews and it’s one of the only ones that supports blogging with markdown without any special plugins on your blog.

Fun

Spice Bandits

A great, and challenging, Tower Defense game. It offers in-app purchases to help jump-start things, but a real Spice Bandit doesn’t need in-app purchases.

Carcasonne

A wonderful port of the board game of the same name. If you like the board game you’ll like the iPad version. Great sound, great voicework on the tutorial. Even includes a “solitary” mode.

Tower Madness

Another fun Tower Defense game. The graphics aren’t fancy, but it’s a lot of fun, and it has a split-screen two player mode which is great for killing time when out with a friend.

Letterpress

Available for iPhone and iPad this is a great word game that’ll tax your vocabulary, and have lots of fun with a friend.

Utilities.

Dropbox

Duh.

1Password

Because 1 Password is the best password manager out there and once you start using it you’ll want it on every platform you use.

Art & Design

Letter M Press

Letter M Press allows you to “Experience the Art and Craft of Letterpress”. It does an exception job of recreating an old-fashioned letterpress on your iPad. It’ll take you half an hour to lay-out the simplest type design, and you’ll love every minute of it, or you will if the idea of working with a real letterpress is appealing to you.

iFontMaker

iFontMaker makes it trivial to design your own custom font, and export it for use on your computer. It supports a variety of glyph sets, including Japanese, greek, Cyrillic, and more. The only downside is that the tools provided really only work for designing handwriting style fonts, and there is no way to edit the bezier curves.

Misc

FlickStackr

Probably the best Flickr and 500px client on the iPad. It also offers good offline support.

Know Backbone.js? Want a Little Extra Work?

Sat, 03 Mar 2012 00:00:00 +0000

If you know Backbone.js and are interested in 5, or more, hours of freelance work every week, I want to talk to you.

We’ve got a number of apps in the pipeline and need someone to help code them. The current one needs Backbone.js and PhoneGap (iOS) experience. There will be plenty of front-end work in the upcoming apps as well as Ruby on Rails, or Node.js tasks if you’ve got the skills for those too.

We’re not looking to hire someone for just this project. We’re looking for someone we can keep working with on all our future projects. Five hours is the minimum I can guarantee, but if things are going well there will definitely be weeks with more hours than that.

Interested? Check out our Job Posting on oDesk. Got questions? Need more info? Drop me a line at masukomi@masukomi.org

How to Merge Specific Files From Another Branch in Git

Tue, 28 Feb 2012 00:00:00 +0000

There are many ways to get specific files from another git branch into your current git branch (overwriting the ones in your current branch), but this is the only method I’ve been able to find to merge those files into your branch en-masse. With this method you’ll be able to pull in any file, or files based on the name of the file or containing folder. If you need to merge files in multiple folders on different subdirectories you can simply rerun step two with a pattern that matches each of the different portions of your tree that you wish to merge.

Please note that this was originally an answer on Stack Overflow, but I felt it could do with a reposting since it’s a commonly asked question and there are lots of poor answers out there that don’t really answer it.

So, without further ado, the simple way, to actually merge specific files from two branches, not just replace specific files with ones from another branch:

Step one: Diff the branches

git diff branch_b > my_patch_file.patch

Creates a patch file of the difference between the current branch and branch_b

Step two: Apply the patch on files matching a pattern

git apply -p1 --include=pattern/matching/the/path/to/file/or/folder

useful notes on the options

You can use * as a wildcard in the include pattern.

Slashes don’t need to be escaped.

Also, you could use –exclude instead and apply it to everything except the files matching the pattern, or reverse the patch with -R

The -p1 option is a holdover from the *unix patch command and the fact that the patch file’s contents prepend each file name with a/ or b/ ( or more depending on how the patch file was generated) which you need to strip so that it can figure out the real file to the path to the file the patch needs to be applied to.

Check out the man page for git-apply for more options.

Step three: there is no step three

Obviously you’d want to commit your changes, but who’s to say you don’t have some other related tweaks you want to do before making your commit.

If you found this useful you might be interested in some of the other git posts here.

It's Not What You Think It Is

Tue, 28 Feb 2012 00:00:00 +0000

There’s a petition on Change.org right now urging people to “Tell Ticketmaster: Stop hijacking fans’ rights!”

The short version is that person behind the petition (Nathan Hubbard) is upset that Ticketmaster has begun to tie the purchased ticket to the purchaser of the ticket. Nathan feels that since you bought the ticket you should be able to resell it, and that this is just a “ploy” by Ticketmaster to make more money by handling the resale of the tickets themselves. Ticketmaster claims that this is an anti-fraud tool.

The thing is, I’ve been privy to what goes on behind the scenes when a popular event goes on sale at Ticketmaster. You know, those ones where four bajillion seats get sold out in eleven minutes?

Well, Ticketmaster hates that, because essentally no humans actually managed to purchase a ticket. Instead, professional scalpers launch a rather brutal assault on the Ticketmaster servers, and regardless of how many measures Ticketmaster and their competitors put in place, the bots still manage to get the vast majority of the tickets. So, if you were wondering why you couldn’t get a ticket to that last big show, that’s why. And, if you’re wondering why Ticketmaster’s purchasing process has so many steps it’s because each one is part of a very complicated process that attempts to slow down the bots so that people like you have a chance to buy tickets.

Tying the ticket to the purchaser of the ticket is about the only thing Ticketmaster can do to help ensure that regular people can get tickets to the shows they want to see without having to pay ridiculous fees to scalpers. Ticketmaster honestly wants you to be able to buy your ticket at a reasonable price. It’s not only the right thing, it’s also what their customers (the musicians, sports teams, etc) want. Their customers are just as unhappy about the scalpers buying up all the seats as you are.

Some of you may be thinking I’m talking about the guys standing outside of the stadium with a handful of tickets for sale. I’m not. I’m talking about online companies that compete with each others bots to buy thousands of tickets.

Yes, Ticketmaster will probably make more money by handling the resale of unused tickets too, but so what? The only people hurt by this policy are professional scalpers who make their living by preventing normal people from buying tickets at reasonable prices. If your friend gets sick and you have a spare ticket, but can’t find anyone else to go, wouldn’t you want a company with the resourses of Ticketmaster to help you resell it? Shouldn’t they be paid for that?

In short, you should be really thankful that Ticketmaster is tying the tickets you purchase to you. Because it’s about the only way I can think of that people like you and me will have any hope of actually buying tickets to popular shows. Next time you feel like getting pissed at Ticketmaster remember, it’s almost always the scalpers who are to blame, and the geeks at Ticketmaster are working their butts off to make sure that normal people like you can buy a ticket at the standard ticket price.

Oh, and those extra service fees? Lets just say that it requires an army of servers to fend off the army of scalper bots, that are trying to get the tickets before you. Well, that and the fact that they want to make money. ;)

OS X Apps Worth Checking Out

Wed, 15 Feb 2012 00:00:00 +0000

There are a ton of good OS X apps out there. These are the ones that I really appreciate, and think you ought to check out too.

Please note that this was written on Feb. 2nd 2012, and that software changes at a very rapid pace.

Writing Apps

Scrivener

If you’re serious about writing, or writing anything significant (book, screenplay, thesis, research paper, etc.), there is only one app to consider, and Scrivener is it. Be sure to go through the tutorial though. Its features do a spectacular job of getting out of your way, which means that a lot of great functionality is hiding in plain sight. The tutorial shows you just how incredible this app is. Also, it’ll generate ePub and Kindle formats for you, and it lets you write in Markdown,* if you want.*

Scrivener is $45 and has a free trial.

Markdown Writing Apps

Byword

I’ve tried essentially every Markdown editor available for the Mac, and Byword is hands-down my favorite. I hope to write a post comparing them all, but Byword really is the best in my opinion. Feel free to ping me with questions if you’re considering it or one of the many alternatives.

Byword is $9.99

Marked

Most of the good Markdown editors already have the ability to preview your work. With marked you can preview things while you write them without having to switch back and forth. It’s also great for reading Markdown documentation. Also, it can hide the crazy YAML frontmatter that Jekyll / Octopress shove into the top of your posts.

Marked is $3.99

MultiMarkdown Composer

Brought to you by the man who brought us MultiMarkdown in the first place, this is a really good Markdown editor, with a really useful outline navigator. From a features standpoint it’s probably the best, but it just doesn’t feel as nice as Byword to me.

MultiMarkdown Composer is $9.99

Texts

Texts deserves an honorary mention. It’s still young, and rough around the edges, but it’s a great WYSIWYM text editor that generates Markdown behind the scenes. It only supports a subset of Markdown at the moment, but it shows good promise. I’m really rooting for this app.

Texts is free

Graphics / Images

Pixelmator

Very well made, amazingly capable, and affordable for real humans. Lots of people like Acorn but Pixelmator just feels more professional, polished, and capable to me.

Pixelmator is $29.99

Skitch

If you ever need to annotate screenshots to report bugs, point out items that need to be improved, or anything like that you need Skitch. Lots of apps can do this. Skitch is the only one that makes it both trivially easy and good looking.

Skitch is free

OmniGraffle

If you ever need to make flowcharts you want this app. I’ve tried every noteworthy flowchart app on OS X, Linux, and Windows. Nothing compares to OmniGraffle. It’s also great for mocking-up interfaces, and creating complicated paper forms (yeah, some people still use paper). OmniGroup’s stuff costs a bit more but is worth every penny.

OmniGraffle is $99 and $199 for the Pro version, which does have some nice additional features professional designers might be interested in.

Geekery / Coding

MacVim

True geeks know the power of Vim (and Emacs). True Mac geeks know the power of MacVim. Still don’t know why we love Vim? Read This

MacVim is free

Miscellaneous

nvAlt

Brought to you by the same guy who brought you Marked, nvAlt is a fork of the original NotationVelocity app that just builds upon the awesome. nvAlt is the best tool out there for storing and managing collections of little notes. It also lets you write in Markdown (and grab the generated HTML), which leads a lot of people to use it for keeping and working on draft versions of blog posts.

nvAlt is free

1Password

Nothing beats 1Password for password storage. Get the OS X version, plus a copy for your iOS or Android device and you’ve got all your passwords everywhere. Also lets you securely store credit card numbers and other sensitive information. Combine it with its easy to use browser plugins and nothing else comes close.

The only downside to 1Password is that it ain’t cheap. It’s $49.99 for the mac version plus another $15 for the iPhone + iPad version. Probably the same for the Android version.

Transmission

If you’re on a OS X, and you need a Bittorrent client, this is the one to get.

Transmission is donationware.

Chuck

A simple, excellent, app launcher, that’ll stick a moustache in your menu bar. What more could you want. Type a few keystrokes and voilla, the app you need has just been launched. No more reaching for the mouse.

Chuck is free.

Capo

Capo deserves every award it has won. “Capo is a revolutionary tool that helps you learn the music in your iTunes library. By slowing your music, and presenting a detailed spectrogram, Capo lets you hear and see your music like never before. " More importantly to me, you can just drag over the darker bits in the spectrogram and it’ll tell you what notes are being played, and help you figure out the chord changes for that song you want to learn but can’t find any sheet-music / tablature for. There is also an iPhone version of the app which I can’t comment on but is well regarded.

Capo is $50 for the Mac version and $20 for the iPhone version.

Reeder

The best RSS Feed Reader for the mac. It combines with the wonderful Readability service to make reading everything better.

Reeder is $9.99 for the Mac version, $4.99 for the iPad version and $2.99 for the iPhone version.

MailMate

A really impressive e-mail client, with a slew of functionality that can’t be found anywhere else, like a little pane that will show you all the prior conversations you’ve had with the person you’re currently reading an e-mail from.

One thing about it that you’ll either love, or hate, is that it intentionally only allows you to write e-mails in plain-text, but it compensates by being the only e-mail client I’ve seen on the Mac that also lets you write in Markdown, and automatically generates a nicely formatted version for your recipient to read.

The author advises using it for a couple weeks before making a decision about it. I’m going to have to agree with him. It’s capabilities definitely grow on you over time. It’s only downside is that, it isn’t quite up to the typically high UI standards that we’ve come to expect from Mac apps. It’s not bad looking, but it’s not great either.

MailMate is $29.99 with a free trial.

Why bootstrappers should track their time

Fri, 27 Jan 2012 00:00:00 +0000

The Problem

Most people only track their time when they are billing by the hour, and most people aren’t billing by the hour. As a result, most people don’t track their time.

Now, you can try to bootstrap a new business or product without time tracking, but you’re doing yourself a great disservice if you do. The problem is that we always think we can get more done than we really have time for, and we inevitably think we’ll have more time to work on things than we really do. Add to this the fact that humans are incredibly bad about judging and estimating time, and it’s pretty much guaranteed that our after-hours projects will take longer than we thought.

One of the biggest consequences of this to someone trying to bootstrap a new company, is an overestimation of what should be included in your Minimum Viable Product. There are so many features that would “be easy to add” or take “no time at all”, and even when they are easy, or fast, most of us are lucky to even have enough time to get the truly core functionality done. Not having a good grasp of just how long things are taking to complete allows these “nice-to-haves” to sneak in when they should really be held back for a future version of the product.

With no reliable information on how long it takes you to do something you can’t create useful estimations. When you overestimate your capabilities you underestimate the value of outsourcing, and what things most need to be outsourced.

In the end, bootstrapped projects, worked on in stolen hours between “real work”, and life, move at an almost glacial pace. Time tracking is the only significant tool we have to address this, and it becomes increasingly more valuable with each successive project.

##The Techniques

Precision is not important. You’re not billing anyone for this. What is important is that you’re keeping good track of the time spent on specific types of tasks, and that you can easily go back and see how much you spent on each. The most important thing you can do is to choose a tool that makes it easy for yourself.

Paper tracking can work, but the ability to see a nice graph of the time you’ve spent working over the past week should not be underestimated either. Seeing an unbroken graph showing your constant forward progress can really help keep you moving forward, knowing that you will make it there. If you find yourself skipping more days than you really ought to, that graph will help you to quantify just how much of a slacker you’ve been, and hopefully kick your butt back into motion.

My recommendation is to go with task groupings that are relatively high level, but detailed enough to help you assess where your time is going in a useful manner. Using just “Design” and “Coding” isn’t going to cut it. On the other hand, getting too detailed is going to be annoying to set up, frustrating to choose between when entering new time, and harder to track usefully when looking back.

These are the task types I’m currently tracking for my web applications:

Coding
Web Design ( HTML / CSS work )
Graphics ( logo design, image creation, etc )
Marketing
Market research
Code Research (tool research, project specific technique research, etc.)
Contractor evaluation / management

Track everything.

If you have to read a book to learn something specific to your product or it’s market then track it as research. These hours add up, and we never realize just how much time they take. Worse, we don’t take it into account when we’re trying to figure out how much time the next project is going to take. Track your time on this project and you’ll have some basis for your future estimations.

When outsourcing small focused task like logo design you’ll frequently be billed for the hours worked, but there’s no point in trying to convince the contractor to learn and use your time tracking system for your short task. Instead just enter the hours they spent working on it into your system yourself. If they’ve quoted you a flat rate, then just ask them for an estimate of how long it took when everything is done, or at the end of weekly updates.

In my case the Graphics, Marketing, and some of the Market Research is outsourced, and I’ll typically just add in the amount of time it took them in single shots on the given week. It makes the graphs look funny but I don’t really care how much they worked on any given day. I just want to be able to keep track of how much time they can and do devote to the project so that I can better predict what’s going to happen the next time I hire them.

Learn

Keep an eye on your hours through the week. Working a specific number of hours each day rarely works when you’re a bootstrapper; your day job, personal responsibilities, and taking time to relax and stay sane rarely leave us with much for our side projects. So, don’t berate yourself if you only got half an hour in last Tuesday. Use it as a tool to keep yourself moving moving forwards, and head-off slacking before it becomes a problem.

As your project goes forward patterns will start to emerge. You’ll discover that some types of tasks are taking you notably longer than expected. When you see this, don’t just sit on the information. Use it to your advantage. Outsource the parts that aren’t your core competencies. It’s generally a good idea to do that anyway, but being humans filled with ego, we tend to think we can do it all. Use what your time tracking is telling you to help convince yourself to get help. Remember, every additional day you have to spend working to get your project out the door is another day it can’t be making you money.

Reassess

At the end of a project make a writeup for yourself with all the important takeaways, including how much time each part of the project took. Then, figure out how much it would have cost you to outsource each ofnthe parts. Don’t calculate it at your rate, calculate it at the average rate of the freelancers you could have hired to do it for you. When outsourcing to people in foreign countries this can be significantly cheaper.

Once you’ve done that, figure out how fast your could have gotten the project done if you had of oursourced and parralellized as much of the process as possible. Some things simply have to wait for others to finish, but some tasks, like putting together your marketing strategy and copy can be worked on almost completely independently of other tasks.

##The Tools As I said above, the most important thing you can do is to choose a tool that makes it easy for yourself. Some tools have incredible lists of features; there are only two that matter.

How easy is it to enter time? More critically, how easy is it to enter time when you discover you forgot to hit start ontheir handy-dandy stopwatch.
How much do you like the tool?

Some tools have great functionality, and designs that are so ugly as to make you cringe every time you open it. Don’t use them. The harder, or less pleasant a tool is to use the less likely you will be to use it, especially when you don’t “need” to be using one.

My advice is this: almost all of the tools out there offer either a free plan or a 30 day trial. Pick the first one that looks interesting and isn’t too expensive for you. Use it religiously for one week. If it annoys you, or doesn’t make you happy, close your account and move on. Don’t bother re-entering the past week’s data. Repeat until you’ve found something that works for you. Do not let yourself just accept it as “good enough” and abandon the search. Humans are terrible about this. We’ll almost always stay in a slightly uncomfortable situation instead of risking a change that could make things better. If you’re not happy with your first choice, force yourself to try something else.

What I look for:

Good design
Trivially easy data entry. Everyone offers some kind of easy stopwatch tool. Few apps make it trivial to enter time without that.
Support for lots of projects in a plan I can afford. I am usually only working on one project at a time, but have an ongoing stream of them and don’t want to have to throw out the data I’ve collected on old projects in order to start a new one. The more historical data I have available the better I can plan my upcoming projects.
Good graphing tools that let me easily see the overall time spent as well as the time spent on given task types.

Things to watch out for

If you’re going to be outsourcing make sure that the tool has support for enough people at a price you can afford.

Many of the tools out there are very focused on freelancers, and small businesses that bill by the hour. They have the basic assumption that if you’re tracking your time, you must be billing for it, and if you’re billing for it then their software has become a critical piece of you making money. It’s a reasonable, and fair assumption and they should be compensated accordingly, but when you’re using their software to simply work on better managing your time, many of the features they’re offering become irrelevant, and not worth the money.

Some tools only retain your data for a limited number of years. This may or may not be an issue, but it is something you’ll want to consider. Personally I’d rather not have to worry about what to do to store all my old data on a rolling basis starting 3 years from now (or whatever their cutoff is). When I find a tool I’m happy with I want to be able to just stick with it and not have to ever deal with tracking down a new provider or archiving old data myself.

Pie charts. Seriously. The human brain is simply incapable of accurately judging the relative size of pie slices. Pie charts are only useful to show massive disparities. When evaluating the graphing tools of an app pretend their pie charts don’t even exist, because the data they provide you will not be notably useful.

Which tools to choose?

I wish I had a handful of great tools to point you to. Unfortunately I haven’t found anything that really makes me happy. I’ll let you know when I do. The best place to start though is Wikipedia, which has a great Comparison of time tracking software.

Have you found a time tracking tool that would be great for bootstrappers? Let me know.

The thing about Mock Objects

Sat, 14 Jan 2012 00:00:00 +0000

You can tell weather or not someone really “gets” unit testing by asking them one simple question, “Do you use mock objects?” Almost invariably, they will say “no”. Even people who have totally gotten the testing religion. It’s like watching someone pray to a statue of Jesus; totally oblivious to the fact that Jesus himself is standing four feet away reading a book.

This is partially due to the fact that most geeks don’t actually know what a unit test is. They think that testing the methods of a specific class constitutes a unit test, but that’s only part of the story. A unit test test is when you test the methods of a specific class in isolation, and the difference is critical. You know how some people call us “computer scientists”. Yeah, well this is the science part.

Imagine you were creating a new medicine, and wanted to test it out on some cells in a petri dish. The weather was so nice you decided to take your dish outside and enjoy the sunlight while you ran your test. It’s a resounding success! Or… is it? How do you know it’s wasn’t just the UV rays from the sunlight? Or maybe there was something floating in from the nearby blossoms? You don’t, and you can’t. You can’t even say, with any confidence, that the medicine worked. Something worked. Maybe the medicine had a part in it, maybe it didn’t. You can’t tell.

The same thing applies to unit testing. If you’re not testing in isolation there is no way to know that the thing your are testing was actually effective or if it just happened to work in the current environment, and when the test fails there’s no way to know (without digging) if your code was responsible, or if something it relies on has broken and passed on its problems. Mock objects are the best tool we have for addressing this problem.

A Mock What?

You probably already know, but just in case, mock objects…

“…are simulated objects that mimic the behavior of real objects in controlled ways. A programmer typically creates a mock object to test the behavior of some other object, in much the same way that a car designer uses a crash test dummy to simulate the dynamic behavior of a human in vehicle impacts.” - Wikipedia

In practice it is a functional guarantee that a foreign object/method/API, will behave in a specific way regardless of its implementation. You figure out exactly what a call should return and then you encode that in your mock.

Why?

Let’s look at an example. In a banking application a User would have one or more Accounts, and it’s not uncommon for the User and Account objects to each have methods that reference the other. Maybe, the User object has an available_funds() method that adds up all the available funds in each of the Accounts. User is depending on each Account object to correctly calculate the current balance, minus any outstanding charges. Problems arise when there’s a bug in how Account is doing its calculation. Now, the test of your User’s available_funds() method is failing, but you can’t tell if it’s because it was performing a bad calculation or Account was. Even worse, it could be that there’s bad data in the database, or that someone changed your test data but didn’t update the tests. All you know is that the number expected isn’t the one received.

The problem with this setup is that you’re no longer testing your User object when you do this. You’re testing that the code in your User class works if the code in the Account class also works. The typical solution of carefully chosen test data in a database does not solve this problem in any way. The only thing it does is add in another source of potential failures and misdirections, and provides yet another thing to maintain.

Using mock objects allows you to test that the User class works regardless of how broken the Account class may or may not be, with no database installed anywhere, and no separate fake data to maintain. You create a real User object and mock up the calls to Account to return mocked account objects, mocked data, whatever else is appropriate.

If you’re not doing this, you are not unit testing. That’s not meant to deride what you’re doing. I mean that as a literal statement of fact. Anyone, for example, who is using the built in Rails “unit” testing framework with fixtures (or FactoryGirl fixtures) is guilty of this. No test that relies on a separate class, or API, or interfaces with a database in any way is a unit test. It is an integration test (some people call them functional test), and when something goes wrong it is just a matter of time before it misleads you.

Now, integration tests are great. They serve the very useful function of guaranteeing that your code works within the context of the expected ecosystem, but they’re not very good about telling you exactly what has broken.

People will disagree with me on this. They’ll argue that testing with the db and other classes isn’t bad, that they can generally tell what’s broken very quickly. And it’s true that a developer with a good knowledge of the system should be able to figure out what’s causing a test to fail pretty quickly, but until they start digging there’s no way to be 100% confident that the bug is where the unit test claims it is because of all the other things that could affect it.

But that’s not all

The process of creating mocks to support your tests will very frequently reveal unexpectedly tight coupling’s between classes and systems. Because you need to mock up every interaction with a foreign anything, you end up creating a bunch of additional lines in your test. Each one is an expenditure of effort and each one represents a coupling. If the object you were testing wasn’t coupled to anything else you wouldn’t need to mock anything. Adding a few lines of mocking to your test is no big deal, but when you have 20+ lines of mocking in a single test it’s a strong indication that something is wrong in your system. If you find you can’t figure out how to mock something up it either means that you don’t really understand what the thing you need to mock does, or that it suffers from a notably poor design.

Mocking should always be easy, and quick. The only times it isn’t are when you’ve got a poor design, or an insufficient grasp of what you’re attempting to test. These are both very good things to have revealed.

Sometimes, the mocks will reveal bad designs, or excessive coupling’s in an library you didn’t even write. Part of the reason I started writing this article was because of just that type of situation. I was trying to unit test a Rails controller. Typically people just don’t unit test rails controllers. They do functional tests that tie in the controller methods, the database, and the view generation, which again, is useful, but doesn’t do a great job of telling you exactly what is broken when the test fails until you start digging. Anyway, the methods I was testing required an the user viewing them to be logged in, but try as I might I could not find a way to successfully mock it so that it never touched the database.

I assumed that I simply didn’t understand the library, and began looking and source code and googling around. After hours of trying, and failing, to make it work I eventually started Googling from a different angle and discovered that the problem was that it simply wasn’t possible (by any reasonably definition of the word) to test this library with mock objects, even leveraging its test helper classes. The thing was so tightly coupled to the underlying database that it demanded the presence of a test database with appropriately structured fake data to even create a test login.

I had to make the choice of either giving up on any hope of decoupling my tests from the database or throwing out a working authentication system. I care about my users, and I care about being able to guarantee that my sites work for them, so I spent two evenings throwing out that system, learning and implementing a new one, figuring out how to test it without touching the database, and then making all my controller tests work again.

It was worth every minute.

Reasons not to use mocks

The downside to mocking everything is the inverse of not mocking anything. If you don’t do pure unit testing, and don’t mock anything you can never be 100% confident that your objects work in isolation. If you don’t do integration testing and do mock everything you can’t be 100% confident that your objects work in concert with each other.

A combination of unit tests and integration tests is always best. There’s no reason not to build both. It just makes your system more robust and catches more bugs before they are released. But, if I had to choose one only one method, I would choose pure unit tests with mock objects for two reasons:

The objects you test in unit tests constitute the foundation, the building blocks, of your system. If they have problems then everything has problems. I want the maximum possible confidence that each of those building blocks is reliable and well crafted.
The process of mocking up the interactions with other objects gives me a far better understanding of how my system works and frequently reveals design flaws in my code, and the libraries I’ve chosen to use. Exposing and correcting those flaws helps improve the maintainability of my code.

I realize this is not the popular choice, and many developers, would argue that if you’re going to write only one test it should be an integration test. There are good arguments for that, but there are no good arguments for doing either without the other.

A moment for FactoryGirl

This one is specifically for the Ruby geeks, but I’m sure there are similar tools for other languages. FactoryGirl is a system that allows you to easily create named fixtures with the data you need.

“When you invoke a factory, factory_girl uses your definitions to compile a list of attributes that should be assigned to that instance, as well as any associated factories… To create an instance, it calls new without any arguments, assigns each attribute (including associations), and then calls save!”

In other words, it’s a nice wrapper around what is an inherently bad idea for unit tests. In fact, using it guarantees that you are not writing unit tests.

From what I’ve seen FactoryGirl is almost always used as a bad stand-in for mock objects. It is a good solution for your integration tests, where you actually want to test that items can be sent to and retrieved from your database from the other parts of your system, but it should never be called from a unit test because that is precisely what you don’t want happening in that situation.

Chris Parsons has a good writeup with plenty of code examples about FactoryGirl vs mocking that you should check out.

The Takeaway

There is immense value to testing in isolation and the process of creating mock objects to support that testing. If you’re not testing in isolation, you’re not writing unit tests.

If you haven’t been using mocks, take the tiny amount of time it takes to learn how one of the popular mock object frameworks for your language, and start updating your unit tests to be true unit tests. Make sure that every new one is a true unit test, and every time you have to touch an old one take a moment to replace the fixtures with mocks. It will be worth it in the long run.

Resources for Ruby Geeks

In the Ruby world we have a good number of mock object frameworks.

Mocha is probably the best known, and from what I’ve seen most widely used.
Flexmock is another option, but I have essentially zero knowledge about it.
RSpec has a built in mocking library called RSpec-Mocks. I have spoken with a number of RSpec users who prefer to use other mock libraries like Mocha instead of RSpec-Mocks. I’ve never gotten the RSpec religion so I can’t comment one way or the other.
RR (Double Ruby) is a lesser-known option. The syntax is very nice (not nearly as verbose) and it offers some nice features like Proxies and Spies that other frameworks don’t.

Personally I’m a fan of Mocha and RR.

My New Favorite Interview Question

Mon, 09 Jan 2012 00:00:00 +0000

I interview a fair number of geeks every year and usually spend my alotted time going over one programming challenge. Lately I’ve been looking for a new one that was simple, but still big enough to give me a glimpse into their thinking. I think I’ve found it.

Why I Like This

I really like this question because:

A good solution involves recursion but you could approach it in multiple ways.
The seemingly simple Array throws a monkey-wrench into the whole thing.
It tests their ability to follow written instructions.
It should give an idea of how willing they are to ask questions.
It’s small, but with 3 separate, but connected, things to handle should be enough to give insight into how they work through things.
In my experience you’ll spend ~40 minutes on this regardless of experience level. I’ve only had one person do it in 5. If folks finish a little early I try and find out what kind of job would make them happy.

The Question

You’re presented with the following YAML file which you need to convert to a useful data structure, but for whatever reason you don’t have a YAML library. You do however, have something that has converted it into a tree of nodes.

Each node has some useful methods you can call:

node.type returns Array, Hash, or String
node.name returns the name of the current node or null/nil if you’re looking at a node in an array.
node.value returns a node, or a String
node.next returns the next node in the tree at the current level or null/nil (assume there are no empty nodes)
node.children will return all the child nodes.

The goal

Using the following YAML as an example, create a method that will take a “node” and return a useful data structure. In the case of the example YAML, that structure would look something like this (Ruby notation)

# en-us is just the name we've assigned to the method's return value.

en-us['date']['formats']['default']   #=> contains "%Y-%m-%d"
# en-us is a hash, with a key 'date', whose value is a hash, 
# ... with the key 'formats' whose value, in turn, is a hash
# ... with the key 'default' whose value is a string.
# So, hash->hash->hash->string

en-us['date']['day_names'][1]       #=> contains "Monday"
# hash->hash->array->string

Notes

Keep in mind that Arrays items can themselves be Hashes, Strings, or other Arrays, and they can be nested, or empty.

Notes for Inerviewer

I present the interviewee with “The Question” and “The Goal” one one side, with the YAML printed on the back. I point out the YAML and tell them that I’ll go over it with them when they reach that point. You can find a PDF version of it here.

I also tell them that “If you ask questions I’ll give you helpful answers. If you don’t ask questions I won’t. Please ask questions.” and let them know that I’m not looking for perfect syntax, optomized code, or anything like that. I only want to see them work through the problem. That is 100% true.

It is very common for people to go down the wrong route before solving this. If someone is stuck on it for a while, I’ll tell them that if they can verbalize what they’re thinking, or ask me questions I can help. Every now and then you’ll get someone who absolutely refuses the help. That’s ok. You don’t want someone who refuses to work with helpful coworkers when they’re stuck.

The test is not to see if they can do it entirely themselves. The test is to see how they’ll work through a problem, and how they’ll leverage the resource of someone who knows more than them.

People who give up are an automatic fail for me. If you can’t work through a problem with a helpful questionner at such a critical time I can’t trust you in a crunch.

Help folks who ask questions. Give them honest answers and leading hints. Don’t give them the answer, obviously, but work with them like the future coworker they might. Help them to figure it out by building on the thoughts in their head.

Note that Junior / Intern level people may not have encountered the concept of recursion. That’s ok. At some point you may have to ask them if they’re familiar with it. Walk them through the idea and see if they can solve it then. Some mid-level people have it in their heads that recurion is evil for “performance reasons” and should be avoided at all costs. Assure them you don’t care about performance.

About the YAML

When they’re ready to look at the YAML I tell them that each line is a “node”. I then tell them I’m going to ask them some really “stupid” questions just to make sure you understand everything. I assure them that it’s not a trick. And then I ask them what the expected return values would be for each node type and make sure they understand that if i give them the - Tuesday node they’d give me the string "Tuesday", day_names becomes an array of seven strings, and so on. I also note that there can be nested data structures and that I don’t want a solution that would work for any tree of data structures, not just this tree.

The Yaml

"en-US":
  date:
    formats:
      default: "%Y-%m-%d"
      short: "%b %d"
      long: "%B %d, %Y"

    day_names:
      - Sunday
      - Monday
      - Tuesday
      - Wednesday
      - Thursday
      - Friday
      - Saturday
  time:
    formats:
      default: "%a, %d %b %Y %H:%M:%S %z"
      short: "%d %b %H:%M"
      long: "%B %d, %Y %H:%M"
    am: "am"
    pm: "pm"

Serving Octopress From a Self-hosted Git Repository

Mon, 19 Dec 2011 00:00:00 +0000

There are two good reasons to serve Octopress from a self-hosted git repo.

It provides you with an off-site backup in case your local copies go up in flames.
It gives you an environment where you can integrate secondary scripts and libraries that allow you to do things like e-mail posts to Octopress.
git provides a very efficient, and atomic, means of uploading your files.

Complicating factors:

Not all ISPs have ssh access or the latest version of ruby, and may not have git or Bundlr installed.
Because of the above you may not be able to regenerate html files from markdown on the server.
You need to have a basic familiarity with navigating directories and editing files over ssh.

These instructions are not for people uncomfortable with using the command line in a *nix environment. Of course, if you were uncomfortable with that you probably wouldn’t be using Octopress in the first place.

In order to do this you must have ssh access to your server, and have git installed on it. In order to generate new files on the server you must also have Ruby 1.9.2 (or higher) and Bundlr installed You must also have a basic understanding of how to get around on a Linux command line. This is not uncommon these days, but in order to check just ssh in and type:

which git
which bundle

If they both return a path to the executable you’re all set. If git is installed we can proceed without problem. If git and bundler are installed and ruby is at 1.9.2 we can generate the html on the server. For those not already familiar, which xxxx will print out the path of the executable if it is installed and on your path. If it returns immediately with no output it is either not installed or not on your path.

Next check the ruby version:

ruby --version

Octopress requires a recent version of Ruby to run, so if it says anything lower than 1.9.2 you will not be able to generate files on the server. Talk to your ISP about installing a more recent version of Ruby. You will, however, still be able to use git to transfer files to and from your server, serve from its generated directory, and act as a backup.

There are a couple ways to make this work. You could just host a non-bare repo on the server and set receive.denycurrentbranch to ignore so that you can push to it, but for security reasons, and safer removal of deleted posts it’s better to use a detached work tree.

SSH to your server, and create a new bare git repo somewhere that will not be served to the public.

#on the server
mkdir octopress_blog.git
cd octopress_blog.git
git init --bare
# core.worktree should point to a directory where 
# everything will be checked out into, but not 
# visible to the public. You must create this 
# directory. Git will not create it for you.
git config core.worktree /path/to/staging/directory

Once you’ve done that we need to set up the post-receive hooks. Create a hooks/post-receive file (in your bare repo) and make it look like this.

#!/bin/sh
# checkout the files after they've been pushed here
GIT_WORK_TREE=/path/to/staging/directory git checkout -f

Next, make it executable

chmod 755 hooks/post-receive

Later we’ll tweak hooks/post-receive to auto-generate the site (if you’ve got the pre-requesites on your server) but for now we just want to make sure we can push to it successfully.

Back on your local computer:

cd my_octopress_blog
git remote add live me@example.com:/path/to/octopress_blog.git

Now try pushing to it:

git push live master

It doesn’t have to be the master branch but that’s what most people use so we’re working from that assumption. It should push without problem, but pay careful attention to lines starting with “remote:”. If it does have problems, you should be able to figure out what’s wrong from the error message. At the end of the push you should see a message from remote saying “remote: Checking out files:…”

Back on your server take a look in the directory you pointed core.worktree at and see if your blog has been checked out there. From here on out we have to divide the instructions for people who can generate files on the server, and people who can’t.

To generate server-side or not….

Generating HTML server-side

Generating the html files server-side is good because you can set up things like JekyllMail to allow you to post to your Octopress without having to have a local checkout (great for blogging from work). Another benefit is that your “public” directory doesn’t have to be a subdirectory of your Octopress checkout. You can tweak your _config.yml to generate it anywhere on the server which can make server configuration easier for some. If you do change the destination attribute in your _config.yml on the server to a path that differs from your local version you’ll have to be careful to not commit any local changes to it.

Caveat Emptor: On shared servers there is one gotcha that you’ll have to be aware of. Long-running scripts are frequently auto-killed by the server so that one user doesn’t consume an unfair amount of resources. Until such a time as Octopress is capable of regenerating only the new posts there is the possibility that large blogs with hundreds of posts may exceed this limit and the generate script may be killed before completion.

Generating HTML locally

The only notable advantage to generating locally and pushing to a server-side repo is it works on servers where you have git but can’t run Octopress’ generate script for whatever reason.

Serving from a self-hosted git repo without generating HTML files server-side.

This is the simplest way to go, but it requires one change to the standard Octopress workflow, and the ability to point your server at a specific directory to serve your site from. In your workflow you’ll need to commit everything in your public directory each time your run rake generate, then push to the server. You need to be sure to add & commit any files deleted from your public directory after generation too, or else a deleted post will not get deleted on the server. Typically you can just say git add public each time and it’ll take care of managing the deleted files too.

Since the HTML files are going to be generated in a subdirectory of your Octopress repo (typically called “public”). You’ll need to point your server to the public directory under the directory that your core.worktree option is pointed at. Feel free to rerun the command above that set it if you want to change it to a different place now that you know everything works.

Once you’ve pointed your server to the appropriate directory all you will need to do to update your site and create an offsite backup of the original markdown files (and everything else) is to locally run

git push live master

Serving from a self-hosted git repo and generating HTML files server-side.

You’re going to follow the same steps as serving without generating files except you won’t be committing the “public” directory’s contents.

You’ll also need to add the following to the end of your hooks/post-receive

cd /path/to/staging/directory bundle install bundle exec rake generate

Note, if you’re using RVM or a custom gem path you may need to add those to the start of the hooks/post-receive script so that git will have it in its environment when it runs. For example, on Dreamhost you would have to add something like this to the top (assuming you’d already installed RVM and the current version of Ruby):

[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" # Load RVM into a shell session *as a function*
GEM_PATH=$GEM_PATH:/home/my_username/.gems
PATH=$PATH:/home/my_username/.gems/bin

Make a commit locally, push it to the new repo, and confirm that your changes have been pushed to the staging directory and that rake generate has done its job and placed the new html files in your “public” directory (or wherever your _config.yml has destination pointing to).

Once you’ve confirmed that that works you can (optionally) change the /path/to/staging/directory to point to somewhere that isn’t just for testing in the hooks/post-receive file and in the core.worktree setting. All that’s left is pointing your server at whatever directory your _config.yaml’s destination is pointed at.

From then on you just run

git push live master

on your local machine to update your blog.

Open Source Wednesday

Thu, 15 Dec 2011 00:00:00 +0000

This is a simple idea for every web development company (small or large) that owes its existence to open source software. I’m going to use Ruby on Rails as an example, but this is just as applicable to all of the other frameworks and tools we use daily.

On the first Wednesday of every month all of your developers work on bugs or needed features in one of the frameworks or tools that your company can’t live without.

The thinking is simple, and entirely self-serving:

A typical SAAS (Software As A Service) shop, or web development house is constantly depending on the quality of frameworks like Rails, but these frameworks are riddled with bugs and lack features that would really help.

No-one worth their paycheck would allow their own products to remain in a state like that, and yet we typically do nothing about those things in the frameworks and tools we are utterly dependent upon. Spending one day per month working on tools like these is not an altruistic move. It is a form of self defense. It makes your product stronger, and helps to guarantee that the tools you’ve built your company around will not fall by the wayside.

Improving the quality of the tools we all use helps to keep them popular, and popular tools get maintained and enhanced by more developers.

Contributing to the tools you work with regularly also helps build up your company’s reputation with the developers you most want to hire.

Open Source Wednesday helps your business, your customers, and your ability to attract the best talent.

How exactly is this done

Implementing Open Source Wednesday is simple, and there are a couple ways to approach it. One way is to simply point your developers at the issue tracker for the tool you want to contribute to and have them each choose a bug or feature request they think they can knock out in a day. Get together in the morning, make sure everyone’s working on something different, or intentionally joining forces, and set them loose.

If there’s a particular bug, or missing feature, that’s been impacting your daily work you might want to have some of your developers specifically attack that.

The thing to keep in mind here is to not take bugs that can’t be addressed in a day if you’re only going to work on them once a month.

Open Source Wednesday also serves as a useful change of pace. Letting your developers work on things that interest them outside of the tasks they’re faced with every other day helps to refresh the mind. And working in the different codebase is likely to teach them new techniques that can be applied to your business’ code.

What else?

That’s it. Go. Write something cool.

Why Wednesday?

I was looking for a day of the week that was somehow connected to the idea of “open source” and realized that “open” sounds like Odin who used to be known as Wōden and Wednesday is Odin’s day / Wōden’s day / Oden Dag/. Open -> Odwin -> Odwinsday -> Wednesday.

His name is related to ōðr, meaning “fury, excitation,” “mind,” or “poetry.” And what is code if not mind poetry? Wednesday seemed just about perfect.

Why There?

Wed, 14 Dec 2011 00:00:00 +0000

Where you spend your time developing is an important decision for an open source developer. Partly we do it for personal satisfaction, partly we do it to give us a tool we want, but there’s always a part of us that wants others to use and enjoy our work. I want to talk about that, and I want to talk about the frustrations that people who use those open source projects have, but first I need to set the stage. Paul Ruoget (@paulrouget) has been working on a cool live CSS editor for Firefox which should be out in FF 11.

When he proudly mentioned this on Twitter I responded in a less than helpful manner:

That’s great, and something i’d find useful… but right now all i really care about is seeing FF be as fast as Chrome.

I’m happy to say that Christian Heilmann (@codepo8) called me on it.

can you imagine how frustrating such a tweet is when you spent a few month building this great tool?

and later…

The point is that sweeping statements like that don’t help anyone. Your tweet might make people move, building good dev tools not

I think he was trying to say that stupid statements like mine, borne out of frustration from something only tangentially related can lead developers to simply stop contributing at all. He’s totally right, and I’m sorry I said that Paul.

At the same time, I am frustrated, and while it’s not even remotely Paul’s fault this frustration is shared by many many webdevs and it does affect Paul, and everyone else who wants to develop cool things for Firefox.

Firefox is slow. Once upon a time it was the king of the hill. We switched to it because it was soo much faster than anything else, and then tools like Firebug came along and FF became a joy to use for developers.

Somewhere along the line that changed. For reasons I can’t explain FF has become notably slower than the alternatives… and that is the only comparison that matters. A slow browser is fine if there aren’t any speedy ones you could use instead, but Google has put Chrome out there and, by comparison, it feels blazingly fast. I can feel the delay every time I open a new window in Firefox.

I just tested it. It just took nearly five seconds for FF to open a new blank window. I regularly see delays of one to five seconds. It always takes a fraction of a second for Chrome to do it and I’ve always got way more open in Chrome. Honestly, I don’t like Chrome… not when compared to FF. But every single action we perform in our browsers is affected by the underlying speed of that browser. For a web developer with 20+ tabs open with research, test, and reference pages open all day long this is a huge deal.

And that’s how we end up with people like me saying stupid shit to people like Paul who are trying to make our lives better.

But… I am a developer too. I’ve got a FF extension, a useful Greasemonkey script, and a few cool Ubiquity tools that are all sitting abandoned for the simple fact that I am unwilling to add that kind of delay that Firefox demands to thousands of actions I perform every day. No, I’m not saying that everything in FF takes 5 seconds longer, but I am saying that everything in FF feels like it takes longer than the alternative.

I look at what Paul is doing and think that
A) there’s already live css editing in the Web Developer extension.
It’s probably not as good, but it’s there) and Firebug has it to some degree too.
B) Here’s a guy building something cool that developers like me are never going to use because the environment he’s chosen to do it in is slow, and loosing people like me to the competition at an astonishing rate.

So why is he writing it at all?

Firefox developers have been making progress in speeding up FF, but it’s a hard problem, it’s taken them a long time, and it still feels like they’ve got a long way to go before they catch up. Now, I say “feels” here because that’s what’s important. Numbers don’t matter to end users. It’s all about perception.

Consider this little story from the guys at Panic regarding a metting they had with Apple.

Jeff Robbin then asked us a funny question that had obviously been percolating for a while: “Does Audion do any kind of special filtering?” You see, since the beginning of time, press reviews in magazines, websites, etc., had consistently said that Audion simply sounds “better” than SoundJam, without question. It wasn’t until that declaration showed up in a very respectable, high-end British Hi-Fi magazine that people started to take it even more seriously. Audion was always noted for being “richer” or “sweeter”, and we were tremendously proud of our incredible results in this regard.

The only problem was: we didn’t do anything. We have no idea why people heard Audion as sounding better.

I try and put myself in Paul’s shoes and have to wonder if I’d think it was worth it. Sure, he loves FF, and maybe that’s good enough reason to stick with it. But, I just like Firefox, and wish that it was keeping up because I love the tools I used to use with it. If I wanted to build a kick-ass live CSS editor I can’t say that I would be willing to build it for FF right now.

And that’s a question we all have to ask when we’re developing something that’s completely dependent on some larger project beyond our control. Is loving the platform enough? Even when thousands of the people who would benefit from your work are leaving it?

Saying “be faster” is like saying “be better” Of course we are working on performance. But we can’t work only on perf

Paul

He’s right, and yet, at the same time I think he isn’t. Firefox has better tools, better extensions, better extensibility, better everything, but every action you take on it either is slower or feels as if it is. Would Firefox really be hurt in any notable way if it actually did apply every resource at their disposal to speed improvements? I realize this isn’t realistically possible, because not every developer has the skills needed to address the problem, and no-one wants to see the other aspects stagnate, but I think it’s still a valid question.

Christian is right that those of us sitting on the sidelines shouldn’t disparage those who are doing good work, even if we think they’re doing it on a sinking ship. I really hope that FF can come back from setback that Chrome has presented it, but in the meantime where does a developer put their energy and what is the best way to keep them from not contributing at all.

I should have said something like this:

That live CSS editor looks great.

… but how do I tell Paul, and people like him that as much as I appreciate what they’re doing, and as much as I really want to use it, I’m saddened to and frustrated to think that thousands of people like me may never touch it, because of something it’s tied to that he has no control over? Is there any way to do that without discouraging them? Is it better to just shut up and leave them to their dreams?

Maybe…

I’m sorry that this post, and my earlier tweets are probably disparaging to Paul. That’s a shit thing, but even if I had the polite social interaction thing down, it seems like in the end the only way to avoid future occurrences is for people like me to not ask “why?”, or at least not publicly discuss what comes out of those thoughts.

The uncomfortable state of things doesn’t have to be the end of it though. People like Paul love Firefox enough to devote serious amounts of time to making it better. I think it sucks that we are in a situation where asking “Why is he bothering?” has some legitimate value. But maybe if more of us stopped taking the easy route of jumping ship to whatever competing tool is “better” at the moment we would actually take a moment to help bring the tools we “loved” back into fighting shape.

I may not have the skills needed to make FF faster, but I’ve got some decent JavaScript skills that could probably be used to help improve the test JavaScript test suite. If you’re a geek like me who’s gone to the land of Chrome, but lament all the great tools you’ve left behind, consider swinging over to the Firefox Bug Tracker and see if there’s a small task or two you can help out with. If nothing else there’s probably a bunch of bugs in there needing confirmation.

Maybe, if we get off our asses, we can help get Firefox back to being the most awesome browser around. I know I’d love to have my default browser be the same one with all the cool tools.

It's Worse When the Sun Goes Down

Mon, 31 Oct 2011 00:00:00 +0000

At our house, you go to the bathroom armed, or you don’t go at all. At least, once the sun goes down. There’s a pistol wedged between couch cushions with handle raised for easy access as we watch TV. You think I’m joking, that maybe the gun is metaphorical, or that this is the start of some fictional story. It’s not. Every word is true.

It all started a month or two ago. We’d hear them moving around. Little sounds. Things you could write off and not really worry about: “Probably just a mouse…” But each night the sounds got louder. The little scratches escalated until they were thumpings on the wall. And then the hole opened up, like the gaping maw of hell itself. It would almost be better if it really was an entrance to hell. At least with hell there’d be flames, or something. But this is just blackness, silent and dark. Maybe the Christians have it wrong.

We take turns staring at the hole now. We stand watch… once the sun goes down, the dogs safely ensconced upstairs. They’d just be collateral damage if we let them out. Part of me wonders if there’s a point. We don’t know if our weapons will even effect them. We’ve shot at them before with no effect. They’d hear the sound, or maybe see us moving the gun into position. Maybe they simply hear the explosion as our projectiles exit their chamber and step out of the way.

They haven’t touched us… yet. But they’ve come close. For the past couple days, ever since it happened, I’ve been having flashbacks. Adrenaline coursing through my system as I hurled myself backwards watching it pass inches from my face and set my heart pounding at a thousand miles an hour. I don’t think it was even trying.

We tried laying out a field of glue. Some super adhesive stuff. I think they may actually use a variant of it as an organic equivalent to waxing legs. Heat it up, slather it on, add cloth, and rip… Depilation was not our goal though, nor were we so naive to think that it would actually capture them. No, we were hoping that maybe, just maybe, it would slow them down enough to get a shot off, that maybe, it would buy us a moment of distraction, just long enough to aim, and fire.

All it did was annoy them, and I assure you, you do not want to annoy them.

We’ve put in a call for bigger guns. Gods help us.

gVim / MacVim drag command for base64 encoding images

Thu, 25 Aug 2011 00:00:00 +0000

The idea is that it can be very useful to base64 encode an image directly into your css file instead of referencing a separate file, but doing so usually involves dropping to the command line, calling openssl, copy-pasting the output, specifying the mime-type, etc… Bret’s Terpstra distilled all of that into one drag-and-drop command for Textmate.The following is simply a generalization and instructions for using the drag and drop in MacVim / GVim

First, take the following and make it into an executable somewhere in your path. That way you can use it from any app that can interact with the command line. I called the fill css_image

#!/bin/bash openssl base64 -in
"$1" | awk -v ext="${1\#\*.}" '{ str1=str1 $0 }END{ print
"background:url(data:image/"ext";base64,"str1");" }'

It’ll generate something like this (only much longer):

background:url(data:image/png;base64,iVBORw0KGgoA...AAAAASUVORK5CYII=);

Now, to call it from MacVim and have the output inserted into your file simply switch to command mode and type

:r ! css_image

leave a trailing space and drag the file into MacVim and hit enter. Dragging it on when in this state will cause the path to the image to be inserted. Enter causes the command to be executed, and the output to be inserted into your file.

JekyllMail: Posting to Jekyll from Email

Thu, 18 Aug 2011 00:00:00 +0000

There are a few problems with Jekyll / Octopress though that would, realistically, make me less inclined to use it. First, you need to have your entire blog checked out on whatever box you’re posting from, and that is simply not something I’m willing to do on a work computer, and not something I necessarily can do when on a borrowed computer. Secondly, the user interface sucks. Well, there really isn’t one.

Being able to send e-mail to your blog and have it posted solves both of these problems. I can e-mail from anywhere, and there are tons of e-mail clients with good user interfaces, and there are good Markdown apps on the iOS that will e-mail off your Markdown formatted writings. I wouldn’t be surprised if they handled Textile too, but I wouldn’t know.

So, I did a little hunting around and found a script by Ted Kulp that works with procmail to post a Markdown, Textile, or HTML formatted post to a Jekyll blog. Procmail’s not an option for many of us, but POP3 is. So, I did a little hacking, added POP3 support, made some configuration and anti-spam tweaks and JekyllMail was born.

In addation to importing your post it will also save your image attachments. I heartily encourage folks to fork the repo on Github and send in pull requests.

[Review] Byword for OS X

Mon, 15 Aug 2011 00:00:00 +0000

[Some perspective][]
[What’s good][]
[What could be better][]
[Bugs][]
[Would I recommend it?][]

Some perspective

I purchased Byword because I think Markdown is a spectacular way to write and was looking for an app that would allow me to create new documents, easily preview them and grab either the formatted preview text or the generated HTML.

Until now, I’d been using Marked for previews while I typed in Vim. Now, Vim’s great. I love coding in it, but it’s really not the greatest when it comes to writing text, and I’m not really a fan of any of the other apps that handle plain text well. So, I went off in search of an app specifically designed for creating documents with Markdown.

What’s good

It does what it claims. Easy markdown editing. It also supports Rich Text and Plain Text.

It’s nice to be able to bold or italicize with Markdown using traditional key-combos instead of having to manually type the asterisks.

Full Multimarkdown support.

You can use it in conjunction with Marked. No need to stop writing to preview the formatted version. Below we have Byword on the left in edit mode and Marked on the right reloading a preview of the changes whenever you save.

It’s only $9.99. Totally worth it. It’s nearest competitor iAWriter is almost twice the price at $17.99

What could be better

The default file format is Rich Text. You can change it to Plain Text or Markdown in the preferences, but I get the feeling that the creators were making a minimalist text editor and then decided to add on Markdown support rather than making a Markdown editor that also supports the other formats.

Preview can be a little slow sometimes.

If you look at the screenshots on the site you’ll see a little popover menu for text styling. That’s there, but only on Rich Text documents. In their defense most of the options there aren’t supported by Markdown, but it doesn’t mean it wouldn’t be nice to have a version of it for Markdown.

Its main competitor iAWriter has “reading time” as one of the running counts along the bottom in addition to the standard word count. I really wish Byword had this.

Like most apps that partially format your markdown while you’re typing it (making *foo* italic in between the asterisks, etc.) it bolds the headings, but there is no difference between a #, ##, or ### heading. They’re all just bolded. I really wish that apps like Byword would make the # headings larger than the ## headings, and so on.

Bugs

At the time of writing (Aug, 14 2011) there are a few bugs that I’ve encountered in my first few thousand words of writing with it:

If you like to balance out your heading tags with octothorpes at the end (e.g. # foo #) you can’t have any trailing spaces afterwards or the final octathorpes will be treated as text not formatting.

Clicking on footnotes in the preview has an odd quirk. The first time you click the footnote number (in preview mode) it opens in the default application associated with the document’s extension. Ditto for the first time you click the return link at the end of the footnote itself. The problem arises when the default application is not Byword. For me clicking the footnote opened it in Vim, but only the first time. Very strange.

Sometimes the traditional keycombos for making text bold and italic simply stop working. For some reason they no longer work in this document but do in others.

The documentation claims that “If you drag images into the text, they will automatically be replaced by a Markdown reference to the file.” Like the key-combo problem this seems to not work all the time. And when it does work it’s missing the initial exclamation point. When you drag an image from the browser you get a link in the markdown, and I don’t mean [foo](url here). I mean a blue underlined http://www.foo.com/img.jpg thing that you can click on in Markdown editing mode, which should never happen. When you drag an image from the Finder it gives you file name which ends up being a link instead of an image (because it lacks the inital exclamation point) and it’s a link that won’t work on any computer other than your own.

Saving a file with the .mkdn extension instead of the expected .md makes it cease to display correctly in editing mode (markup is no longer greyed). It still previews correctly though.

Searching for a word or phrase will highlight it, but hitting the delete key will not delete it.

Yeah. Byword is a decent app. It doesn’t wow me, and the bugs are frustrating, but infrequent. The drag-and drop image linking that it promotes simply doesn’t work in any useful way, and I’m annoyed by that because it’s one of the reasons I bought it over iAWriter. With that said though I don’t feel particularly disappointed by it either. Full Multimarkdown support is nice, especially when you consider that iAWriter doesn’t even support full Markdown, and really, at $9.99 you’re still getting a lot of value for your money.

It's not a "blog"...

Mon, 15 Aug 2011 00:00:00 +0000

Listen, you are an intelligent person, but someone has led you astray, and it is driving me nuts.

When you blog some information for the world to see, what you have created is a “post” more specifically, it is a “blog post”. Sometimes they’re “entries” but that’s more commonly associated with diary style blogs. In some cases a post could be considered an “article”, but those posts are never, ever, a “blog”.

Blog, as a noun, is short for web log, as in, “there were many entries in his log”. It is a collection of entries, and never a single entry itself.

Blog can, of course, also be used as a verb, in which case it is the act of creating one or more posts for a blog.

When you tell people that you have “a new blog” you are telling them that you have a new log of entries separate from any existing one. This is almost always an indication that you’ve decided to start creating a series of posts that are topically separate from the posts on your current blog. You are not telling people that you have added a new post to your existing log.

Unfortunately the latter is almost always what you intended to convey. So please, please, for all the people who follow you on Twitter, Facebook, Google+, and anywhere else you give notice of new posts, stop calling your posts blogs.

P.S. Some people have countered by suggesting that language is mutable and constantly evolving. While this is true, the word blog has not mutated to the point that it is interchangeable with the word “post”. Using it as a replacement currently only serves to demonstrate an ignorance of the actual meaning, and confuse your readers who know better. You’re an intelligent person. Don’t make yourself look ignorant.

Thinking about Lo-Fi camera apps

Sat, 07 May 2011 00:00:00 +0000

Anyone who’s been following my Twitter feed lately knows that I’ve been having a lot of fun with the Lo-Fi camera apps on the iPhone, and I had a post all written up about them, but then my friend Kirk tweeted:

Gotta admit I hope the whole instagram thing is kind of a fad. Makes all [the pictures look] like those b+w “dress up like Bonnie and Clyde”

I think he’s not alone in this opinion, and he’s definitely got a point. There are a lot of cheesy pictures being uploaded by people just playing with the effects. But I think he was missing something vastly more important: They’re getting people to take pictures.

They’re getting millions (literally millions) of people to look at the world around them with different eyes. It doesn’t matter that they’re going “oh, I wonder what that would look like with a quirky effect…” what matters is that they’re looking. We spend more and more time wrapped up in our own little worlds. Especially those of us fortunate to have smartphones. We tweet, we text, we play games and we loose touch with the world we’re moving through.

The boring walk to work or school has been transformed into an exercise in observation. It doesn’t matter that people are frequently photographing mundane “boring” objects. What matters is that they are finding beauty and interest in the world around them.

Sometimes they go a bit crazy with the effects, but so what? They’re being creative, and even the most brilliant artist takes leave of their senses from time to time.

People are taking the time to look up from their smartphones, and not obsessively thumbing out Facebook updates to each other.

And maybe some of them will realize there’s life outside of the computer screen.

… I’m sure we’ll get tired of the Lo-Fi effects soon enough, but I hope that by then the apps have evolved into tools that allow for even more expressiveness. Instagram in particular has done something I would have said was nigh-impossible a year ago. They’ve created a whole new social network. Sure, they snuck it in the back door when no-one was looking but they also tricked people into actively looking for creative things to photograph and share with their friends who are sharing creative photographs with them. On top of that Instagram’s created a whole ecosystem of applications by opening up their API to outside developers, which makes it more fun to use, which makes more people use it, which makes it more popular, which gets more people taking pictures, and on, and on…

This isn’t to say that the Instagram app is the greatest. It’s certainly the prettiest of the bunch, and has the best usability and sharing features, but it’s only got a handful of effects and they’re not adjustable in any way. It’s not surprising then that you see a number of pictures in peoples Instagram feeds that have been manipulated in other apps, but that just goes to show what an amazing thing they’ve created. People actually go out of their way to upload their pictures to their Instagram feeds.

These days I’m mostly reaching for Photoshow and Infinicam. Infinicam feels like it lives up to its name with a huge number of potential effects combinations, but it’s a lot of random luck (and crap) until you’ve saved off a good swath of combinations you like as favorites that you can then apply on demand. Its sharing capabilities suck though. If it didn’t have so many great borders and lo-fi effects I wouldn’t bother, but the borders are great and you can easily flip through them once you’ve found a visual treatment you like.

Typically I take pictures with the built-in camera (so that I’ve got unaffected originals that can be loaded by most of the apps) and bring them into Photoshow where I can crop them square (so that fit in Instagram’s format), then fiddle with effects there or save it and fiddle in Lo-mob or Infinicam. Sometimes they bounce around between apps layering effects until I’m happy, and eventually get uploaded via Instagram, unless I’ve decided I’m unwilling to stick with Instagram’s demand for square photos.

As for the apps themselves, well, there’s a lot of room for improvement. Most of them seem to offer a handful of carefully selected effects to choose from, but offer no way to combine the features of them (this border with that tint for example). Photoshow is excellent about this. Infinicam does offer it but not in a direct way. It’s more about finding happy accidents and then saving the ability to recreate them. And then there’s the constant square cropping. I don’t mind square pictures at all, but sometimes you want a wider view of things.

Anyway, if you like these pics, follow me on Instagram (if you have an iPhone… coming soon to Android ;) ), or Flickr, or Twitter. I’m masukomi on all three. There’s also Facebook. Yes, believe it or not I’m actually doing something with Facebook (friends will understand how shocking this is). But, even if you don’t follow me anywhere… pick up a camera and go find the beauty around you. Then share it with people. And have fun. :)

For the iPhone there’s: Instagram, CameraBag, Toy Camera, Lo-Mob, FX Photo Studio, PictureShow,Infinicam, and more… For the iPad there’s: CameraBag for iPad, FX Photo Studio HD, and not much else, but that it starting to change now that the iPad 2 has a camera.

Cleaning Wordpress of some Malware

Tue, 26 Apr 2011 00:00:00 +0000

The other day the Googlebot swung by to check my site for updates and found Malware. Almost immediately, it seemed, people’s browsers were warning them off from my sites. Malware! Bad Things (TM)! There be Dragons here! and so on. Fortunately a friend dropped me a Tweet shortly after it started and thus the hunt began with one clue:

Malicious software is hosted on 1 domain(s), including globalpoweringgathering.com/.

Sadly, that was ALL I had to go on, and when I told the browser I was ok with the risk (Windows malware can’t hurt us Mac folks) I was unable to find any calls to JavaScript to files on my blog. I couldn’t find any that were encoded either. I was stumped. Poking around on masukomi.org, which is just plain HTML files I did find they had all been prepended with an evil script tag, but that was easy enough to replace as there were only a few files. weblog.masukomi.org though… I was stumped. I’m still not sure where exactly it was coming through to the browser, but I did find the culprit.

I should note here that Securi’s free malware checker should definitely be commended. It helped narrow things down and confirm that the site was clean in the end. You should definitely take a minute to plug your site into there and double check that all is ok. Unfortunately as they make their money by fixing malware problems for people, and monitoring for them, they don’t actually tell you how to get rid of any of it. Anyway, at the top of twenty-four of the core Wordpress files (wp-*, index.php, and xmlrpc.php) was a single line 3,209 characters long that started like this

 <?php /**/ eval(base64_decode("aWYoZnVuY3Rpb25fZXhpc3RzKCdvYl9zdGFydCcpJ

For the non-geeks amongst you, that’s a piece of source code that’s been Base64 encoded so you can’t just search for the globalpowirenggathering.com domain, or anything else that a human would recognize. The PHP then decodes it with base64_decode and then executes it with eval. It decodes to a bunch of stuff that looks like it’s targeting Internet Explorer users. Seriously people? Chrome, Firefox 4, or Safari… Anything but Internet Exploder. Geeks: just run the following code on your server’s command line to get a list of infected files. If it doesn’t pull up anything then replace the gibberish in quotes with a section of the Base 64 encoded text from one of your infected files.

grep -rc "aWYoZnVuY3Rpb25fZXhpc3RzKCdvYl9zdGFydCc" * | grep -v ":0"

Non-geeks: If you don’t have a geek, or shell access to your site that you can hand over to a geek you trust then your best bet is to simply delete your WordPress install and reinstall it from scratch. Write down the plugins you’re using first so that you can re-download and reinstall them, and don’t forget that your WordPress install creates an “assets” directory at the top level for the various files (images) you’ve uploaded for your posts. Some viruses do infect images, but the particular malware I’m referring to here does not. So, if you replace the entire WordPress install (just to be safe) be sure you have a copy of your assets folder that you can re-upload.

Reinstalling it from scratch really is the safest way to address the problem and it’s actually pretty easy because WordPress installs are very painless these days. As always, be sure to backup your database first.

Speaking of… backing up your database to a text file is actually a reaaaally good idea in this case because some variants of it inject themselves into all the posts in your wp-posts table. If you back up your db to a text file you can then search it for any of the offending domains, “eval” statements, “unencode” statements, or PHP that you didn’t put there. If they’re in there, you’ve got your work cut out for you, but this does emphasize just how important it is to do regular backups of your database. If it gets infected you can just restore from a recent one.

I was lucky. It was just the PHP files on my blog and a handful of html files on the main site that were infected. Cleaning up one line from twenty some-odd files is not so hard. In fact, once I knew what WordPress files, I just replaced them all with the latests ones from a fresh WordPress download. Before you do that though make sure you’ve grabbed the settings from the wp-config.php file on your server. Don’t worry. Reading the file with a text editor can’t infect you even with the malicious code in it. Once you’ve replaced those files you can hop over to Google’s Webmaster’s Tools and request a review. The review doesn’t happen immediately, but it bumps up your priority and apparently doesn’t count against you if you still fail, but shows that you are taking action to eradicate the stuff.

Also, change your passwords. Change the password on your account with your ISP, and change your password in WordPress. It is possible that this password has been compromised. If you use the same password anywhere else (bad idea) then be sure to change the password on those sites too. Note: other domains that might show up from this malware infection: globalpoweringgathering.com lessthenaminutehandle.com lessthenaseconddeal.com welcometotheglobalisnet.com

Geeks: If you know git, I’d suggest creating a new git repo at the root of your blog. Add and commit all the WP files into it. You just need to remember to update it when you update a plugin, theme, or wp itself which is generally infrequent. Next time the malware strikes (it will) all you’ll have to do is

git reset --hard HEAD

Check for any strange new files with

git status

and delete them.

You won’t have to worry about what malware it is, or what it has or has not infected.

Adventure means taking chances

Tue, 07 Dec 2010 00:00:00 +0000

Tomorrow morning Dachary and I will be climbing on our motorcycles and setting off for an epic adventure lasting nearly four months and over 17,000 miles. The goal is to drive south from Boston MA, USA until we reach the most southerly city on the planet: Ushuaia Tierra Del Fuego, Argentina. I can’t wait. Usually when we tell people their first reaction is “Be careful in Mexico.” Colombia, Nicaragua, El Salvador, Honduras, rebels living in the jungle… not a concern. But Mexico! OMG Flee. The fact that millions of US Citizens cross into Mexico, shop, and relax just south of the border without harm is irrelevant. Some Mexican citizens have been kidnapped, and held for ransom. Some Mexican businesspeople have been extorted. Some US citizens have been kidnapped but most of them are hispanic and there have been

“very few cases where a tourist is targeted at random,” said Eric Drickersen, who supervises the FBI’s border liaison office in San Diego.

More importantly, most of this stuff seems to be happening close to the US/Mexico border; a place we intend to spend only as long as it takes us to get through customs and head south. We’ve got better things to see than Gringo tourist traps. So, I appreciate the concern, really I do. But, if you’re gonna worry, worry about bigger things. Like breaking a bones in the middle of nowhere, being forced off a cliff-side road with no railings, getting Malaria, being stopped by rebels is south-west Colombia. Me, I’m not actually worried about any of that. It’s all possible. But, worrying about it does’n’t help at all. If anything it makes it worse by stressing you out. But, I am slightly worried about one thing: coming back. You see, I am officially unemployed. When I planned this thing I was under the impression I’d be able to get unpaid leave from my employer, but that fell through in the end, and when given the choice of continuing to sit in a cubicle and continue doing the same tasks I’ve been doing for fifteen years, and getting on a motorcycle and exploring the world for four months, possibly returning home completely broke… well, that’s not much of a choice at all. I mean really. A person has to have their priorities straight. And living in fear of not having money is not a very high priority for me.

“Ooh Can I?! Can I please continue to live a mundane existence so as to make sure I receive another paycheck that allows me to continue to live a mundane existence? Please please?!”

Fuck that noize.

My coworkers gave me a going away party, which I am very thankful for. But, one of the most memorable parts of that was speaking with a coworker about The Adventurists. The Adventurists offer a number of great adventure packages that you should definitely check out, and spend some time daydreaming about. One of the most popular is the Rickshaw Run. They provide you with a “rickshaw” (basically an old vespa with 3 wheels, a windshield, and an open body welded to it) that is not even remotely designed for thousands of miles of driving, almost guaranteed to give you problems at some point along the way, and an a route across India that will take you about two weeks to complete, with essentially no support from them.

Ill-advised, uncomfortable, impractical, dangerous, pointless, furstrating, unreliable, unstable, stupid, painful, all great things that make the rickshaw the ultimate all terrain machine. - The Adventurists

If it was easy it’d just be a pretty ride, but breaking down in the middle of Inda and having to figure out how to fix it… that would be something to tell your friends about. That’s an adventure.

My coworker thought the idea was wonderful, but he had a baby about a year ago, and simply couldn’t do something like that because he had responsibilities. But, his stay-at-home wife is smart, and surely could take care of the baby for two weeks without him, he’d be gone on paid vacation, and the chances of dying are really no higher than they are here at home…

The point is, we build these mental cages for ourselves. “Oh I’d love to do that but I can’t because…” This seems especially true of people with children, but the best gift you can give a child, your partner is happiness, and happiness doesn’t come from a paycheck. We were poverty-level poor for much of my childhood, but my mom did what made her happy, kept us fed and clothed, and did whatever she could to make me happy too. You think I would have cared if she’d left me with Dad for two weeks while she went and had an adventure? Hell no. And, in the years that followed I would have wonderful tales of far off places. When I was a baby she took me to the Grand Canyon. Rode down into it on a donkey. I don’t remember a second of it, but I remember the story, and her telling me how wonderful it was.

Unless you’re in prison there is nothing keeping you from having an adventure. When you look back at your life do you want to see a life spend primarily in a cubicle, a few hours with your friends and family each day before going to bed, and if you’re lucky some time on the weekend squeezed in between all the errands you couldn’t do during the week?

I don’t care what anyone says. That is not a life well spent. I don’t care if that cubicle dwelling allowed you to put your kid through school. You barely get a chance to see them, and you sacrificed your own happiness to do so. Lots of people enjoy their jobs, but few of them think spending 40+ hours a week sitting in a cube staring at a screen is a good life. I love coding, but I want to look back at my life and feel that I lived it, that I did something memorable, and special with it. Sitting in a cube staring at a screen is neither memorable, nor special.

The job I just quit was an excellent one, surrounded by good people, but it did not make for a life well spent. It did, however, provide me with the means to make a good start on one.

We’ll be documenting the adventure on CorporateRunaways.com. I invite you to follow our adventures, and start figuring out how to have your own. Life is too short to spend it all at work. Make it memorable. Make it fun. Make yourself happy.

Food and Cuisine (a brief history)

Thu, 07 Oct 2010 00:00:00 +0000

A brief history of food:

Early man: “So hungry…. *chomp*” Not-so-early man: “I wonder what that tastes like…”

A brief history of cuisine:

“What would make that taste better?”

Counting the days until Borders dies

Thu, 16 Sep 2010 00:00:00 +0000

Honestly, I kind-of like Borders (and Barnes and Noble), and they’re the only ones with a zero BS customer loyalty signup process.

“Do you have a card?”
“No.”
“Would you like one? I just need your e-mail address.”
“Ok it’s _____ "
“Here you go.”

The end. No paperwork. No forms. Thirty seconds. But, that’s the only thing they’ve gotten right in a long time.

Today they sent me an email announcing that “You could win the new American Girl doll”.

Seriously?! There’s only one kind of book I buy at Borders: urban fantasy. I buy everything else at Amazon.com, but when it comes to new fiction I like to browse physical aisles to find new authors. The only exception to this has been one or two of the Harry Potter books. So, after years of buying Urban Fantasy books about werewolves, vampires, zombies, and other supernatural beasts (almost all of the stories centering around a murder that needs to be solved) they think I’d like an American Girl doll. They’re so off the mark that I didn’t even know what an American Girl doll was until I looked at the email. If it wasn’t for a random work coincidence I wouldn’t have even heard the name before. Now that I know what one is I know for a fact that it is nothing I would ever buy, or even contemplate buying. And I’m fairly confident i’d never buy one of the American Girl books as a gift either as there are some truly exceptional children’s books out there that aren’t trying to sell you dolls.

Honestly, I find this insulting. It’s even worse than the time they tried to convince me to buy a book that I’m pretty sure I’d already bought from them. It’s really not that hard to figure out that someone with my buying history has no effing interest in something like that. It’d be like promoting a book about the Pope to someone who just buys books on atheism.

Contrast that with Amazon.com’s emails. “Hey, we noticed you’ve been checking out <item x>. Here’s a bunch of popular related items you might be interested in.” or “Hey, there’s a new book from an author you keep buying. Bet you’d like a copy of that huh?” (paraphrasing of course).

Borders meanwhile just spams the entire freaking list. “We want money! Here’s random crap! Buy it!” Borders is going to die, and it’s their own stupidity that’s going to do them in. Never-mind how badly they’ve been screwing their employees lately, although that falls under the category of “their own stupidity” as well.

And then there was the bear...

Wed, 08 Sep 2010 00:00:00 +0000

We rode the Trans-Massachusetts-Trail yesterday. A series of dirt roads starting at the border of Connecticut and Massachusetts and working its way north to route 2 where it meets up with the start of the Puppy Dog Trail, which winds its way north all the way to the Canadian border (we’ll be doing that one shortly). Near the end of the trip we stopped for a break in the woods to address the “call of nature” and grab a snack.

To the right was a small hill, and the left edge of the road had a two foot mound, that turned out to be a half buried stone wall, before continuing down the hill. I’m not sure how far it was to the bottom, maybe a hundred feet, but from where we’d pulled off to the right of the road we couldn’t see down past the mound.

We chatted and drank some water, and ended up quietly enjoying the scene for a few moments until we heard something running through the woods just past the mound. We looked at each other, and I walked quickly, and quietly, to the look over. It was an adult Black Bear trotting quickly through the woods. I made a “be quiet” hand motion and mouthed “bear” (Dachary’s eyes got huge) because I didn’t want to bear to come over. Then I remembered all the episodes of Survivorman we’d watched in which Les was walking through the woods yelling “Hey Bear!” because the LAST thing you want to do is surprise a bear.

So I promptly started shouting out “Hey Bear!” Grabbed my keys, shoved them into the ignition, threw on my helmet, started it up and revved the engine, which I’m happy to say has a nice deep growl of a sound . I threw my gloves between my crotch and the bike, checked to make sure Dachary was on her bike, and we took off; zipped jackets and gloved hands be damned!

How close were we? The bear could have easily closed the distance between us in three seconds. How much adrenaline did we have? Just enough to cap off the day with a smile. Although the remaining miles were pretty anticlimactic.

P.S. A coworker opened her eyes wide when I related yelling “Hey Bear!” “I thought you played dead?” she said. For those of you who don’t know: No, you don’t play dead. You make lots of noise, hopefully stay out sight, and the bear will probably stay away from you. If the bear comes up to you, make yourself big, carry a big stick, and pray to your favorite deity. Unless it’s a Grizzly Bear, which you probably won’t know until the thing is pretty much on top of you. If it’s a grizzly I’m pretty sure you do the same thing, except if making noise fails, you play dead. If you play dead for a Black Bear or a Brown Bear, they’re likely to thank you for making it easy to kill you for being in their territory.

P.P.S. On a related note. Does anyone know the appropriate strategy for dealing with mountain lions or keeping them away from your camp? That’s an issue we may have to deal with in Central / South America.

P.P.P.S Afterwards Dachary was all “Why were you telling me to be quiet?!?!” because she’s smarter than me. ;)

800+ lbs of flying idiocy.

Mon, 06 Sep 2010 00:00:00 +0000

Yesterday I watched an 800 pounds of chrome, fiberglass, metal, and plastic spinning through the air. Sunlight reflected in movie-like highlights off of the long chromed pipes. The Harley did things other Harleys have only ever dreamed of… in their nightmares.

I saw the whole thing, from start to finish. Dachary only saw the grand finale of flying metal, but her brain came to the obvious conclusion: “That’s a cruiser [spinning through the air]. He was probably wearing jeans and a t-shirt.”

Let’s back up, a fraction of a second earlier.

Two “Harley guys”, out for a ride. Each wearing a Yarmulke style black skull cap (too small to deserve the title of “helmet” in my book), t-shirts and jeans. Cruising along at maybe forty miles an hour. The rear one, obviously not paying attention, gets too close to the front, and as his front tire is almost in line with his friend’s rear, does something I can’t explain. Maybe he clipped the panniers. Maybe he screwed up and hit his wheel into his friends. I’m not quite sure. But the rest was clear.

Uncontrolled front wheel wobble, followed by a lowside (when you “lay the bike down”). I watched as the left side of his torso approached the ground. Some small part of his brain told him to keep his hand up, which was good, because while his hands did have leather gloves on, I’m pretty sure they were fingerless. It’s “cooler” that way. So, he proffered his bare elbow to the gods of asphalt.

His bike was better at keeping its speed on its side than he was, but after an instant it decided that it didn’t like sliding, and figured maybe flying would hurt less, so eight hundred plus pounds of metal went from sliding on its side, uprighted itself (sideways) and lept two feet into the air, where it began it’s pirouette.

I didn’t see it come down. I was heading in the other direction on the divided road, and didn’t feel like performing a re-enactment. There was a light ahead, and I planned to turn around there to help out, because there’s a camaraderie amongst motorcyclists, and we watch out for each other, even when the others are idiots. Also, I had a first aid kit in my panniers. But, just before I got to the light, a police car passed, lights on, heading for the scene. And, as cops are way better trained at handling bleeding idiots than I am, I let them too it. Also, he probably had a better first aid kit than mine, although I wonder if his had a splint too…

Gear Up.

It is said that there are two kinds of motorcycle riders in the world. Those who have crashed, and those who haven’t crashed yet. It’s safe to say that he will have a serious scar on that elbow, and he may have mobility issues with it for the rest of his life. Depending on how the rest of him fell and if he rolled or slid there may be much a broken shoulder and much more skin ground off by the road. There’s probably a couple grand worth of damage to his bike, and his friend may never ride with him again. I know I’d be hesitant to let someone that careless ride beside me.

If he was paying attention it would have never happened. If he was wearing protective gear I honestly believe the worst he’d suffer would be a bruise and maybe a week of aching.

A note about camping while touring

Wed, 18 Aug 2010 00:00:00 +0000

On this past weekend’s test run we encountered an unexpected problem. It took us nearly two hours to break camp each morning which left us no time to relax, or have a nibble, between waking and hitting the road. On my last big trip it wasn’t like this at all. Yes, it took me nearly two hours between when I woke and when I hit the road, but that included a shower, a nibble, and lounging around reading a book. So what went wrong?

I wasn’t sure at first, but eventually it hit me. On my last big trip I was spending my nights in a one person tent. Because the number of people a tent is rated for is the number of bodies you can fit in it, barely, there was no additional space inside for much of anything. Essentially everything had to stay in the saddlebags on the bike. At the end of the tent I’d fit one one boot in each corner. Along my side i’d lay my one piece suit in one bunched up line (assuming it wasn’t wet). My camelback would go by my head for drinks in the night, and my rolled up clothes would be my pillow. My helmet would sit on a waterproof bag (to keep moisture from coming up from the ground and into the inner padding) underneath the tent’s rain flap. And, that was it.

What I didn’t realize was that because I didn’t have space for anything in the tent everything I’d used the night before had to be put away as soon as I finished with it, lest it blow away. In the mornings I’d throw on my pants, take off the fly cover, shake it out and set it in the sun to let it dry (there was always moisture on the inside of it from my breathing if not dew), grab the handful of things from inside the tent and put them by the bike, and then enjoy a leisurely read for an hour or so before throwing on my suit and heading out. It was a great start to the day.

But on this last test ride we spent two hours picking things up and packing them away. Part of the problem was that the soft luggage i was using seemed to hold slightly less every day. Even though I was packing the same items it never seemed to want to hold as many of them as the previous day. As a result, each morning some time was spent putting things in, and taking things out, trying to figure out how to make it fit again. But part of it was just time spent picking up and packing things away that didn’t need to be left unpacked the night before, and the fact that I’m not the most efficient creature on the planet just after waking.

The morning’s weren’t enjoyable at all. They were two hours of grabbing, packing, and reattaching the bags to the bike, so that, we could ride off immediately, because we were already running so late.

So, here’s my tip. Pack everything away as soon as you’re done with it. In the case of pots and bowls*, bring a small towel just for them so you can wash, dry, and immediately pack them away as soon as you’re done with dinner. If you’ll be using them again for breakfast you’ll still want to immediately address them because you don’t want them lying about to get blown around, and they take up too much space when out and about.

In the morning it’ll take you less than 10 minutes to break camp, leaving you plenty of time to sit around and enjoy the morning while your fly sheet dries in the sun, and another 5 at the end to roll up the fly sheet and the rest of the tent fabric and stick it on your bike before gearing up and taking off. * I highly recommend the GSI Pinnacle Dualist Cookset. They’ve also got a single person version.

It's only been three days...

Tue, 17 Aug 2010 00:00:00 +0000

We took a test run this weekend; seeing how the gear works for the big trip in December. It was only three days, but now I’m back, out of the shower, and about to start my morning routine. And, the truth is I feel a bit overwhelmed at the prospect. So much…. internet.

So much data. So much news. And so little of it actually matters.

I’ve already falling back into the mindset of being on the road. Just ride…. grab half way through the day and guess how far you can make it before dark. See if there’s a campground nearby ride some more. Try and find as many beautiful things to see and photograph as possible. Repeat.

I learned a lot on this test run. Not just about riding with my new partner, but about why some things worked so well on the last trip, and failed to on this one. I’ll write that all up in another post, but right now. I’m a little afraid to “jack in”… and it’s only been three days.

Why you should never indent code with spaces

Mon, 26 Jul 2010 00:00:00 +0000

Tabs vs. spaces

It’s a big back-and-forth between developers, with lots of us swearing by the use of spaces, but I’m here to explain to you why everyone who uses spaces instead of tabs for indentation is not only wrong but seriously inconsiderate of their fellow developer.

First though, we must consider what a tab is and what a space character is. A tab is a typographical element specifically designed for the indentation of text to various levels. A space is a typographical element specifically designed to separate individual characters so as to distinguish words from each other.

Next we must consider the individual coders we work with. Each of us has a personal preference about how much indentation looks good, and is most readable to our eyes. Many of us like about four spaces worth per indentation level, but some prefer two or eight. What’s important here is that what’s readable and good looking to you is almost guaranteed to not look good to someone else working in the same codebase.

When you use spaces you are misusing a typographical element to emulate one that already exists. Not only that but you are enforcing your personal aesthetic on your co-contributers. However, if you were to use a tab for each indentation level then everyone else who works in the same codebase would see each level of indentation at a depth that they prefer. Every code editor out there allows you to specify how many spaces of indentation each tab should emulate. People who like it wide can set it to eight. People who like it skinny can set it to two. Everyone gets to see the code indented in a way that is aesthetically pleasing and readable to them.

There’s only one thing worse (in this discussion) than enforcing your indentation aesthetic on your co-contributers, and that’s combining tabs and spaces. When you do that it’s almost guaranteed to look screwed up in other people’s text editors. So turn on invisible characters in your editor (or at least have it display tabs). In summary:

Tabs were invented for indentation, so stop misusing the damn space bar for something it was never intended to do.
What looks good to you doesn’t look good to everyone elese.
What’s easily readable to you isn’t easily readable to everyone else.
Everyone gets to have indentation at a level they want if you use the freaking tool that was designed to indent instead of the one that was designed to separate words.
Turn on invisible characters so you know when some idiot’s mixed tabs and spaces.

git status-report

Fri, 16 Jul 2010 00:00:00 +0000

Every week I, and millions of developers like me, have to put together a status report for our bosses, letting them know what we’ve been up to for the previous week. Like most of the developers I’ve encountered I’m always a little unsure of what *exactly* I was working on, and typically I just open up git to see what commits I made, and try to remember any non-code stuff I’ve Thinking it was silly to keep wading through everyone’s commits for the past week to see what I worked on I’ve put it all together in a script (in Ruby) called git status-report, which you can grab from github here.

It outputs a bullet list of all your commits for the past n days, or the commits of one of your fellow contributors. I think I’ll find the latter a great way to keep up on what other folks on my team are working on at the moment.

Usage: git status-report [-e <email>][-d <days>]
Generates a status report for what you worked on for the past n days.
    -a, --all                        Displays output for all contributers sorted by person
    -b, --branches <branch name>     Limit results to work found in the specified branch(es). 
                                         Multiple branches can be comma separated
    -c, --current                    Generates status report for the current repo only
    -d, --days <num days>            The number of days to generate the report for. Defaults to past 6 days (one week)
    -e, --email <email address>      The email address of the committer to generate a report for. 
                                         Defaults to your "git config user.email" address. 
                                         Multiple email addresses can be comma separated.
    -f, --files                      Display a list of files involved in the commit(s)
    -h, --help                       Displays this message
    -r, --reverse                    Displays output in reverse chronological order
    -s, --simple                     Simpler output. Doesn't include the dates
    -v, --verbose                    Verbose output includes details on each commit

Please don’t hesitate to fork the repo on github and make improvements. I’ll happily merge them in to the main one. git-status-report supports will check for commits in all the branches and supports multiple repositories. Check the README for full details.

DODOcase iPad case mod

Fri, 09 Jul 2010 00:00:00 +0000

I love my DODOcase. Money very well spent¹. Throw an iPad in it and it just looks like a big Moleskine (love that look) instead of some techy $500+ block of “steal me”. Plus, it’s about the only case out there that I feel is actually worth the $50 they all seem to cost. But, there’s one problem: nowhere to store any papers. I had to go to City Hall the other day and needed to bring some papers with me. “I’ll just fold them in half and throw them in my DODOcase.” I thought. And it worked, kind-of. The problem is, that every time you open you have to move them to use the iPad, and you’re stuck like that till you get home again and have somewhere real to put them. “If only it had an accordion pocket like the Moleskine it’s emulating.”

The next day at work I grabbed a manila folder, a pair of scissors, and some scotch tape and made one, and have been loving the results. I’m posting them here so that other DODOcase owners can do the same. Maybe the DODOcase folks will even consider adding an accordion pocket like this in future cases (only without the scotch tape ;). If so, I totally want a free one. ;) Just kidding, actually, no, not kidding. ;) When I initially made this I left the flap over the opening simply because the folder was wider than the cover, but I’ve been using it for about a week now and have come to realize that it is essential. Frequently when I open my DODOcase I remove the elastic and flip the cover around behind the iPad in one swift motion. If there wasn’t a flap there any documents held in the accordion pocked would be likely to go flying out. And yes, before you ask, because the iPad is smaller than an 8 1/2 x 11 or A4 paper you’re going to have to fold “normal” sized papers in half to fit them in the pocket. Pictures (followed by instructions):

Instructions:

Take a manila folder. Turn it so that it faces left and center it vertically on the inside of your open DODOcase’s cover.
Make a mark where the red paper stops on the top and the bottom.
fold the top and bottom edges of the folder inwards at those marks.
Close the folder with those edges folded inwards and rub the crease down with something hard.
Put the folder on your dodocase and mark on the top and bottom edges of your folder where left side of the red paper is.
Cut off the left edge of the side of the folder that is facing you from the top mark to the bottom. You may want to make a crease, or draw a line between them so you have something to follow with your scissors.
Fold a vertical crease in the far side of the folder so that it folds towards you over the edge you just made with your scissors. Crease this fold with something hard. You need it to really want to fold inwards as much as possible on its own.
Open the folder back up. You will see the edges you previously folded inwards poking up. Place tape on the far side of the left half of the bottom one so that the bottom of sticky side is half stuck to the back of the edge poking up and the top of the sticky side is facing you and not stuck to anything.
Now, mostly close the folder, and starting at the inside fold the tape over to stick to its counterpart.
Repeat for the top.
Your folder now has an accordion fold.
Tape the far top and bottom edges to your DODOcase. I used Scotch tape for this but I think I’m going to switch it to Medical tape where it’s held to the DODOcase.

Voilla. You’re done. :) Drop me a comment if you do this, or if you think of a way to make it better.

A while after this was written the bamboo started to bow inwards which prevented the corners from staying where they should and the iPad kept falling out. Eventually, I had to abandon my DODOCase. ↩︎

Mind Map of Ray Mailman's I Didn't Know

Tue, 15 Jun 2010 00:00:00 +0000

I was listening to Ray Mailman’s I Didn’t Know the other day and realized it’d make a great Mind Map. So, this morning I grabbed MindNode for the iPad, put on some headphones, and whipped this out.

Future Edit:

The song is from his Sideways album. It’s kind-of hard to find as he seems to have disappeared from the Internet in 2014, but here’s a link to it on YouTube Music.

Feed by Mira Grant [Book Review]

Sat, 05 Jun 2010 00:00:00 +0000

Feed is not about zombies. Yes, they play a significant role in the book, but the book is simply not about them. It is a gripping book about journalism and journalistic integrity.

It starts out with a dramatic zombie escape sequence, as all books involving zombies must, which honestly left me feeling… “um. ok. And?” The scene was good but it didn’t seem to have a real point beyond acting as a hook. Immediately afterwards she sets about the task of building up the world of her main characters, not a “zombie! zombie! fear! fear!” world; a world where two twenty-something siblings go about their life of being professional bloggers / journalists in a world where The Infected are an everyday part of life that has been, to varying degrees, contained.

When The Rising happened people stopped trusting traditional media, because it let them down so badly, and began to trust Bloggers who spoke the truth about the dead rising and what people needed to do to save themselves. By the time of the story Bloggers have become organized themselves into a very real and serious form of journalists categorized by the type of stories they produce: news, opinion, fiction, real-life action, etc.

Our main characters get a gig following a presidential candidate on the campaign trail, which sounds rather incongruous with a zombie book, and doesn’t make you say “oh my, this will be good!” But trust me, it is, and it gets better with every page. It’s just a matter of time before you’re stealing extra minutes in the bathroom just to see what happens next. It’s a little slow in the beginning, and some of the “clues” are discovered a bit too easily, but this is the best book I have read in a very long time.

The poignancy of the climactic scene in the van will stick with you for a long time, and you will love, and hate how it all ends.

Read this book. Read this book if you ever thought it’d be cool to be a reporter. Read this book if it bothers you that our media outlets are hamstrung by governments and over-litigious societies. Read this if it bothers you that people keep giving away their freedoms every time something scary happens. And… read this book if you like a little zombie spice in your tales.

Four out of 5 stars, only because the intro sequence left me feeling meh and the real story took a little bit to get going. You could *almost* delete the first two chapters and have a better book, but the end of the second chapter sets up some important details on how the main characters do their job.

Dear AT&T: Fuck You

Thu, 20 May 2010 00:00:00 +0000

As we all know, AT&T has been having serious issues with their quality of service thanks to the iPhone. What most people don’t know is that it isn’t a problem that can be solved by simply putting up more towers¹. But that’s not what I’m upset about. I’m upset about their handling of the “3G MicroCell”.

I live in Cambridge MA, just across the river from Boston. There are millions of people here (literally), and, like many AT&T users my calls get dropped even when outside, on bright sunny days, with five bars of service. In my house maybe eight feet from the windows I’m lucky if anyone can understand what I’m saying, or can even hear me in the first place. My girlfriend works from home, and for the most part, I don’t attempt to call her, because it’s not worth the frustration, but then I get my hopes up, call, can’t understand her, and eventually have the call dropped. But she’s just screwed if she needs to call someone on her cell. But, like I said, I’m not actually that upset about the crap service. It’s like being mad at someone with a broken leg for not being able to run. Of course, their leg was broken years ago and they still seem to be hobbling around acting as if it were fresh…

But AT&Ts handling of the 3G MicroCell is absolute bullshit. In the promo video on their web site they’ve got a guy attempting to make a phone call by holding his phone out the window, before being told by his wife that he doesn’t have to thanks to the 3G MicroCell. “So, no more leaning out of the window or standing on the porch to make a call?” the man says. Ok. You’ve got service so crappy that not only do people have tolean out their windows to use it, but you explicitly use that problem in promotional material as a reason for getting the 3G MicroCell and then you have the gall to charge $150 for the privilege of getting the coverage iPhone users are already paying at least $100 a month for? Even worse, you use our bandwidth to do it. Even worse than that, while users or the MicroCell have gone out of their way to take themselves off of your overloaded network by using the MicroCell AND giving you free bandwidth that they’re paying someone else for you’re still going to make any minutes used talking that way be removed from their account. On top of all that, if we want the privilege of getting the service we’re already paying for, and give you free bandwidth, but don’t want those minutes to count, we have to pay you another $20 a month?!

Fuck you!

Your proposal is essentially that your service is such shit that your customers should pay you $150 *and give you free bandwidth?!*And let’s not forget the option you’ve given us of paying you a recurring fee (and give you more free bandwidth) if we find that we like talking to the people we were paying you to let us talk to in the first place, now that they can actually hear us.

In what universe does this make any sense? You should be giving them away to anyone who wants them and giving people unlimited minutes for calls made on them. If your service actually worked it would be reasonable to charge for it, but it doesn’t, and it’s not reasonable for people to have to pay you to compensate for failing to give them what they’re already paying you for. This is bad economics and it is utterly disrespectful.

If all of that wasn’t bad enough. I’m probably going to have to buy the fucking piece of shit because I can’t use my fucking phone without it. If I didn’t think the iPhone was a brilliant piece of technology that I loved using I would cancel my service and pay pretty much any termination fee just to get away from you, your blatant disrespect of your customers, and your shit service. I’d go to tiny little T-mobile in a heartbeat, even though they’ve got less coverage than you, because where they have coverage it actually works, and they try and do the right thing for their customers.

Shit like this gives AT&T an even worse name than they already have, and makes me seriously consider ditching the iPhone. It will be a monolith of my hatred for AT&T. It will glare at me saying “sucker” until the day I finally cancel my contract with you and joyfully smash it to pieces with the nearest hammer.

Fuck you AT&T.

Yours truly,
- All the people you’ve been shitting on for years now.

P.S. While I have you: I already bought an iPhone from you. You’re charging me a hundred bucks a month for it. Stop trying to sell me an iPhone!

[Update]: A lot of people just don’t get why I’m so upset, and in explaining it to someone I came up with this metaphor: Why should I have to pay AT&T anything (for a MicroCell) to compensate for their failed service promise that we’ve already been paying ~$100 a month for? That’s like telling someone you’ll come cook them dinner every day (no matter where they are in the US) if they pay you $100 a month, but then you only show up occasionally, and sometimes you leave half-way through the cooking, and then you ask them to pay you an additional $150 to get you to show up, but only at their home, and only if they’ve gone out and bought all the fixings for dinner and paid someone else to make sure they can have access to the stove. Would ANYONE, EVER find that acceptable? No. You’d get fired and they’d hire a cook that actually did what they were paying them for.

With regards to putting up more towers. Someone with a good understanding of the technology described it to me like this: Imagine that you’re at a table with 4 other people all talking. With a teeny bit of effort you can listen to what any one of them is saying. You are the cell tower, and each of the other people are cell phones. Now, imagine there are a thousand people at the table. They’re all talking, they’re all within hearing range, and they’re all speaking at roughly the same volume. You’re going to have a damn hard time listening to any single one of them. It wouldn’t matter if there were fifty “towers” in the room attempting to listen to the people’s conversations because they’re all going to have the same problem. It’s just too hard to listen to a single voice in that cacophony. Other cell phone providers don’t have the same problem because they use different technologies. ↩︎

Git Rebase: why, and when, you'd use it.

Sat, 08 May 2010 00:00:00 +0000

Rebase is one of the most powerful tools in Git’s arsenal, but it can trip up people coming from centralized version control systems. This is just a quick example of why, and when, you’d want to use it.

Let’s say we’ve got a team of three developers. Monday morning they all come in, Bob makes a quick commit, and shares it with everyone. They all do a git pull and suck it into their repos.

Tuesday Mary does some work, but Bob and Tom are taking the day off and don’t pull in her changes yet.

Wednesday Tom makes a change and everyone pulls it into their repos.

Now depending on what changes Mary has made Bob and Tom may be able to pull them in without problem. Then again it could result in a conflict. But Mary’s a pro who thinks of her teammates, so she’s going to rebase her repository and reorder the commits so that her change is on top of Tom’s. Now, if Mary’s changes were such that they’d cause a conflict when Bob and Tom pulled them in then they’ll cause a conflict for Mary when she rebases, but they’re Mary’s changes so she’s the one most capable of resolving those quickly. Also, if Mary takes care of it in the rebasing then no-one else is going to have to deal with the conflict. It’s much better to have the person who wrote the change resolve it than have everyone else on the team have to deal with it.

So, Mary reorders her commits with git rebase, and if there were any conflicts she resolves them. When the others pull down her changes it’ll look like she wrote them on top of the changes they already had.

Another reason Mary might want to rebase is if she made a bunch of partial commits along the way. She might do this to give herself multiple roll-back points, or maybe she committed every time she finished working on one of the files related to the current feature she’s implementing, just so she wouldn’t have to worry about loosing anything. Now, she wouldn’t want to share those partial commits because they’d probably break something in other people’s system. So, when she finishes with her work, she uses rebase to squash the partial commits into one nice clean commit and then tells people to pull that, or maybe pushes it to some common repo they all push changes to.

Rebase is an incredibly powerful tool, but there’s one thing you must remember to never do and that’s rebase commits that have already been shared with others. For example: Git wouldn’t prevent Mary from rebasing the “Bob - Monday” commit up after all the other commits, or merge it into the commit she made on Tuesday, but doing so is guaranteed to cause problems for anyone who tries to pull from her. So rebase your own work before you set it free, but once others have it you can’t touch it.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License

If you found this useful you might be interested in some of the other git posts here.

How to Sell... Anything

Sat, 08 May 2010 00:00:00 +0000

A flow chart of How to Sell…Anything.

The $11.09 iPad typing stand

Wed, 05 May 2010 00:00:00 +0000

The Problem

When you check out the iPad at an Apple store they’re all lined up on little lucite stands with a grippy top and a slight angle so that they’re simultaneously easy to view and easy to type on. I love those stands. I’d totally buy one, but I can’t. [Update: now you can buy something even better. Check out the Loop from Griffin and their A-Frame

the goal here was to create a stand that would hold your iPad securely, would let you easily read the screen, and type comfortably on. Also, it had to not look like crap, so duct tape was specifically excluded, and this is the result.

Now, some of you aren’t really the do-it-yourself type, and would like something a bit more “professional” looking on your desk. If that sounds like you, I’d recommend you check out thisvery slick $50 iPad stand from Griffin Technologies, that supports both typing and display positions.

What went into it

1 menu stand $8.99 1 package of 7 3/4" rubber bands $1.00 2 keyrings ( 1 3/4" ) $0.80 (each) 1 mousepad $0.00 (or $4.99 at Staples)

Putting it all together

When you flip the stand over you’ll find it’s pretty floppy, but there’s a second layer of plastic folded underneath that could provide structural support, which is where the keyrings come in. The idea here is to sandwich the two layers of plastic together into one double-thick layer. You could use duct-tape but that’d be ugly. You could use super glue, but lucite tends to crack when you apply super-glue, or it did the last time I tried. I believe that duct-tape would also work quite well, but even colored duct tape would look a lot tackier, so we decided to go with keyrings. I suspect that large binder clips would work well too, just be sure to make the top flat with the top of the stand and take off the top arm of the clip after you clamp it on.

When putting on the keyrings make sure that the break in the ring faces outwards. There are two reasons for this: you want the full squeezing strength of the keyring to be covering as much of the plastic as possible, and the break will scratch the plastic if you try and pull it off (if it’s not already on the outside).

Next, the top rubber-band. Choose whatever color strikes your fancy and pull from the front to the back, then cross it in the back and go over the front again so that the unsightly x is in the back, then slide it up to the end near the bend.

Flip your mouse-pad over so that the fricative rubber bottom faces outwards and slide the top edge under the rubber band. It’s important to do this before you add the remaining rubber bands.

Next, take all the remaning rubber-bands and stretch them wide before sliding over the bottom end. Be careful! There’s a lot of force with all the rubber-bands and you can easily pinch your fingers against the edge of the lucite if you’re not careful. You won’t be able to cross them over, but that’s ok because you don’t need to. You want a nice thick pile of them to provide a lip for the bottom edge of your iPad to rest against. Congratulations, you’ve just completed your iPad stand.

If you want to get fancy try stenciling on some eyes and a nose to go with those keyring ears, and rubber-band mouth.

Hi-Per Hanger [Review]

Thu, 08 Apr 2010 00:00:00 +0000

The Hi-Per Hanger from Black And Grey

Let’s get this out of the way right off-the-bat. This, is a seventy dollar hanger. Technically it’s $30.95-$72.95 + shipping, and that is a pretty hard price-tag to swallow for a hanger. But, the real question is “is it worth it?” I’m asking from a purely practical perspective. The answer, as far as I’m concerned, is a whole hearted YES! If mine were stolen today I would go to the web site tomorrow and buy another one without hesitation.

For me it came down to the fact that standard plastic hangers were either prone to breakage, or well made but were too skinny vertically to allow me to feed my pants through with the knee armor, and hangers with standard clamps to grab the waist on your pants simply aren’t up to the task of holding on to heavy motorcycle pants. Also, normal hangers aren’t wide enough to actually make the shoulders hang on them correctly. I could put up with the latter, even though it’s not good for the garment, but i needed somewhere to hang my pants, and after spending a nearly a thousand dollars on a new Jacket and Pants (I like my bones unbroken and skin attached thank you very much) I decided that I wasn’t going to screw around with hangers that didn’t work anymore. So I crossed my fingers and placed the order for an HP-3 which is the heavy-duty base hanger with plastic shoulder pieces and two heavy-duty clamps that can either be used to grab the waist of your pants or one for each leg. You can get them with more, or fewer, clamps.

As soon as I pulled it out of the box I knew I’d received one bad-ass hanger. The aluminum hanger at the core is really heavy-duty. I could hang my full body-weight from this thing no problem. The clamps live up to all that is implied by the word “clamp” They hold on hard and require a non-trivial amount of force to squeeze open. This, is a very good thing. You won’t have to be gentle when grabbing your gear out of the closet or carrying it across the room because they will not accidentally let go of your pants. The width of the shoulders on the hanger is adjustable with a couple thumb-screws, and there are 5 holes you can use to attach the claps to via some simple thumb-screws.

With jacket hung, and pants clamped I was convinced I’d gotten a good hanger, but it wasn’t until I’d picked it up from the hook that I came to truly appreciate how important having a bad-ass hanger was. You see, it’s not that your gear weighs an exceptional amount (mine is roughly fifteen pounds) it’s that all that weight is focused on one very small point. On my body the fifteen pounds of jacket, pants, liners, and armor isn’t a big deal, but when you lift it by the hook of the hanger you realize just how much force your hanger has to withstand in order to do its job, and it’s a lot.

When you’ve been sweating in your jacket all day you’ll be really thankful for how the Hi-Per Hanger’s shoulders keep your jacket open and allow the air to flow in and dry it out. You’ll also be happy to know that they’re not warping the shape of your shoulder pads over time.

There is no question that the Hi-Per Hanger is overkill for a hanger. But, you can’t include it in the same category as other hangers. That’s like comparing an industrial dump-truck and a pick-up truck. Yes, they’ll both transport your crap, but there are some tasks the Pick-up truck simply isn’t appropriate for. Similarly, the Hi-Per hanger is designed for a specific, task that average hangers simply can’t handle well.

If you actually care about having good gear you’ve probably spent at least $500 on your suit. Spending another $70 to keep it in good shape and dry your sweat from it seems like money well spent to me. And just to be clear; I’m still not comfortable with the idea of spending that much for a hanger, but it isn’t really just a hanger. The Hi-Per Hanger is a specialized tool for for the support and maintenance of the gear you spent good money on to save your life.

If you’re still not convinced, check out the review on WebBikeWorld.

Posted via email from masukomi’s adventures

Macro Micro Checklist

Thu, 04 Mar 2010 00:00:00 +0000

A variation on my Simple Checklist Sheet.

The Macro Micro Checklist allows you to maintain a list of key deliverables, fine grained tasks, and a quick calendar of highlights for the upcoming month.

In the top left you’ve got a list of Key Deliverables. These are the high-level tasks / projects you’ve got on your plate. They may be personal things like “File Taxes” or work based things like “Deliver Example.com’s new logo”. There’s a faint dashed box you can either ignore or make a checkbox out of, and then check off the deliverable when you’ve completed it. If one of them needs to be brought to someone’s attention, needs followup, or whatever, you can just fill in the exclamation point at the end of the line.

In the top right we’ve got a circle calendar. Most people are going to be unfamiliar with these. I’d never seen one before I made one, but I doubt I’m the first one to come up with the idea. Each dot (or in this case half-circle) is a day of the week. The blue triangles give you a visual indicator for the start of each week (Monday). Saturday and Sunday’s circle’s are blue and their sections of the inner ring are grayed out. A full-page Circle Calendar is WAY more useful than a normal grid calendar for planning because each day is a further step along the ring. You actually make forward progress as you cross off days and the farther away a day is on the circle the farther away it is in time. On a traditional grid calendar the square for one week from now touches today’s square. Physical proximity has no relationship to temporal proximity. Another advantage to a Circle Calendar is that it’s got a LOT of space for you to make notes and draw lines to the appropriate day without having your lines or text go over any other days.

A smaller Circle Calendar, like this one, isn’t great for detailed planning, but neither is a small grid calendar. The idea here is to mark out important dates in the upcoming month and add any related high-level notes. As you cross out days you’ll be able to see if there is a lot of distance (time) to the next deliverable or not, and looking to the left you’ll see how many high-level deliverables still need to get done in the time remaining. Everyone’s going to use the Circle Calendar slightly differently, but that flexibility is one of the things that makes them great. When I use them I generally write in the date on each Monday’s node, as well as the date of each major event (like a code release). Then, if any of the Key Deliverables in the top left need to be completed by a particular date, I’ll just write its number in the center of the circle and draw an arrow to the day it’s due. As each day goes by I’ll put an X in it’s node to cross it out. Some people might fill in the missing half of the circle. Whatever works for you and gives you a visual indication of which days have already gone by.

The bottom of the page is just like the Simple Checklist.

See it’s post for details on how to use that and what all the boxes and exclamation points are for.

Downloads

Macro Micro Checklist: Omnigraffle, png, tiff
Stand-alone Circle Calendar: Omnigraffle, png, tiff

Three Useful Task Sheets

Fri, 05 Feb 2010 00:00:00 +0000

Almost five years ago I wrote a self organizing todo-list application. It was ugly, but worked really well. Unfortunately for me, I really prefer writing my todo lists out on paper. I like the simplicity of it, ideas just flow out through my pen. I can make notes and draw little arrows connecting things. And, I can make really satisfying check-marks in boxes when I’ve finished something.

Paper’s just the right medium for me, and I know I’m not the only one. So, I created a paper version of that self organizing todo list, and every few months I find some little thing I can do to improve it. Now I’ve got three different forms which I’ll cover below:

A Simple Checklist Sheet (OmniGraffle, png, tiff)
A Self-Prioritizing And Time-Tracking Todo list (OmniGraffle, png, tiff)
A Manager’s Planning Sheet (OmniGraffle, png, tiff)

(Why no PDF? Because the font placement is critical on some of these and Windows screws it up.)

If you find these types of forms useful be sure to check out David Seah’s excellent Printable CEO series, which inspired these so many years ago. [Update] There’s now a fourth sheet to check out too. MyMacro Micro Checklist.

A Simple Checklist Sheet

This sheet is simple and flexible enough to be useful to just about everyone.

The header has a place for the project name or some other context that connects the tasks you are working on: “Project X”, “Homework”, “Enemies of the State”… stuff like that. And, if you’re the type who keeps your tasks lists around for a while there’s a place for the beginning and ending date of the project, or maybe just the dates you started and finished the tasks on the page; whatever works best for you. I usually use it to indicate what week the tasks were for. This can be useful if you need to go back and see what you did last week for a status report.

After the header, the first thing you might notice is that everything else seems a bit faint, especially when you print it out. This is on purpose. As you can see in the example here, the lightly dashed boxes at the start of each line are there just to act as guides for your own check-boxes and practically disappear once you actually start writing. The three boxes allow for a hierarchy of tasks three levels deep, and there’s no reason you couldn’t easily draw boxes farther in if you really need it, but in practice I’ve never had the need.

At the right end of each line there are three more items in an equally faint gray: a place for a due date, a box to record the total hours spent working on it, and an exclamation point. The first two are pretty self explanatory, but they’re in a similarly faint gray so that you can just write over them if you need the space and don’t care about recording that info on the current line. I do this all the time and I’m happy to report the gray is light enough to not get in the way there either. The exclamation point is not so obvious. It’s for calling out items that you need to come back to later for whatever reason. In my case, I use it to mark items that I’ll need to discuss at the postmortem meeting we’re having the end of each release.

A Self-Prioritizing & Time Tracking Todo List

[![Task Sheet

Screenshot](http://s3.amazonaws.com/mobtvse_masukomi/assets/2010/02/task_sheet_v2_4_screenshot.jpg “Task Sheet Screenshot”)](http://s3.amazonaws.com/mobtvse_masukomi/assets/2010/02/task_sheet_v2_4_screenshot.jpg)

This one consolidates a lot of information in every line and is going to require some explanation. It is most useful for people who want a system to help prioritize tasksand want/need to keep track of the time they’ve spent working on them. The grid at the left of each row has four columns “i”, “e”, “t”, “c” for “Internal Importance”, “External Importance”, “Technical Feasibility” and “Creative Feasibility”

Internal Importance: how badly do you, or your group, want this task completed. The more you want it the more you fill up the bar.
External Importance: how badly does your client, or customer, want this task completed. The more they want it the more you fill up the bar.
Technical Feasibility: how easy will it be to actually do it. The easier it will be to do, the more you fill up the bar.
Creative Feasibility: how easy will it be to figure out what you need to do to complete this task. The easier it is to figure out the more you fill up the bar.

Some examples:

Creating a logo is creatively a pain in the butt (short “c”), but technically quite easy (full “t”). If it’s for a client it’s something externally important (full, “e”) but typically internally not very important (empty “i”). Creating a logo for your own company would be internally very important but externally not important at all.

Getting a logo design from another department is technically trivial (full “t”), creatively trivial (full “t”), and internally important important to you (mostly full “i”), but unimportant externally (empty “e”) because no-one cares that you got it from another department, they just care that you have it.

How much you put in each column is a judgment call, just fill in however much feels right. Once you’ve got them filled in you can just scan down the pending tasks for the one that’s darkest. Items that are quick and easy to get out of the way will have their right halves mostly filled in. Items that are important to get done will have their left halves filled in. Items that are quick, easy, and important will be almost entirely filled in. So, really you’ve got three ways to look at it, and none of them require much thought. The thing you should do first is the one that’s got the most black. But if you’re just looking for something you can whip out quickly when you don’t have much time to work, you can just look for something with a dark right side. Some people like to count up the number of squares they’ve filled in and then do the task with the biggest number.

Some tasks are related, or dependent upon other tasks. That’s where the little circles to the left of the grid come in to play. In the example you can see that a couple of the items have their circles drawn over and a line drawn between them. The parent task is typically the top one and the line between them shows you that they’re connected… literally.

You’ve got two lines for each task, as well as a notes space to the right for details you think up later and a big check-box you can fill in when you’ve finished the task.

Beneath the text lines there’s a blue line filled with lots of little boxes. These are for tracking how much time you spent working on each task and what day you worked on it. You’ll note that there are only four boxes per day (actually three boxes and a circle). This is for two reasons. The first being that we rarely have more than four hours a day to devote to any one task and the second being that if your tasks are taking more than four hours each you’ve probably not broken them down to sufficiently fine-grained level. The last box is a circle simply to help visually separate each day’s boxes. There are seven days worth of boxes but you’ll note that the last two (Saturday and Sunday) have faint edges. This is because you need some time off. Go have a life and endeavor to never need fill these in. It’s a little hard to see in the picture but in the example the first task was worked on for two and a half hours on Wednesday.

After the boxes you’ll see a “due / / " section were you can note a due date if the task has one.

A Managers Planning Sheet

Next up we’ve got a planning version for of that last one for manager-types. The idea is that managers will be assigning tasks at a much higher level, and the people actually working on them will divide them up into “bite-sized” pieces.

The header remains the same, but the prioritizing aspect of each task has gone away and been replaced with a due date. The hours are no longer tied to days since many tasks, at this level, will span days and are purely there for estimation purposes. You can fill in the hours boxes like a big horizontal thermometer. Alternately you can use it to estimate days. When the task is completed you can go back and fill in the “total” at the end to see how your estimates stood up against the time it actually took.

The circles to the side of each task are exactly the same as in the Self-Prioritizing version, and are for connecting related tasks.

On creating my own language

Fri, 22 Jan 2010 00:00:00 +0000

Some of you may remember that I was working on creating my own language. I wrote a creation myth in it a little over a year ago, and with the exception of a few months, I’ve been trying to make daily diary entries in it as a way of not only recording my life but practicing my language.

I didn’t create this for any grandiose reason. I simply wanted a language that would express the way I think. I wanted to play with language itself and learn more about it. And, I wanted to learn a new language. But I’m fairly honest with myself about what I can, and will, realistically accomplish. I could learn a natural language no problem, except for the lack of anyone to speak it with. More importantly, natural languages are external things. Someone else created them. The rules are someone else’s, and to speak it correctly you have to learn, and abide by those rules. But, they’re all just abstract foreign things. They’re not anything you’ve grown up with (at least not the languages I’m interested in), or anything that conforms to your brain’s view of the world. And without someone else to speak it with, it’s a lot like rote memorization. You memorize their words, their rules, and just accept them. And free writing in a natural language before you really understand the rules can lead to some very bad habits based on misunderstandings, and the words you have to look up seem fairly random. It doesn’t make a lot of sense why a word sounds the way it does, or why it means such different things¹. Reading from books isn’t very doable either until you’ve built up a fairly decent vocabulary.

But creating your own language… that’s something else entirely. You aren’t memorizing someone else’s arbitrary rules. You’re creating constructs that rules flow out of. Words can sound however you want. Take “water” for example. To me English’s “water” doesn’t sound like anything I associate with the stuff of rain, rivers, and oceans. “Water” isn’t flowing, or bubbly. It doesn’t ripple or wave. But, lelea (lay lay ah), *that* sounds like water to me. So, that’s what water is. But, being me, I didn’t just use the rule’s I’d grow up with. I’d just end up with a cypher of English if I had, and I wanted to learn. So, I gave myself a few small restrictions which would have a significant impact on what I created. Sentences would have a Verb Subject Object order, there wouldn’t be a verb “to be”, and the concepts of Yin and Yang would be an integral part of word creation: pushing and pulling, male and female. To me the world is all about the push and pull of energy, and I wanted to help myself to see it in those terms. I also wanted it to sound similar to Hawai’ian and other languages that evolved from gift cultures, with their flowing tones. That evolved into a requirement that all consonants be separated by a vowel and never come at the end of a word. Somehow I ended up with a glottal stop like Hawaiian too, although that wasn’t intentional.

With those few tiny restrictions I’ve been building something that’s seriously challenged my mind and forced me to question so much about how English works, and what I really mean what I speak. Getting rid of the verb “to be” has been the most challenging. It is so ingrained into English that learning to speak without it has really taken work. But, it’s been so worth it.

In olo ( the name of the language ) I’ve found a real sense of peace. I actively want to write in it at the end of the day; not to keep up my practice, but because the act of using it is so relaxing. If I go to bed without having written I feel like I missed out on something special, like a relaxing beer or glass of wine at the end of the day is for many.

I think a part of that may be that I keep my journals in a Moleskine, and writing on paper, in a different orthography is so removed from anything I do during the day. I believe that the different orthography is a huge factor. The act of drawing those foreign characters really does seem to affect my mind. I’m enjoying watching how those characters are evolving as my speed and comfort level increase. It’s like watching a natural language’s evolution in fast forward, because there’s no-one to make me stick with the old way. One of my characters started out looking like a “u” with a straight bar closing the top, but now the bar has remained and the “u” part has turned into a sort of attached curlicue. Writing in not only a different language, but a different orthography gives me an even greater feeling that this is *mine*… It’s something I can own as thoroughly as my own thoughts.

It’s also nice to know that in this language I can speak without reservation. If we spoke honestly with each other we’d hurt a lot of feelings. And, while most people do feel comfortable speaking honestly in their diaries, there’s always that lingering worry about what would happen if someone else came across it. But with Olo I don’t have that worry, at all. I do plan on eventually making my language reference public, but even if I did it would take enough tedious work to figure out what my diary said, that no-one would be likely to actually bother to figure out more than a few lines.

Because the vocabulary is still evolving, writing any sentence forces me to pause and question what I really mean, because so often we say things in our native tongue that aren’t really what we mean. We use idioms constantly; far more than most of us realize, but I don’t have that luxury. I’ve only three to work with in Olo (so far). We’re frequently talking around our meaning, because there’s no way to accurately express our true intent. But with your own language there’s always that option. It’s *your* language, and if there isn’t a word to express a concept you can create one, and you’re free from unintended connotations and implications. In English, for example, I could talk about “toil” but there are lots of negative connotations there. We don’t really have a word for work that you do that is simply undesirable, like washing dishes. You don’t really “toil” at washing the dishes, and it’s not really a hardship. It’s just undesirable work. A big part of most people’s lives is filled with undesirable work. In Olo, there’s a word that’s similar to “unpleasant” but without the negative connotations. It’s simply “not pleasant”. Combine that with the word for work and you can speak about work that is undesirable but not bad: pa’u hana.

If you need the ability to discuss something in a way your native tongue doesn’t adequately allow for, you can devise a way of doing it. As time goes on the rules your language accretes will make this a bit more difficult, but you’re unlikely to live long enough to make a language even a quarter as complex as English, unless you go out of your way to add complexity. But, if you, like me, are creating a language to express the way you see the world, or want to see the world, you’ll find things work out quite nicely. I’m still rather slow, and as I write more I am constantly having to coin new words which sometimes take a while to get memorize, since many of them, like “doubt” don’t come up very often. New affixes arise, and force me to go back and alter a few existing words to conform to the new rules from time to time. But, the process is wonderful, and educational in so many ways. I hope that one day I may meet someone special and she’ll be wiling to learn it with me. I think the intimacy of a private language shared only between you and your lover would be an incredible thing. I may never meet someone like that. But, even if I don’t, I’m learning so much, about language, about myself, and about the world around me.

So what’s the point? Why have I written this? I think the point was to speak about language creation, to give a little glimpse of what it can be, and what it is for me, to let some people know that it’s a legitimate option, and let others know that they are not alone in their desire to create a language. There are thousands of language creators around the world and it’s something with a long historical tradition. It’s certainly not for everyone, but what is? Conlangs have been brought into the public’s eye again with Na’vi, and learning it, like many conlangs, will provide you with a wonderful perspective on your native language. You’re also likely to find a small sense of community because it’s like joining an exclusive club for speakers only. But, creating one can give you a means of self expression you’ve probably never imagined. So many of us think with words of our native tongue, and every language has some concepts, and views of the world that it simply can’t express well, especially when you consider how tightly bound our language and culture tend to be.

Language creation is frequently a solitary act, but it can be a very rewarding one. Even if no-one else learns your language, there are many of us who will enjoy getting glimpses of it, and happily help each other with their creation. If nothing else the Conlang mailing list has proved an incredible resource for questioning English and learning about options that other languages present.

Hawaiian’s lāhai (just a random example) means: to poise aloft ( as a kite ), to leap, or a short wing fence to guide cattle to a corral. To someone who didn’t grow up with the language it seems so arbitrary, and we’ve no way to know if it is, or we’re just missing something because we haven’t grow up with it or its culture. ↩︎

Respro Foggy [first impressions]

Thu, 14 Jan 2010 00:00:00 +0000

In WebBikeWorld’s review of the HJC IS-16 helmet they pondered why there was Velcro on the inside of the chin-bar. A commenter suggested that maybe it was for a Respro Foggy. Curious as to what one was I Googled their site and was amazed at the simple brilliance of it. There is nothing fancy here. It’s just one of those head-slappingly obvious ideas that makes you wonder why no-one else has been making these.

##Summary:

Good, cheap, anti-fog device that really works.

If you live in New England or anywhere else it gets chilly you’re more than familiar with the problem of fogged visors. A pinlock system is great, but it requires getting a fancy visor which isn’t available for most helmets, or a do-it-yourself kit that involves drilling a couple holes into your visor for the pins. Not fun and particularly sucky if you’re like me, and find yourself either getting a big scratch on your visor, or having enough bugs and dirt and dust pinging off of your visor that the micro-scratches built up and you end up needing to replace it every year. Your other alternatives are Fogtech anti-fog liquid, Cat Crap anti-fog wax, pre-treated visors (which may or may not be available for your helmet), electrically heated visors (probably not available), and now, the Foggy.

Personally I think the idea of having to treat my visor with liquid, or wax and then remembering not to touch the inside is lame, and annoying because how much would it suck to pull up to your first stop-light and realize that you needed to redo the coating? Electric would work but that’s another cable to run and more power to suck from a bike that probably wasn’t designed to have the spare juice to run all your electric heating widgets.

But the Foggy… That’s an idea I can get behind. Stick it in your helmet in the fall, take it out as summer starts rolling around. The end. The principle is simple. All the hot moist air coming out of your nose and mouth gets redirected away from your visor, and thus never has a chance to fog it up. The end.

It comes in a variety of colors and is held in with hook-and-loop (Velcro(TM)) that attaches to your chin-bar and your cheek pads. It also has a plastic arch that goes over the nose to keep it fitted to your face. There’s just one little catch. While it has 3 male hook-and-loop pads it only comes with an matching adhesive-backed female hook-and-loop pad for the chin. There’s a sticker on the back of that that says “the side pieces of the Foggy(R) mask should be sandwiched between the helmet cheek pads and the chin strap.” Sounds workable, except for the fact that the side pads come across your face at about the same level as your cheekbones which is slightly above where the chin straps emerge from the padding on most full-faced motorcycle helmets. In other words, following the instructions is essentially impossible. Fortunately I noticed the “Approved for…” list of helmets on the package and I happened to own one of the brands listed (HJC) so, I set down my Scorpion, picked up the HJC and said “Oh hey, there’s Velcro on the chin-bar!” The side pieces still couldn’t fit under the chin straps but it turns out that the fabric that HJC uses is fuzzy enough that the hook-and-loop on the Foggy can attach to it. “How cool.” It’s not an incredible attachment on the sides, but I’m not worried about it falling out, especially with the real hook-and-loop in the chin-bar. The Velcro on the Foggy’s side pieces doesn’t even remotely want to stick to the lining of my Scorpion.

So, I stuck it in, put on the helmet and started adjusting it to make a good fit across my nose and cheeks. Now, before we go any farther I should point out that I’ve got a typically skinny British nose. It’s not teeny but it’s by no means large. A fairly average white-person nose. But the plastic bridge on the Foggy is is skinnier than my nose. I assume the idea is that it should gently clamp on to it to keep moist air from escaping up beside your nose. The problem is that if I put it up on the bony bridge of my nose it squeezes itself up and off a bit. If I put it below the bony bridge then it’s squeezing my nostrils, but it seems to be adjustable. So, before you insert it gently spread the arms apart and hold them there until you have a slightly wider bridge. It took a couple minutes but I eventually I found that It would sit comfortably just below the bony bridge of my nose.

Once I’d stuck it in the helmet and adjusted its placement to make a good seal on my face. I stuck my helmet outside in the 16 deg. F weather to chill for a bit. The bikes are not in riding shape this winter, but I wanted to give it a decent test. I went out, put on the helmet, inserted my glasses so I could actually see anything, and started breathing. And… nothing happened. So I breathed some more. Nothing happened. So, I breathed some more…. I breathed big heavy breaths out my nose. I breathed big heavy breaths out my mouth. Eventually, I noticed that if I looked closely the top half of my visor was slightly foggy when I was breathing out of my mouth. I started paying more attention and noticed that I could feel some of the air from my mouth escaping up between the foggy and my face, but only barely. And I’m sure that if I adjusted it I could get rid of most of that.

But, maybe it wasn’t the Foggy. Maybe it was a flawed test. I took off the helmet. I took out the foggy. I put the helmet back on. I put my glasses back on. I breathed in. I breathed out through my mouth, and was suddenly blind. My glasses were totally opaque with fog. I lowered my glasses, closed the visor again, and yup, it was nearly opaque with fog. As I was standing still with no wind neither really felt like de-fogging, but eventually they did. And yup, they fogged up when I breathed through my nose too. Not nearly as badly, but enough to remember why I bought the foggy in the first place, and enough to remind me that it really sucks to have to breath exclusively through your nose while riding.

Hell yes. But, unless you have one of the Approved Helmets listed below you may need to go to your local sewing store and buy a little bit of adhesive backed Velcro for the cheek pads. They’re £13.99 plus shipping from Respro, which ends up being roughly the same price you’d pay from KneeDraggers, except the money’s going straight to the manufacturer who has a pretty cool line of products, and, I think, deserves to be supported. Of course, it’ll take a wee bit longer to get to you from the UK. On the other hand, KneeDraggers.com said “Distributor does not provide live stock data” and “This item usually ships in 1-3 days” which usually translates to “we think it’ll go out soon but we may not actually have any”.

Overall I give the Foggy a 4 out of 5. It’s great but not absolutely perfect, and I was pretty irked by Respro leaving out the matching velcro for the cheek pads. That was just cheap corner cutting that will leave the product effectively unusable in many helmets without you running to the store to buy more velcro.

The foggy is “Approved for” Shoei, Arai, Dainese, Shark, FM, AGV, Bell, OGK, Roof, and HJC helmets.

Over 20,000 miles & 14 Countries later

Since writing this review we traveled from Boston to the Southern tip of South America. Hot, cold, humid, dry, you name it we’ve ridden through it and the Foggy held up exceptionally well for me. Dachary regularly had trouble getting it positioned correctly, and while I never had problems with it needing to be re-adjusted once inserted she frequently did. I still think it’s a fantastic device, and even though it frustrates Dachary sometimes, we haven’t found anything better.

On learning Na'vi (or any "fictional" language)

Thu, 07 Jan 2010 00:00:00 +0000

There are a number of people out there who have expressed an interest in learning Na’vi (the language spoken by the Omatikaya in Avatar ) and are getting verbally shat upon by the communities they dare to mention this in. And, I can understand the knee-jerk reaction that it’s silly to learn a language from a semi-random piece of popular fiction. But, I can also think beyond that.

Learning a language, any language, is a remarkable thing, especially in American society, and if you think about it, there is nothing more or less valid about a language that was created for a movie. Does it really matter how a language came to be? The fact is that it is a legitimate and speakable language. Koreans write in Hangul, a writing system that Sejong the Great made up from scratch less than 600 years ago. They didn’t need a writing system, they were getting by with Chinese characters. It just so happens that the Korean people seemed to agree they deserved their own writing system, so they switched, but it was no more a “real” writing system than any of the ones Tolkien created for his languages. There are two million Esperanto speakers, and maybe ten million who have studied it. It’s a conlang (constructed language) just like Elvish and Na’vi, the only difference being that it was created to bring world peace through improved communication instead of just being created for the sheer love of language.

So, should Korean’s stop using Hangul because some guy made it up? Should Esperantists throw in the towel? What about Esperantists who learned it as their first language? Esperanto, the Hangul writing system, Na’vi, and Elvish are all “fictional”. None of them existed until someone got it in their head to go create it.

…this wouldn’t have been such a remarkable case from the perspective of time - as you already have entire regions of internet clogged with Tolkienfags who struggle to master his own fictional languages despite being unable to use english properly. - Random Ass-Hole

I’m not even going to bother pointing out the grammatical errors in that statement, but the sentiment is not uncommon. The logic however, is horribly flawed. Our native tongues are things so deeply ingrained in our thinking that it isn’t possible to step outside of them and analyze them without first learning something else. Think about it. How can you possibly analyze the limitations of a language without bias when your tool for analysis is the same language which is, of course, bounded by the same limitations and biases?

Seriously? Go learn an actual language, not something from a movie. - Ignorant Jerk

Ignoring the fact that Na’vi is, in a very real sense, an “actual” language. I would argue that learning Na’vi or Klingon would be much better choices than any of the Romance Languages for someone who is interested in leaning how language itself works. This is because both of these languages go out of their way to be very un-English. English, for example, is a Subject Verb Object language. Na’vi has no such restrictions. Through the use of accusative, ergative, genetive, dative, and topic marker suffixes speakers of Na’vi are able to construct their sentences in whatever way flows best. Can you say that about English? Do you with your years of practicing English even know what those are?

“Verbs in Klingon take a prefix indicating the number and person of the subject and object, plus suffixes from nine ordered classes, plus a special suffix class called rovers. Each of the four known rovers has its own unique rule controlling its position among the suffixes in the verb. Verbs are marked for aspect, certainty, predisposition and volition, dynamic, causative, mood, negation, and honorific, and the Klingon verb has two moods: indicative and imperative. The most common word order in Klingon is Object Verb Subject, and in some cases the word order is the exact reverse of word order in English. " - Wikipedia

That’s not to say that there aren’t such significant variations amongst natural languages. Pretty much every twisted idea you can conceive of to warp a language has already been done by a natural language at some point in history. But what better way to learn your own language than to attempt to learn something so radically different from it that you are forced to question everything from word construction to sentence construction?

The naysayers

“Avatar? No, it is your idea of learning language used by in-movie characters that is disturbing, problematic and life wasting. NONE of us are bashing your fave movie.” - Random Ass-Hole

“How about, instead, you learn one of the hundreds of real languages that are in danger of dying out, and help preserve some of the collective heritage of humanity? You know, instead of wasting your time learning a language made up for a film everyone’s going to forget about?” - Clueless Ass-Hole “Please learn a dying human language if you’re going to bother learning a language at all.” - Polite, but ignorant.

Conlangers have a different take…

" I find the “languages are dying” line the most irritating thing someone can possibly say against the invention of a conlang. There is a lot of diversity of viewpoints in the conlang community, but there are certainly many of us who do care very deeply about endangered languages. Creating a new hobby language doesn’t affect natural languages any more than playing Monopoly affects the economy. Field linguists can preserve a record of the language, and members of that community can work to maintain or revive the language, but how exactly is it supposed to help endangered languages if we all stopped this conlanging business? I think that [conlangers] are probably more keenly aware than most people that language is a community activity. (This just sort of slaps you in the face when you are the only person who knows your language.) I can learn an endangered language– probably pretty imperfectly at my age – but unless I can participate meaningfully in that language’s community or spawn a new community of speakers, it’s nothing more than hobby, just like making up entirely new languages. " - M. S. Soderquist

conlangers simply are not equipped to save endangered langauges. Linguistic fieldwork requires specialized skills which most of us do not have; while many of us may be capable of writing a fairly useful grammar of a language, hardly anyone of us have experience in conducting a linguistic interview and all that. And documenting an endangered language is only the first step in preserving it; the much harder part of it is to create and maintain the social environment in which the language can flourish. That is well beyond the possibilities of most conlangers, who are merely hobbyists in linguistics. “While conlanging indeed does nothing to save endangered languages, it also does nothing to endanger languages, and most … Indeed. The survival of a language requires the existence of a community that speaks it, and a consciousness of the language’s value within that community. " - J. Rhiemeier

A language is more than a collection of words and rules. It is the repository wherein a community encodes its values and viewpoints. Very recently we have learned to read Mayan, but no-one with half a brain would suggest that anyone is capable of creating any new writings in Mayan that actually capture the Mayan viewpoint. The same goes for ancient Egyptian. Sure we can read hieroglyphs and there are definitely people who can write in it, but again, we don’t truly grok it. We’re like computers parroting back words in accordance with some pre-defined rule-set. Even if you were to bring the handful of speakers together their usage would not reflect that of the original language even if it was syntactically correct, because we simply do not think like they did. We are not capable of observing the world around us the way they did.

The only people who can truly save a dying language are people who are part of its community of native speakers. Yes, an outsider can become part of that community. You, sitting there reading this, can pick some dying language and help save it. All you have to do is travel to where it’s spoken and truly become one with its community, assuming there are enough speakers to even form a community. You’d have to give up your way of life and take up theirs if you really want to save it, because language expresses a community’s perception of the world and the reasoning behind their actions in it. And you can not express that accurately if you do not share it yourself.

Which brings us back to Na’vi. Na’vi is not a dying language. If anything it is a blossoming language. Maybe it won’t survive, but there are thousands of people waiting excitedly for enough information to truly learn to speak it, and we will create a community around it. Some have even gone to great lengths to accurately piece together its rules based on the limited information we have at the moment. And almost anyone who attempts to learn it will learn more about their native language in the process.

Does it really matter that what is bringing us together is a “fictional” language? Isn’t it more important that people are coming together to participate in a creative, and educational act? Isn’t that an order of magnitude better than just sitting at home and watching the next episode of House? Note: some names have been changed in order to better reflect the guilty.

Stop applying your agenda to Avatar (and everything else)

Tue, 29 Dec 2009 00:00:00 +0000

Over on Sociological Images Lisa evaluates Avatar(spoiler alert) Unfortunately, she’s got an agenda, and is seeing what she wants to see instead of what’s actually there.

First off, she says that the Na’vi “… are, in short, the stereotypical “noble savage.” Which as I stated in my review of Avatar, is simply false.

The Na’vi are never portrayed in the classic sense of “noble savage”. They are noble yes, but your classic “noble savage” (at least as I’ve seen it) is also, “savage”, “primitive”, and simply “doesn’t know better.” You will find none of that in this film. The Na’vi are simply an indigenous people with simpler technology than ours…

Furthermore, they have spent years being taught our modern advances and ways and have chosen to reject them. They are never portrayed as “savages”.

Lisa says that “After they win the battle, Sully assumes the role of chief, with the highest ranking female at his side.”

This is simply not true. While this may be assumed to happen after the film ends it does not happen in the film. During the film Jake always shows deference to the chief and never tries to overstep his place in the tribe (excluding trying to come back after being sent away for his perceived betrayal of them).

But Sully is not only a superior human being, he is also a superior Na’vi. After being briefly ostracized for his participation in the land grab, he tames the most violent creature in the sky, thereby proving himself to be the highest quality warrior imaginable per the Na’vi mythology.

While the last sentence is true the first is arguably false. At no point in the film does it make any claim, explicit, or implicit, that Jake (Sully) is “superior”. He’s more courageous than most, and certainly has a strong moral backbone, but that’s not superiority. He’s not stronger, faster, smarter, or more educated than anyone else in the film. He’s just a good guy with courage. And there’s nothing preventing anyone on this planet from becoming that themselves. We can identify with Jake specifically because he’s NOT superior. He’s an “average joe”.

He gives them hope, works out their strategy, and is their most-valuable-weapon in the war.

This is true, but not quite how she suggests. He does give them hope. If he is the one to work out their strategy it is never shown, and if so it proves he’s a freaking terrible strategist because he has Na’Vi on horses ride straight into machine guns instead of hiding in trees and sniping.

There’s a good look at the racial politics of Avatar here, and if you doubt the words of us white folk, you might want to ask yourself why the Native American Times seemed perfectly happy with it, or why Wes Studi lent his voice to the film. If go into this determined to see it as “liberal guilt made flesh” that’s probably what you’ll come out with, or maybe you’ll see it as “The most expensive piece of anti-American propaganda ever made.” Or maybe, you’ll just go and enjoy it as an excellent film with the simple message that the environment is worth protecting and that people unlike you are still worthy of your respect. You get out of it what you take into it.

[Update] Miller says:

I think you should mention that when Jake went after the toruk, his reasons weren’t simply to prove that he was in any way superior to them as a warrior (as Lisa more or less says) but to win back the Na’vi’s estimation of him since he had so indelibly lost it with his “betrayal” the scene previous. the only thing he was proving in that act was his sincerity in saying that he would do anything he could to win back their trust and to help save them from being wiped out. if he failed in his attempt at taming the last shadow, he would have surely died. and seeing as he had lost everything else (his position with the humans /as well as/ the Na’vi), there wasn’t anything left for him to live for anyway.

I agree.

Why tinyurl.com and its cousins are a blight upon the internet

Sun, 27 Dec 2009 00:00:00 +0000

Every web page on the internet has an URL that is a unique address (that’s why it goes in the “address” bar), and in the beginning everyone used that. But early e-mail clients kinda sucked, and some of the current ones still do, and those addresses were so long they’d wrap, or had some funky characters in them that the e-mail client wasn’t expecting, and so it’d break the URL in such a way that you’d have to copy and paste both parts of it into the address bar instead of just clicking on it.

This kinda sucked.

Then Twitter came along and said “You only get 140 characters because that’s all that’ll fit in an SMS”. And, trying to write a useful little post in under 140 characters with some big-ass url eating up a third of them really sucked.

So, people turned to tinyurl.com and it’s cousins. Because they promised short urls that saved you characters and would always be clickable in crappy email clients so long as you ignore the fine print. Fine Print? What fine print? Well, imagine, if you will, that an URL is a bridge to a distant place. A normal URL works like a normal bridge, but tinyurls…

When you cross a normal bridge you know where you’re going to end up. I never have to worry about crossing the Mississippi and finding myself in Nigeria. With a tinyurl bridge, you just might. There’s no way to tell where it goes before you get there. KinkyPornThatWillGetYouFired.com ? Could be. Oh, and the bridge doesn’t go straight to the mystery land. No, all tinyurl bridges curve through the country of tinyurl. So, if they’re having a power outage, or an earthquake, you’re not getting there today. If they experience an economic catastrophe and cease to be then no tinyurl bridge that’s ever been built will ever make it past the once powerful, but now non-existant, country of tinyurl.com and you won’t be able to get to the desired location manually because there’s no way to know where that bridge ended up. Then, there’s the problem of Google (and its cousins). Google watches every bridge that’s built, and notes where it goes. The more bridges people build to a place, the more important that place must be. But guess what? When you use a tinyurl bridge no-one can see where that bridge goes. So that place you want to spread the word about? You’re not helping it. If anyone is getting any Google-juice out of the process it’s Tinyurl.com, but I suspect the Google geeks know better than to count those urls.

Then there’s the question of longevity. Not only shouldn’t you count on tinyurl.com and it’s cousins staying around, you should count on them going away. Almost all of them are totally free services with no advertising that just cost their owners money. The more you use it, the more bandwidth they consume, and more disk space they need. No, you should definitely count on these sites going away. It’s just a matter of time. Sure, as long as there’s a need another one will probably pop up to take it’s place, but all the millions of urls that used the old one will break when it goes away.

But, what about those old fashioned long urls? When I give someone the url to this page https://weblog.masukomi.org/2009/12/27/why-tinyurl-co…n-the-internet It not only gets them to the post but it also gives them some additional information. They can tell for example that it’s from my blog ( weblog.masukomi.org ) and not some porn site. In my urls (and many other blog URLs) there’s also an indication of when it was written ( 2009/12/27 ). This is especially useful when you need current information not something that was written five years ago. You can also tell if it’s something you’ve already seen. And last, but not least, the end of the URL ( why-tinyurl-co…n-the-internet ) gives you a hint at what the article’s about.

But what about Twitter?

Yeah, I hear you. It’s easy enough to stop using URL shorteners in everything else, especially since modern e-mail clients are generally pretty good about not breaking up urls, but you need to include URLs in your tweets from time-to-time. There are two simple simple solutions and both are really easy to implement. The only problem is that Twitter has to do it.

It’s probably safe to say that Twitter’s not going to give up the 140 character limit even when all phones have gone beyond that limit for texting. Those 140 characters have become part of Twitter’s ethos. If the limit was extended much it would transform what what Twitter is and how it’s used. So, what are these solutions?

The best would be if Twitter were to set up their own tinyurl clone. [Update: they have now] There are plenty of free tinyurl implementations out there that are easy to install. You’d still have the downside of not being able to tell where the url lead to, and you wouldn’t be able to get there if Twitter was down, and if twitter went out of business they’d all stop working BUT, except for not seeing where you’re going these are all ok because if Twitter was down you wouldn’t see the tinyurl in the first place, and if Twitter went out of business the site would go away, and take all those now non-functional links with it.

If Twitter were to simply not count any characters contained in an url it would solve the problem on the web, and only require a minor code change and a simple database update. It has the downside that older phones would have trouble with the extra length and would need an url shortener, of course, if your phone is so old it can’t handle more than 140 characters then odds are you’re not going to be clicking on any links that come in a Tweet anyway.

While neither of these are hard they do both have a financial impact on a company that seems incapable of figuring out how to make any money. Storing those few extra characters may not seem like much but I assure you that they add up, and the servers and hard drives required to make them keep working under a Twitter level of load (and nigh-constant hard drive failure) would not be cheap. But, there’s a good reason for Twitter to go through the effort of fixing these. Over time the URL shortening sites will die out, and as they do millions of links in old tweets will start to break, and that makes twitter look bad. How much will it suck when most all of the links in old tweets stop working and people stop bothering or wanting to click on links in tweets because they’re so frequently broken?

Summary:

In summary, Tinyurl.com and it’s cousins are bad because:

You can’t see where the URL takes you
The URL won’t work if the tinyurl is down temporarily
The URL will break permanently when (not if) tinyurl ceases to be.
It takes longer to get to the site because you have to first detour through the Tinyurl servers (literally adding thousands, sometimes tens of thousands, of miles to every request).
You’re not helping promote the page you’re trying to spread the word about because Google can’t tell what you’re linking to.

Please note that it’s not tinyurl.com that’s specifically the problem. They’re just the most popular one. ALL of the URL shortening sites have these same problems.

Avatar [review]

Sun, 20 Dec 2009 00:00:00 +0000

I didn’t plan to write this.

I just can’t get it out of my head.

Despite the hype, despite my fear of having expectations set too high, Avatar has blown me away.

You’ve probably heard people talking about how incredible the CGI is, and it is. But that’s not important. What’s important, is that James Cameron has created a lush and beautiful world that is utterly believable. You will hear that the plot is fairly simple, even predictable. But, that’s not important either. What’s important is that you enjoy every moment of it. What’s important, is that you care about characters, and when over one hundred and fifty minutes have gone by, you just want to see it all over again. It simply does not matter that the core story arc has been used time and again. Storytellers keep using it because it’s a works, and works well.

I’ve seen some of the few negative reviews of this talk about how it’s a tale of modern people versus the “noble savage”. But the Na’vi are never portrayed in the classic sense of “noble savage”. They are noble yes, but your classic “noble savage” (at least as I’ve seen it) is also, “savage”, “primitive”, and simply “doesn’t know better.” You will find none of that in this film. The Na’vi are simply an indigenous people with simpler technology than ours, end of story. They have traditions unlike yours and mine, but the movie doesn’t tell your they’re better or worse, merely asks you to accept them for what they are and believe that they are worth protecting. The only thing they really suggest is better about the Na’vi is that they live in tune with their world while the humans have managed to wipe out all the natural beauty on theirs.

James Cameron and crew have created something that will walk away with a mound of Oscars, and deserve every one.

The editing is absolutely brilliant, astounding even. The pacing is perfect. Everything you want from a film with regards to those, it has. It is as long as it is because there was that much to show, but it never drags, and you never come across a part that, looking back, you wish they’d cut. The graphics will obviously get an Oscar, but there is no doubt in my mind that the editing deserves one too.

The CGI: the world, the creatures, the Na’vi… Incredible. You can’t tell the Na’vi don’t exist in the real world. They have pushed motion capture, especially the capture of facial movments, to a level that is indiscernable from a physical actor. I’m a geek, and as such there was always a tiny piece of me watching from that perspective, and I can remember one moment when Zoe Saldaña’s character Neytiri was speaking to Jake and the facial motions were so complex, so complete, and so perfectly rendered down to the creases of the skin, that the geek part of my brain just locked up for a minute. Some of the flora and fauna is so unlike anything on earth that it had to be CGI, but some things, like rocks… you simply couldn’t tell if it was CGI or not.

In a way it’s sad. It’s sad that the technical advances in this film are so significant, because you can’t talk about it without speaking of them, and that takes away from the film itself. Maybe when Avatar is as far behind us as the original Star Wars is, when the tech simply isn’t noteworthy by the current day’s standards. Maybe then we can have a real discussion about this film. What I can say now, is that it is absolutely worth seeing. It’s not flawless. But it does exactly what a sci-fi movie should do. It takes you to a new place, or time, it makes you feel for its characters, and leaves you wanting more.

[Update] I made a second post about some BS commentary about Avatar.

I saw a beautiful thing today.

Sun, 13 Dec 2009 00:00:00 +0000

There was a young girl, at that age when puberty hasn’t quite reached her, and everything hasn’t changed. I watched her through the window of the subway train as she buried her face into her fathers chest and hid from the cold. He was talking with another man his age and gesturing with his arms. After a moment she turned around, reached up, and put her hands around his forearms. Not to interfere. Just, to be let them hang, to touch him as he continued talking and gesturing.

I saw a beautiful thing today… a little girl, who loved her father.

Robert A Heinlein Changed My Life

Wed, 09 Dec 2009 00:00:00 +0000

Somewhere around the time I was in High School my mother introduced me to Heinlein, and one of the first things I read was A Stranger In A Strange Land. And, I think it impacted me even more than I realized at the time. I’m almost finishing rereading it now, and reflecting on some interesting paralels between the characters and myself. While I could never prove it, it seems that as I changed from a “nestling” into an adult I took on the morals of Valentine Michael Smith and combined them with Jubal Harshaw’s way of thinking.

Michael’s morals aren’t too far from the norm, with some notable exceptions, so it’s not something you’d particularly notice in me, but I do share them, for the most part, even in the exceptions. Jubal, on the other hand, had an ability that is exceedingly rare. He could think about things separately from the morals of the society he lived in. He was able to contemplate them for what they were inherently. For example, our society says that orgies are bad, but when the topic was discussed Jubal spoke of them for what they were; a group of people making each other feel good, and noted that some societies had no problem with them. Just because the morals of our society deem something “bad” doesn’t mean it actually is.

I think I learned that lesson most strongly from Jubal. He, more than anyone else, taught me to judge things for their own worth, and to not accept what “everyone knows” without question. And my ideas on religion and family have come, in no small part, from Michael’s views on the same.

The more of his novels I think about, the more influence I can see on decisions I have made in my life, and how his teachings influenced the way I think. So thank you Robert Heinlein, Valentine, Michael Smith, Jubal Harshaw, and all the other fine characters who helped to shape my life. Many authors have entertained me, and made me think, but I can only think of one that has really changed my life.

A Behaviorally Targeted Secret Santa

Mon, 07 Dec 2009 00:00:00 +0000

We’re doing an interesting variation on Secret Santa in our group this year, that you might enjoy too.

Background: we do behavioral targeting in my group. We get anonymous data about web surfers and try and try and make sure that those people are shown banner ads that are actually applicable to them, but we never know WHO, and thus…

A behaviorally targeted Secret Santa. Each participant submits a list of 3-5 items they’ve recently purchased (online or off) and are comfortable sharing to the coordinator. Then, instead of drawing names from a hat, each participant draws a an anonymous list of recent purchase with a participant number and has to try and buy a gift they think appropriate based on that for under $20.

When it’s time to exchange gifts, everyone gets together and the participant numbers on the lists are matched up with the humans and gifts are exchanged. I’m sure we’ll probably read off the items on the list we got and everyone will try and guess who’s list it was before the reveal and exchange.

I like it. I speak with a bunch of my coworkers but I’d be totally stumped as to what to get some of them. Give me a list of things they’ve recently purchased and I think I’d be able to do a pretty fair job though.

I think it’s a good idea that would work well in just about any group, and will probably result in presents that are going to be enjoyed even more by the recipients. If you try it in your group drop me a note and let me know how it went.

P.S. I’m thinking it would help if when you made your list you included links to descriptions of the items online, even if you didn’t purchase them online.

A present for my Twitter followers.

Fri, 04 Dec 2009 00:00:00 +0000

A little bit ago I got a 1" button maker and have been having lots of fun with it. So, I thought I’d make you a present. :) In order to get one all you have to do is send me a Direct Message on Twitter. If, by some chance you’re following me (@masukomi), but I’m not following you (and thus you can’t DM me) send me an e-mail at masukomi@masukomi.org. Your DM, or e-mail, must contain 2 things:

A name and street address where you want the button sent. If you want it sent to someone else let me know who to tell them it’s from.
An emotional / human adjective. E.g.: happy, angry, serene, silly, cute, erotic etc.

Rules and notes:

This offer is available to anyone who was following me on Twitter prior to 12:00 PM (noon) Eastern time on December 4th 2009. Otherwise it might spread and I’d go broke from the postage. [UPDATE: Due to underwhelming demand (six!) I am opening this up to anyone who is following me regardless of when they started, or even if they started just to get a button. I’ll cap it at the first 100 requests (assuming it ever gets that far). Also WTF is with all you people not wanting a free mystery button?! Sheesh. ]
A special exception will be made for readers of my blog who’ve contacted me via e-mail or comments in the past.
You don’t get to pick what’s on your button. It might be a photo. It might be a drawing. It might be a word, or an icon, or even a letter. The adjective you choose will influence it though.
Please note that if you choose an emotion like “angry” or “frustrated” your button might have a swear word on it. If you choose something like “erotic” it’ll probably be NSFW and I won’t guarantee what gender (or even species) will be represented. :P
I don’t guarantee delivery by Xmas (or even the next millennium) but I’ll try.

An evolutionary leap

Thu, 12 Nov 2009 00:00:00 +0000

It was, so strange… No, unbelievable.

I was sitting at my desk, typing away, when the phone rang. Hmm, I don’t recognize that number… “Kay speaking”

“Hi, I’m Random Headhunter X with Random Company Y, and I was hoping I could talk to you about a position. I know you’re not looking, but I was hoping you might know someone…”

My brain froze for a minute. I know more words followed but… did he just say what I think he just said? I rewound the conversation “…I know you’re not looking…” Yes! Yes he did! Oh… my… god! He can read! There’s a note on my home page next to the resume link. It says “NO. I am not looking for a new job. Don’t offer.” And … he read it! He read it, and understood what the words meant.

I know. I know. Some of you are thinking “so what”, but trust me, this is an incredible event. You see, until now, all observations have indicated that headhunters work on a simple form of pattern recognition. Like bees and flowers. They see the pretty color, and they zoom in to it, even if it’s just a piece of plastic. They see “Java” and their dialing finger starts an uncontrollable sequence of motions. “Rails”! *dialdialdial* In some species, the fingers are attached to e-mailing devices, but the actions are, in essence, the same.

But this one… this one seems to have made an evolutionary leap beyond simply recognizing patterns of letters, beyond words even. This one was able to grasp that words have meaning and can be placed in a specific order to generate further meaning that goes beyond that of the individual words that have been arranged.

I feel out of my depth. I feel like a child in the back yard who just witnessed a raccoon giving birth to a kitten. Who do you call about these things? Will anyone believe me?

A realization ~ Why hadn't I noticed this ~ Never a long day

Sun, 27 Sep 2009 00:00:00 +0000

I was thinking about my trip and had one of those awesome, yet so simple, realizations.

I never had a “long day” on the bike. Like many of you, I sit in my cube day in and day out, and by three o’clock on most of those days it’s already feeling long, and my brain just starts thinking about going home. But that never happened on the bike. Even when I was ridding ten hours a day I can’t remember a single day that felt “long”. Sure, on some of them my shoulder muscles were really hurting badly for hours on end, but mentally it never felt like a long day. There were boring times, and frustrating times, but never times when you were just desperate for it to end. And what an *amazing* thing that is.

Ten years ago I’d loose myself in programming; disappear for the better part of a day into code. But it’s hard for me to find projects like that any more. And I realize that even if I don’t find what I’m looking for on my next trip, I’ll have had a couple months of days that were never “too long”. Maybe more if I don’t stop riding. ;)

Looking for something

Sun, 27 Sep 2009 00:00:00 +0000

Ever since the trip was done, I’ve wanted more.

It’s not that the trip was so wonderful that I want to recapture it. It’s that in nearly six thousand miles of riding I never found what I was looking for.

I keep thinking that it was too easy. That through all of that, there was no real challenge. The roads are all pretty much perfect. There’s no real risk of running out of gas in the United States. Breaking down? So what? Grab your cell and a tow truck will be along in a couple hours at the most. Fell down and broke your leg? No worries, even if you’re out of cell phone range a car drives by every ten minutes or so. Even driving down a dirt road through the badlands that doesn’t exist on the gps, has no towns, or any good reason for being traveled I kept encountering more cars…

So, I’ve set my sights on Africa. I’m thinking of participating in the Africa Rally put on by The Adventurists. Take a totally inappropriate motorcycle from London to Cameroon. But half of that distance is across the equally unchallenging roads of Europe, so I’m thinking that when I hit the end, I’ll just continue on down until I hit South Africa. That, surely, would be a “real adventure”.

But, I wonder if, even in traveling the length of Africa, I would discover what I was looking for. I think I would love the experience, surely, and I would find a real challenge, if nothing else, but where will I be at the end of it?

Will it be enough?

I’m worried. I’m looking for something within myself, but I don’t know what.

I think I’m looking for what’s next. The next stage of my life. Will I find that on the road? Will I find someone to share it with?

[Update] I did find it on the road, and I did find someone to share it with. See Corporate Runaways for details.

Microlight Solo ~ Two weeks and change on the ground ~ Final Impressions

Sun, 20 Sep 2009 00:00:00 +0000

Quick summary

I set this tent up and took it down every day for over two weeks and thought it was excellent.

The details

I figured that camping was “the way to do it”. I’d save money, and remain a bit more in contact with the world than if i’d of stayed in motels on my trip, so I need a tent.

I hoped on my bike and drove about a hundred and fifty miles up to the L.L. Bean store in Maine. Sure I could have hopped on the subway and gone to the local R.E.I., but hey L.L. Bean’s been at this a lot longer, has a much cooler place to visit, and… road trip! And, to be fully up front. I’d read some good reviews of the L.L. Bean Microlight Solo on their site and just wanted to see one in person.

When I finally made my way to the tent section I encountered an incredibly helpful salesman, whose name I’ve totally forgotten (sorry), who confirmed my thoughts on it discussed a few of other tent options, and suggested that I get the $15 “Footprint” to go with it, but made it clear that it wasn’t a requirement, but that I’d probably want to put down a plastic bag or something under the tent if I didn’t have it to keep it from being damaged by the scratchy rocks and sticks and such I’d be compressing under myself, and to act as a moisture barrier. I think it was worth every penny. But first, the tent itself.

This is, unquestionably, a one-man tent. As in, one person who’s in shape. If you’re… “generously padded” this is NOT the tent for you. Two thin people could probably fit if they were willing to lay on their sides and spoon each other. Also, because of the shape you can only sit up just inside the doorway. I’m 5'9" and I didn’t have any problems with this, although I did occasionally brush my head when placing or removing anything from down by my feet, or if I sat up in my sleeping bag I’d have to scoot back towards the entrance.

This small size is actually one of the reasons I chose the tent. Small size means less material, a smaller bag, and less weight; all things which are critical on a motorcycle trip. When I first got it home I attempted to set it up in my living room just to get a feel for it, but having not set up a tent in well over fifteen years I was rather surprised at how dramatically tent-tech has changed. First off, it’s not a free-standing tent. It simply won’t stay erected if you don’t pound in the tent-pegs. This isn’t a bad thing for most of North America, it just means no living room test-runs, sand and snow would probably be quite difficult without specialized tent pegs, and you definitely can’t set it up on a large flat rock. You’ll need soil. There are two poles, which are made from tubes of aluminum with an elastic cord run through them to keep them together, and help them snap easily into place as you’re combining them into one long tube; an act that takes about five seconds. Unlike the tents of yesteryear you don’t bend them slightly to fit through some straps on the tent. No, you stick one end through a grommet in the tent, then bend it far beyond anything that seems sensible, until the other end finally approaches the grommet on the opposite side of the tent. Then, you do the same thing for the other pole. It’s not hard, it’s just a bit disturbing to someone who isn’t used to this new world order.

Then, you lift up one of the poles, pull a series of plastic hooks over it, pound in a peg or two, and repeat at the other end. I found the easiest way to do it was to erect one pole, push in one tent peg, then step on, or press far side of the tent down while you grab and lift the other pole. Once you’ve got the far one lifted pound in the diagonally opposite tent peg. Congratulations you’ve just done the bare minimum required to raise this tent. I wouldn’t recommend stopping there but it’s pretty impressive that with two tent pegs you’ve got your tent up. A little floppy at the unpegged corners but hey…. Then just move around the tent putting in the rest of the pegs. The footprint matches the base of the tent exactly, has its own grommets that the poles also go through, and some loops for the tent pegs to pass through directly under the ones for the tent.

Once you’ve done that you now have a mosquito netting tent up with a waterproof base and a full view of the world. If you’d like some privacy, or expect rain, throw the rain fly over it and shove in a couple pegs. The rain fly also creates a little alcove in front of the door under which you can set things you want out of sight, or protected from the rain, but don’t want in the main body of the tent. There is a gap between the netting and the rain fly and this is a very important feature. Your body heat is going to cause condensation to form on the inside of any tent (assuming there’s water in the air to condense) but in a tent like this it forms on the rain fly which won’t end up getting you or your gear wet because of the gap. It simply forms on and runs down the inside of the fly to the ground without ever touching you. Unfortunately the fly tended to sag slightly between the two poles so there was about eight square inches of space in the middle of the tent where they did make contact. This was never a problem even on the most dewey of mornings but it shouldn’t have been happening. Casually putting up the tent, while pausing to listen to the insects and look at pretty views still took less than 8 minutes from start to finish, including putting all my stuff in it after it was up.

The slight sag of the rain fly was most likely because of the one badly designed element of the tent. At the foot end of the rain fly are two pieces of webbing. Each has a loop at the end for a tent peg to go through and runs through a plastic length adjuster thing. The problem is that no matter how much you shortened the adjuster never held it. I ended up looping the webbing around the adjuster and that was almost the right length. While certain parts of the fly get their own tent pegs there were no pegs for these so you had to put the end loop over one of the pegs used for the base. This would have worked perfectly if the adjusters worked, but they didn’t so it didn’t pull with quite enough tension on the top and you end up with that little sag in the middle. So, if you do get this tent my recommendation would be to purchase two more of the thin aluminum tent pegs that this tent uses. Then you can just put them at the end of the webbing and pull it as taught as you need to.

Space and Comfort

I am 5'9" tall and about 145 lbs. I had enough space for me, my one piece riding suit down along my side, my Camelbak M.U.L.E NV on one side of my head, my walking shoes and assorted other small junk by the other side (flashlight, iPhone, a small tupperware of food, etc), a pillow (actually my pants and high-vis vest rolled up), my full-face motorcycle helmet to the left of my feet and my riding boots to the right of my feet. My glasses went in one of the two mesh pockets that are right by your hands when you lay down and seem designed for just such a usage. Those pockets were a perfect little touch. After taking my sleeping bag out of the dry-sack I’d stick it in the alcove (it had a book, notebooks, and an emergency set of dry clothes still in it) and have space on the other side of the alcove that I pretty much never used.

The comfort was fine. It was wide enough that you could curl into a fetal position without trouble and laying there in the morning watching the silhouettes of leaf shadows on the rain fly was nice. You didn’t feel cramped in there. However, I would note that owing to the fact you can only sit up by the doorway you really wouldn’t want to be stuck in there hiding from the rain all day. That wasn’t a concern for me since I ride rain or shine. Also, obviously, this tent is not for anyone who is claustrophobic.

Tear-Down tip

The rain fly is made of some incredibly slippery parachute fabric. When you roll it up it’s really difficult to get it to stay rolled up nicely as you’re trying to get it in the bag. It just wants to slide out of itself. The solution I found was to roll up the tent (mosquito netting and base) so that you have a rectangle slightly shorter than the bag and about half again as wide with the base out. do the same for the rain fly, then fold that in half again and stick it on top of the base. Then roll the base around the rain fly so that when you’re holding it with one hand there is only the base material exposed to your hand to grip.

For the Footprint: fold it into a rectangle as tall as the bag and whatever width, then roll.

Main points:

Extremely light-weight and compact when packed up. I could easily roll it up smaller than the bag it lived in and there was plenty of space in there for the pegs, poles, and the footprint.
So easy to put up you can do it in the dark. If you’re familiar with how all the pieces go together. I did it once in the pitch black since dealing with the flashlight too was distracting, and a couple times as I raced the last rays of sunlight.
Enough space for you, some gear around your head, and some by your feet.
Get the Footprint. It’s worth the $15 for the convenience of all its perfectly placed connectors, folds up very small and can fit in the tent bag.
Buy two additional thin tent pegs to compensate for the bad adjusters on the rear of the rain fly.

Assorted notes

I’ve taken the tent down in a strong wind. I was very surprised to find that it wasn’t a hassle at all. There’s simply not enough fabric for it to be a big deal.
Owing to extenuating circumstances I never actually used it in the rain, but according to the reviews on the site it performs excellently. I would not doubt this in the least.
There’s some velcro on the outside of the rain-fly along the zipper. I am not sold on this. I’m sure they put it there because of some wind issue but whatever their decision was it never became apparent to me and occasionally gave me a trivial amount of annoyance when dealing with the zipper. This is totally nit-picking I admit.
The elastic cord through the tent pole sections really made them trivial to put together. You could almostgrab one end, wave it in the air and listen to the pieces snap snap snap into place… almost. In reality you can do it with your eyes closed, or better yet, while paying attention to the beautiful scenery you’ve found yourself in. Taking them apart is just as easy.

I almost Forgot ~ Buffs make everything better ~ Great comfort item

Thu, 17 Sep 2009 00:00:00 +0000

So, In my list of items in my kit ( http://masukomi.posterous.com/write-up-on-my-kit-the-things-that-worked-and ) I totally forgot to mention my Buffs. This is most likely due to the fact that I wear them every day anyway so I don’t really think about them much.

One around the neck. Kept it from getting to chilly and I hate the feeling of those tiny bugs that seem to manage to ping off your throat from time to time. 70 mph mosquito impact on an exposed throat is not a pleasant feeling. On the cold wet day when I was driving through a cloud I swapped it for a polar buff. As expected, it was perfect.

One over my hair, well, most of my hair. It kept stray strands from sneaking out and annoying my eyes when I put the helmet on, or while driving down the road. Also, made it possible to move in the tiny one-skinny-person tent, because without one my nearly waist-length hair would have been totally obscuring my vision and getting under my hands, and generally being a pain in the ass. When I road the bottom of my hair was shoved down into my suit because if I leave it out in the wind it instantly turns into a mass of knots, and I forgot to pack my brush.

Yes, it’s one of those inventions that seems “duh”, but so is the nail, and yet somehow they’re both still awesome.

http://www.buffwear.com/

http://twitter.com/BuffLife

I think I might get a Typhoon Buff for the next adventure…

Posted via email from masukomi’s posterous

Write-up on my kit ~ The things that worked and didn't. ~ What I'll change next time.

Thu, 17 Sep 2009 00:00:00 +0000

Some of you, mostly the motorcycle geeks reading this, will be curious about the kit I used on the trip, what worked, and what didn’t.

I laid out the initial batch of it with detailed notes on flickr (click the image to go to flickr and see the notes) There were a number of items added afterwards.

What worked:

The iPhone was wicked useful but I had no service, or no data service for so much of the time that the built in map app was useless and I ended up buying the TomTom app since it keeps all its maps locally. The battery life was fairly sucky though, and the video capture is totally useless when mounted to a bike. The vibrations make the picture look like it was shot from within a running front-load washing machine. Listening to audio-books on it rocked, especially when driving through mile after mile of corn and in those hours when the sun has set, so you can’t see anything, but you’re not tired yet.
The L.L. Bean Microlight Solo tent was superb. So well designed that I was able to put it together in the dark the first time out in the wild. I didn’t end up using it in the rain, but i think setting up, or tearing down, any tent in the rain must suck. At least tearing this one down can be done pretty quickly, and I did do that in strong winds hoping to beat an approaching storm.
The $2 net from bikebandit.com held everything down but would have been mediocre at best if not for the Carabiners.
The 5 Carabiners were an excellent addition to the kit. 1 at each of the front corners of the net, plus one one each side to give it a redundant attachment to the saddlebags and to go through the loops at the end of the tent bag and the dry bag, so that even if the net came loose somehow (it didn’t) the things it held down wouldn’t go flying. For a while I put one through the handle of the gas can to attach it to the net but I came up with a different solution later. They also acted as a simple thing to hang my helmet from when I went into some place to eat. I used the locking one for that to make it a bit more difficult for a would-be thief.
The wind-up flashlight was awesome and surprisingly bright.
Sea To Summit Evac Dry Sac ( http://www.seatosummit.com/products/display/64 ) I got the 35 liter one and kept my sleeping bag in it. As the trip went on more things started living there too. The clipped loop at the top went through a carabiner to be sure it couldn’t fly off even if I lost my net.
Spork! I got it because it was neat. It turned out to be totally useful. It’s not obvious from the pics but one of the fork end’s tines has a serrated edge to use as a knife. http://lightmyfireusa.com/spork.html
Swiss Army Knife. One of those nice fat ones.
Reusable ear plugs were great. Far better than the foam ones since you don’t have to stand around waiting for them to expand in your ears and then re-attempt if there’s still a gap. I knew this before but using them that frequently really convinces you of the advantage.
Odwala Bars were great. I wish I could have found more when I finally ran out. Cheap, not overly sweet, and I liked most of the flavors.
Medium bicycle hand-pump was excellent. About 20 pumps per pound of air pressure. I rarely had to put in more than a few pounds per tire. Don’t forget that air expands as you go up in altitude. Was letting air out as I approached Colorado, then putting it back in as I made my way from it.
Fieldsheer Highland II suit. I thought I’d boil in it. Most of the time though, even in 80+ degree weather, I had it zipped up all the way with just the air vents open. In Wyoming i even put in the winter liner. It was about 53 degrees and I was riding through the bowels of a cloud at 70+Mph. Only real complaint was that the left knee pad on mine is positioned too far to the right so it wouldn’t really help me in a crash. https://weblog.masukomi.org/2008/05/03/fieldsheer-highland-ii-review
The CamelBak Mule NV was excellent. The built in rain-cover worked perfectly and having the water on my back available whenever I felt like it made an amazing difference. It was also really nice to be able to reach over and grab the tube to get a drink of water from it in the middle of the night. I did have some complaints related to it on the trip but they weren’t really failings of the Camelback. The discomfort was more due to bike ergonomics, personal muscle weirdness, and the weight of the water but there’s nothing you can do about water weighing what it weighs. A camelback tank-bag would be awesome. I’ve only seen one (knock-off brand) and it didn’t look good.
Zip-lock disposable tupperware thing (sandwich sized). I’d stick my leftovers in this, and throw them in my CamelBak. Don’t think I bought dinner once the entire trip thanks to this.
Scala Rider Q2. It took a lot of fiddling over many days before I finally got the speakers exactly against my ears but once I finally did it was excellent. You’d have that problem with any set though. I played mp3s through it with the bluetooth paired to my phone and in standby for 3 full days (8-10 hours each) of riding on one charge and it still had juice. People seem to be able to understand me just fine on it when they call, although they seem oddly reluctant to call me if they know I’m on the bike, which is sad. I would have liked to hear from them.
Pamprin. Nothing kills headaches better. Although staying hydrated meant headaches really weren’t a problem. Pretty much only needed it when suffering from altitude sickness as I came in to Colorado.
REI sleeping bag. it was rated for 35 degrees Fahrenheit but, sleeping naked in it, I got chilly, but not cold, in the mid forties and low fifties. I wish there was some standard way sleeping-bag temperatures were rated. I wouldn’t have been chilly if i was wearing anything though. On warm nights it was a bit too much and I ended up oscillating between too hot and too cool, trying to figure out just how much of your body to leave exposed to balance out the heat from the covered bits, which was complicated by not having a pad under it which limited the number of comfortable positions.
The Tour Master boot covers worked great, but I lost one, bought a replacement pair, and then found the one I thought I’d lost.

Things I never used but was glad to have:

Tire repair kit.
Small roll of Duct Tape
First Aid kit. I’ll be replacing it with a soft bag next time though. The hard plastic was obnoxiously inflexible when I needed to shove it in or pull it out of my bags to get to other things.
Jumper cables
Siphon
Umbrella

Things I’m unsure about the value of:

Tie Downs. http://www.bikebandit.com/bikebandit-com-premium-tie-downs-with-soft-tie-loop-pair Theoretically these would have been useful if I’d needed to throw it into someone’s truck bed, or maybe if it fell down a big ditch or got stuck somehow I could have attached them to the bike and a tree and used the little ratchet to help pull it up. Theoretically…
The moleskines got soaked. New rule: all paper products must live in a dry bag. Even so, I tended to not stop riding until sunset so I didn’t really have any time to use them before it was dark.
More than 2 changes of clothes. The extra socks were great, but I think I enjoy fresh socks more than most. Really though I only wore 2 shirts the whole time because I was smelly anyway and it’s not like anyone saw i’d been wearing the same shirt for a week. If I got a chance to shower at night I’d just wear the one i had on and soap it up and rinse it out before taking it off and cleaning me. Leave it to dry for morning. The drying by morning didn’t always pan out.
iPhone RAM mount. I got it thinking i’d take video while driving. As mentioned the vibrations made that unworkable (not the mount’s fault). It’s decent if you’re going to use your iphone as a GPS but if you do that you better have somewhere to plug in the phone. Plus you can’t work an iPhone with gloves on, and you don’t want to leave it there if it’s raining. Mostly, I didn’t use the mount and just kept the phone in my pocket so there wasn’t a cord going out between me and the bike. The mount was well made but ultimately kind-of useless for an iPhone. Maybe I’ll get a camera base for it instead.

Meh

Winter Gloves. I thought I might need them in the rockies. I never used them. I guess it depends where you’re going and when.

Things I wish I’d had:

One of those helmets with a clear visor but a slide-up tinted layer. A couple times I ended up riding past sunset and it just wasn’t worth digging out the clear visor and swapping it so I just rode with the tinted visor opened up. Or, maybe a dual-sport helmet with one of those over-hanging sun-visors that dirt-bike helmets all have.
Somewhere on the bike to plug in the phone.
A real GPS system. TomTom Rider or, better yet, Garmin Zumo.
Somewhere on the bike to plug in a gps.
V.O.I. POV Helmet Camera. http://www.vio-pov.com/ I am definitely getting one for my next adventure. I think it’s the only good camera like it with an audio-in so you can have a real mic instead of just recording wind-noise like most of them do.
One of those rolls of foam padding for under your sleeping bag. Or, better yet, one of those ones that folds into a 3D rectangle and has an egg-carton like texture. Definitely getting one of those for next time too. Sometimes the ground is freaking uncomfortable. I don’t trust air mattress and you’d waste time filling and emptying them every day
zip-ties. I didn’t end up needing them but I think they’d be a really good thing to have.
A companion.

Things that didn’t work:

Fieldsheer Expander Saddlebags. There weren’t many options that would work on my bike. These sagged a little farther every day and let everything in them get damp. The rain covers are a joke. They will try and fly off at the first opportunity. The stitching along the main zipper started to come undone on one of them after a few days, and that was the side with less stuff in it. The way the zipper opens is really annoying because it well… doesn’t really. I mean, the zipper works, and there’s an opening, but it’s like trying to pack a suitcase through the end of a manilla envelope. Also, it’s not at all obvious what they expect you to do with some of the pieces it comes with, they don’t provide a manual, and when I e-mailed them the pdf manual they sent me was only semi-helpful. Also, it was missing one rain-cover when it came from the factory, which turned out to be not much of a loss since they don’t want to stay on anyway. Fieldsheer did end up sending me a replacement for the missing one though. So, yay customer service. Also, while it was easy to lock them to my bike via a bicycle cable-lock, and I rarely needed to take them off, I never felt my belongings were really safe from prying hands (not that there were any). Next time I’m going with aluminum panniers. It just wasn’t an option on this bike though. To be honest, the saddlebags didn’t suck. They were mediocre. If I had to use them again I’d put down a piece of hard plastic across the bottom to keep them from sagging in the middle.
Trailer Life Directory RV Road Atlas. The map indicates what towns have campgrounds / rv parks near them, but then you have to go to the index in the back to see what’s there, and there’s no phone number, address or anything else for any of them. So, you know they’re around there somewhere but that’s about it. Without the iPhone to look them up i’d have been screwed. Also, pages started falling out the second time I opened it, in the end I decided that was a good thing because I just started ripping out the page(s) for the current day’s state(s) in the morning. And it is unexpectedly huge. God what a piece of crap.
Energizer Energi to go iPod charger. Totally useless piece of crap. Maybe it works better on iPods, but it’s crap with an iPhone 3Gs. It would charge for a minute, then the voltage seemed to fluctuate and the phone would claim it was incompatible, then it would charge, then it wouldn’t. Each time it switched to wouldn’t it would wake the phone and waste it’s battery. It drained more power than it gave. Only worked well once.
The Aerostar GP Plus gloves stayed at home, and I’m about to put them on Craigslist. I thought they’d become more comfortable once I broke them in, and while they did slightly, they were never comfortable enough for a long ride. Instead I went with my no-name “Backup Gloves” which are just leather, some foam padding across the knuckles and kevlar across the palm. They’re no good at dampening vibration, and after riding through the pouring rain I was able to clench my fists and watch a stream of water squeeze forth from each one.
Unable to find some overgloves I got a pair of Joe Rocket Ballistic 6.0 waterproof gloves which I ended up hating. They had an inner glove that was essentially free floating and would bunch up at the finger tips, and make it hard to get your fingers to slide into the right holes when putting it on, and a nightmare if your hands were already damp. To make matters worse, they only kept me mostly dry. My hands still ended up feeling slightly damp.
Aerostar GP Plus gloves. Too uncomfortable. Left them at home
Knox Gilete Air back protector. Too bulky. Would have been a pain in the butt, hot, and unpackable. Went with the CE back armor built into my suit instead.

Things I’ll do differently next time:

Two Piece suit instead of a one piece. I’m thinking about the Aerostitch Darien.
Metal Panniers instead of textile.
More waterproofing (dry sacks inside the panniers probably).
Take the time to wire in some sort of power outlet if the bike doesn’t have one.
Get a Garmin GPS.
Get a different bike.
Get a better map.
Get better gloves (and some waterproof overgloves).
Find a bigger challenge. Africa’s looking better by the day.
Find a companion… I hope.

Curious about what worked and what didn’t in my trip from Boston to the southern tip of South America? We put together a huge gear review after that trip too.

The unexpected: ~ Sometimes it is a grand thing ~ Sometimes it's simple

Tue, 15 Sep 2009 00:00:00 +0000

I thought it would be a Grand Adventure. Something I would return from with tales of interesting events and intriguing sights. But it wasn’t like that at all. In fact, there wasn’t a whole lot to report on, on a day to day basis. I’d kind-of bemoaned that about Lois Price’s books. I enjoyed them, but it felt a bit like she’d left out so much. She’d cross entire countries only mentioning their existence in passing. “How could she leave out so much?!” I thought. It just doesn’t make any sense until you have a long adventure of your own that you understand. It’s the simple fact, that for the most part, not much happens on a motorcycle adventure, at least, not while things are going according to plan.

It’s not that they’re boring, or uninteresting. It’s just that, unless something goes wrong, the vast majority of the time you spend on one is spent sitting in a saddle watching the landscape go by. I rode over mountains, through canyons, and clouds, and buffalo. And while I took lots of pictures of many the many interesting things, in the end, they’re essentially a collection of landscapes.

For a while now I’ve been intrigued by the adventures put on by The Adventurists ( http://www.theadventurists.com ). One thing they emphasize on all of them is using vehicles that are wholly inappropriate for the task, and providing absolutely no support should your vehicle break down. On the page for their Rickshaw Run they write, “Support? Of course we don’t provide any support. The Rickshaw Run is supposed to be an adventure. What sort of adventure would you have if we were following you in a truck with spare parts and a comfy bed. No, no we must get out there into the world and get stuck in. When you’re stuck, lost, and up a certain creek without a rowing implement is when you start to have fun - and the last thing we want to do is stop you having fun! If you want a full support crew there’s a very nice place called Butlins based in Bognor Regis.”

What I’ve learned now, is that they are 100% correct. I look back at my journey and realize that the most “interesting” parts of it, when I was actually faced with serious choices and events, were when things went wrong, or when things were anything but smooth. I loved taking my absurdly laden street bike up a dirt road through the rockies at elevations far above my carburetor’s tuning, with the very serious possibility, and near instance, of being crushed between truck and stone as they came flying around a blind canyon curves with no room to spare, or falling over the side of the cliff to my doom, but that just proves their point.

I loved going through the Black Hills National Park. I was astounded by the beauty of it, but I’ll never forget riding through the middle of three buffalo herds on a motorcycle that always put them on edge, or seeing one running in a direction that seemed to be very much towards me. I loved the Badlands, but it was made forty times better by the fact that I could barely keep my bike upright at times on the very gravely road, that I had to ride most of it in the wrong lane, and when a car came towards me I had to slow to a near stop to cross over the eight inch mounds of loose gravel that my street tires were woefully unequipped to handle.

I loved driving a hundred and fifty miles through empty lands and towns so small that the idea of anything as useful as a gas station was absolutely laughable, wondering if it would see a gas station before I ran out, thinking gratefully about that spare gallon and a half strapped to the rear seat.

I look back at Lois’s books now and understand why they’re the way they are, because while I may have ridden through nearly four thousand miles of farmland there’s not a lot to tell you about it. How much does anyone want to hear about four thousand miles of corn, sunflowers, and random green things I can’t identify? Kansas was great, but the most noteworthy moment was when I pulled off the road to eat lunch near some grain silos, and watched two men come out from them to watch me eating a few hundred yards away.

But, you can’t leave it at that. To do so would imply that more mundane bits spent riding between the complications are somehow unimportant, or not worth the time. But it is. I wrote before about how your motorcycle becomes home ( http://masukomi.posterous.com/today-was-the-last-it-started-off-in-a-cloud ) in a very real sense, not just because you have nowhere else to go. There’s something incredible about climbing onto a saddle that’s also your home and setting off on unknown roads. Especially on a motorcycle.

Ted Simon, who wrote Jupiter’s Travels, said “I think the motorcycle is best because it puts you so much more in contact with everything. You experience much more closely the nature of the terrain and can almost taste the cultures that you’re riding through. Because it exposes you to the climate and to the wind and rain it’s a much more complete experience.”

I’ve quoted that before, but it’s just so true. I think my trip through Wyoming’s plains might have been pretty boring in a car. But, there’s just such a huge difference between passing a curious windmill and passing a curious windmill after having felt that same wind pushing against you for hours. Racing towards the silhouetted edge of the cloud that is itself racing along the road is neat, but doing it after riding through the heart of its brother with water condensing and dripping from every exposed surface, after feeling the chill wind that’s blowing thirty five miles an hour against you, the windmill, and the cloud you’re racing, and knowing that when you reach that edge you’ll feel the sunlight again. Laughing with joy when you finally do… Laughing because it’s so suddenly warm, laughing because you raced a cloud, laughing because a tumbleweed suddenly blew across your path, something you’d only ever seen in Road-Runner cartoons and Western movies. “Tumbleweeds don’t really go rolling across the road in front of you.”, you thought.

I loved sleeping in a tent, listening to the cicadas as I set it up, and noticing they’d all gone quiet, but that the chorus of insects was picked up by others and still going strong as I went to sleep wondering if any of the ants that had scampered around as I pounded in tent pegs would find a way in. Doing so wasn’t just the cheap option. It was the *right* option. To have used a motel every night would have left me so cut off from the world; as if the adventure were some safe video game that you could turn off at the end of the day. Even the sterilized campgrounds with their precisely laid out RV spots and electric hook ups felt wrong. I kept thinking of Wan, ( http://totalruckus.com/phpBB2/viewtopic.php?t=12143 ) a Korean guy who came to the US, bought a little 50cc scooter and circumnavigated the lower 48 states, finding places to hide his tent, when he wasn’t shacking up with strangers from a message board. I kept thinking that if my bike wasn’t neon green and was either light enough to be carried when stuck, like his, or capable of real off-roading, I would have totally done some sneak-camping too.

I loved going three days with no electricity, every night trying to figure out how to keep my iPhone going one more day so that I’d be able to check the GPS if I needed to, something which would drain the battery in an hour and a half, or record my nearly daily audio posts for you.

And there was something liberating about loosing my map in Iowa, and awesome about not knowing what day it was, and later finding you were two days off, and not knowing what state you’re in, checking the map later and discovering you’d passed through three states in a day. I loved how, at the end of almost every day, I’d find myself checking the sun to see how far it was from the horizon, learning just how low it could get before I’d be setting up camp in the dark again. “Come on… Come on…. I’m not going to make it…. shit I’m not going to make it. Oh look, a campground sign! Turn! Turn!”

I learned a lot this trip. It wasn’t the life changing experience I’d dreamed of, but It ended up being the practice adventure I’d hoped for. Incredibly informative, but relatively easy. Too easy to stand on it’s own maybe. Like a bike with training wheels. It gets you from point A to B and you’re excited to be going, but you’re not *really* riding until you take those training wheels off. Now I know that The Adventurists are right. “When you’re stuck, lost, and up a certain creek without a rowing implement is when you start to have fun”. The United States are, honestly, a bit too safe. You have to work at it to worry about gas, and I can’t remember a road I didn’t encounter someone on fairly regularly. To make it exciting here you have to work at it: take the Trans-America Trail ( http://www.transamtrail.com/ ), or make it a real challenge and take a tiny little 50cc bike like Wan. It’s not at all surprising that when you watch Long Way ‘Round America, while over 3,000 miles from Alaska to New York is one of the shortest and least interesting pieces of the show.

If that sounds anti-climactic it is, but don’t take that to mean I didn’t have fun, that I didn’t shout a hearty “Hello Cow!” as I passed our four footed cousins who raised their heads to watch me, that I didn’t grin from ear to ear when I saw the Prairie Dog warning, and remember them scampering ten feet from my wheels as I drove past a family of them two states ago.

Or that I even the simplest moments of beauty didn’t make me think about higher powers.

Don’t think for a moment that I would trade a moment of it for the comforts and safety of my home, if anything I regret not going all the way to California. And know that if this has had any impact on my life it has been to show me that the things I want so desperately in my life are just waiting for me to come and join them.

So, who feels like riding to Mongolia with me? Cameroon?

Posted via email from masukomi’s posterous

First there was the pic ~ with mention of a story ~ Now you have the words.

Mon, 14 Sep 2009 00:00:00 +0000

It started with a thwapping on my left foot.

Thwap

Like a thick cloth being whipped heavily across my boot.

Thwap

“But, There’s no cloth in front of my foot…” I think.

Thwap

I’m imagining some impossible piece of canvas beating in the wind, occasionally swinging around to slap across my laces.

I look down. There’s a grasshopper IN my shoelaces, its whole body wedged under them against the tongue of my boot.

“I have GOT to take a picture of THAT.” I think. “It’s not going anywhere. I’ll do it when I pull over.”

Thwap

This time it’s the right foot.

Thwap
Thwap

Thwap

I lost count eventually. A hundred? A hundred-fifty?

Thwap

I never saw them. I just felt them. Thwapping against my feet. It became a sad running joke. Invisible grasshoppers jumping to their doom.

I thought that would be the worst of it. Them, the few hundred small flying things that converted themselves into little piles of winged meat on my visor, and the occasional large flying thing which bounced off or exploded into a large yellow stain across my eyes. I wondered why bug guts were always yellow, until I finally hit a mosquito on its way home from a meal. It left a small red splotch that looked remarkably like a Scottish Terrier. I had at least a hundred miles to ponder its shape before walking over to the gas station squeegie and attacking my helmeted head for the third time that day.

Unfortunately that wasn’t the worst of it. I killed a lot of things in South Dakota, but I feel especially bad about the long necked water-fowl that was sitting on the center-line. It seemed confused, as if it couldn’t decide if it should stay there, or attempt to leave. A the last moment it took flight, cutting directly across my path, but far enough ahead that all would have been fine, had it not decided to change its mind directly in front of my wheel, and attempt to turn around. A tenth of a second? A hundredth? Just enough time for my mind to fear that the impact, and following loss of traction as I rode up and over its body would cause me to drop the bike, not enough to prevent the Thumping impact followed, without noticeable delay, by a jolt to the shocks, and then nothing until eventually…

Thwap

I thought it was just dirt, but then I realized it was the remains of countless South Dakotan grasshoppers.

I think it's dead now. ~ There's no way it's still healthy ~ It's not my fault though

Sun, 06 Sep 2009 00:00:00 +0000

I forget what state I was in. Ohio maybe? I’m not sure.

I was driving along, through the edges of some town when I see, for an instant, a Monarch Butterfly.

And then it hit me.
In the chest.

*whap*

Then, as they weigh so very little, the force of the wind colliding with my chest and rushing upwards pulled it along.
Right
up
into
my
HELMET

*flappityFlappityFlappity*

“AAAAAAAHHH!!!!”

There’s a flapping papery thing stuck between my jaw and my helmet. IT’S ALIVE!

*flappityflappity*

“Ahhhh! Get it out! Get it out!”

I start jamming my left index finger up by my chin to try and pull it down but it’s flapping, and the wind is pushing, and it’s flapping and it’s just going up my cheek!

“AHHHHH!!!!”

I pull my finger out and try to grab the edge of my visor to open it, and it’s flapping, and it’s moving, and the wind is beating it and there’s a truck coming and IT’S APPROACHING MY EYE!

The visor is open now but it’s not helping. It’s not coming out! I start shaking my head violently, like a Tourette’s sufferer having a bad day at forty miles an hour until eventually, finally, I manage to fling it out without flattening myself into the grill of the approaching pickup truck.

That was the only monarch I saw on the whole trip, and I’m pretty sure I killed it.

Pictures from across the states

Sun, 06 Sep 2009 00:00:00 +0000

Somewhere unknown

Camping in Carlyle IL

Pics from the Sky Meadow Campground

Wind Turbine Blades

Grain Storage

Murals by E. Rhodes

Wyoming Plains

Indian Springs

Phantom Canyon Road’s southern end

Bug Spatter

Iowa Standard

My bike in The Badlands

The final morning

Today was the last ~ It started off in a cloud ~ Ended with regrets

Sun, 06 Sep 2009 00:00:00 +0000

Today, my last day, started off about a third of the way across New York in Arkport and found me riding through another cloud. This one was just enough to shorten visibility and mist up your visor. Not like the one in Wyoming which left everything dripping. After a while I made my way past the hills that bounded it and found bright blue skies with sunlight streaming down.

I was excited. “I’m going home!” I thought, but the closer I got to home, the more I didn’t want to arrive. Even taking the Mohawk Trail on the way back through Massachusetts didn’t lift my spirits. In the end, it just didn’t feel like a homecoming. I love seeing Boston’s skyline come up over the horizon after being away. It’s always made me think “ahh, home” before. Today though, I just thought… “Maybe I should have kept going to California…”, and “I don’t want this to end.”

I found a new home out on the road. You hear adventure riders talk about wanting to get back “home” to their bike after they’ve been off it for a day or two. I’d always thought that to be a sort of joke, in that, you don’t have anywhere else to go but your bike, so it is “home” by default. But on this ride I learned the truth of it. Your bike really does become your home. Everywhere else is unknown and a little shaky, but your saddle… Your saddle is the place you go to feel safe and comforted in the way that any good home does. I’d find myself looking out at it from some random restaurant windows, just wanting to be done with my meal so I could climb back on.

A motorcycle is so much more than a “home” though. It is part of the adventure, with a personality all its own, and calling it a “steel horse” isn’t just poetic license. It is a metaphor that lies very close to truth. It eats, it breathes, it has things it likes and doesn’t like that aren’t necessarily shared by others of its breed. I really think that a motorcycle adventure isn’t that different from a horse adventure, except that a motorcycle is so much better at devouring the miles.

I imagine that once upon a time there were men who set out west on their horses, not so much for the promise of gold or new land to call their own, but because they could. Because there were new things to be seen, new places to go.

For a while I was like them: seeing new things, exploring new places, sleeping on ground that wasn’t always soft, starting each day by packing your saddlebags and throwing your sleeping gear over your horses back. Now I’m back at my house with it’s big plasma TV screen and soft cushions, and I’m not convinced it’s an improvement. I look at shelves of books, video games, electronic boxes and wonder “why do I need all this?”

I was riding through clouds in Wyoming, and New York. I saw tumbleweeds crossing before me, and windmills bringing water for cows. I watched the lush beauty of the Black Hills turn to the bleak death of the Badlands in a matter of hours. I drove past two miles of abandoned boxcars, and made my bed to the sound of cicadas instead of Chevrolets. I watched my black gloves bleach a yellow-grey in the sun. And I am not at all convinced that this soft couch is an improvement…