Skip to main content

The Problem with Github Pages

I love Github Pages. I run this blog, my personal blog, and my music and liturgy blog on it. I used it to host documentation for my most recent tech writing gig.

For a single writer with moderate or better technical skills looking for a simple hosting solution, it's amazing. But, I've recently realized there's a problem with it that makes it ill-suited for multiple collaborators working on complicated documentation. (Or even, as I discovered, a single writer on more than one machine.)

Read more…

Data Structures and Philosophy

Sometimes bad programming is just bad programming: people write sloppy code, people don't know how things are supposed to work, people forget that binary math is weird sometimes.

But often, bad programming is a result of bad philosophy - a fundamental misunderstanding of how meaning is made, or thought works, or how the world is structured. Sometimes the fault is a little less radical, tied to ignorance of some domain-specific facts, but often it's just plain bad philosophy.

Read more…

On the Design of this Blog

Since I spend almost my entire day in an editor, writing, I've put a bit of effort into getting it to look the way I like. The most important things for my writing experience are:

  • dark theme
  • oversized display font
  • syntax highlighting
  • relatively narrow text (< 80 column)
  • centered text with a decent margin on each side

Here is what my screen looks like when writing a blog post.

AMW Post in Editor

Read more…

It Should Matter That It's You

I grew up doing theatre, went to college for theatre, and taught theatre for a few years. Nearly all of my theatre experience --- as a performer, teacher, director, stagehand, designer, or even audience member --- was non-profit and the bulk was non-professional. High school, university, community, non-profit regional.

I saw a lot of shows where it didn't seem to matter who had directed it, or who had designed it. So many high school and community theatre shows are bad reproductions of the professional version of the same show. Musicals, comedies, murder mysteries... musical comedy murder mysteries. Names the audience recognizes, with poorly built sets that look pretty much the same as every other production of the show, and costumes assembled from what seems like the same pile of thrift-store refuse.

Read more…

Enough to Be Dangerous: The Joy of Bad Python

Learning to Code is all the rage. I don't see any sign that the trend is dying down any time soon. I might as well jump on the bandwagon here and encourage my fellow tech writers to do the same.

Obviously, a lot of you already code, or are in the process of learning. I once assumed knowing at least some coding was a requirement for being a tech writer. But it seems this isn't entirely the case. Some TWs need to be able to read and write enough code to document APIs and provide code samples --- but apparently (I have learned) most tech writers aren't doing that, and you can fake your way through that if you really need to.

So, if you are among the majority of technical writers that don't code, this post is for you.

Read more…

"Success and Self-Determination: You Need a Third Option"

I am the master of my fate;
I am the captain of my soul.
— from Invictus, by William Ernest Henley

A strong sense of agency --- the feeling that you can, indeed, control the course of your own life --- is an essential element of success.

Unfortunately, a sense of agency can also be a source of crippling guilt and shame.

If I am not the master of my fate, then my lack of success up to this point is not my own fault. There is nothing wrong with me.

But if I am, well then --- I have some explaining to do. Why have I not lost the weight, started the business, written the book, built the app?

Read more…