The Problem with Github Pages

Adam Michael Wood

2017-01-10 05:50

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.)

Shipping

Adam Michael Wood

2017-01-09 06:42

Comments

My New Year's Resolution --- which I have so far held to --- is to write and publish every day.

Data Structures and Philosophy

Adam Michael Wood

2017-01-06 07:26

Comments

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.

On the Design of this Blog

Adam Michael Wood

2017-01-05 06:29

Comments

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

Overriding CSS/LESS Declaration to Reduce One LOC

Adam Michael Wood

2017-01-04 05:50

Comments

While working on the theme for this site, I was referencing Markdown CSS, which makes HTML look like Markdown. (h/t @ericholscher)

I ran across an interesting (let's call it a) pattern.

It Should Matter That It's You

Adam Michael Wood

2017-01-03 06:06

Comments

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.

Simple Input Validation and Exception Handling in Python

Adam Michael Wood

2017-01-02 06:33

Comments

If you are doing a simple terminal script in Python, and you need to validate some user-supplied input, you can put the assignment and validation in a try block inside a while loop.

Enough to Be Dangerous: The Joy of Bad Python

Adam Michael Wood

2017-01-01 06:31

Comments

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.

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

Adam Michael Wood

2016-02-13 07:26

Comments

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?

Python and Django vs. Ruby and Rails

Adam Michael Wood

2016-02-10 15:22

Comments

tl;dr - Python.

I can't even begin to count how many forum posts and deleted Stack Overflow questions there are boiling down to some version of Python vs. Ruby or, more specifically, Django vs. Rails. Google (as of right now) has NINE POINT EIGHT MILLION results for "Python vs. Ruby", which is basically insane.