Another Take on Austin’s Proposition A

Emma Freer wrote a good retrospective on Austin’s successful 2020 light rail election in Austonia:

Unlike other races this election cycle, the results weren’t close. Prop A passed by a nearly 19% margin, which local political analysts and transit advocates attributed to record-breaking turnout, a younger electorate and a new approach to transit planning.

The new approach to transit planning is described by Christof Spieler. First, don’t be coy. If you’re proposing transit, go all in for transit.

Conventional wisdom used to be that a transit referendum would be more likely to pass if it appealed to transit skeptics, said Christof Spieler, a senior lecturer at the Rice University School of Architecture.

This was often achieved by limiting the amount of funding and bundling in spending for different kinds of infrastructure.

Comparing the 2020 plan to 2014:

This time around, Capital Metro and city officials learned from past failures. Project Connect included more than seven times the investment and focused exclusively on transit, with two light rail lines, expanded bus service and other components.

Second, do the community outreach. Getting community groups involved and invested improved the plan, but it also included a bunch of activists who were influential in their communities.

Another key change, Spieler said, is the attention paid to advocacy groups and grassroots organizing.

Capital Metro reports that around 60,000 Austinites provided input on Project Connect, and advocates—some of whom opposed the last ballot measure because they felt it did too little—were more directly involved.

“Those advocacy groups were a major voice in the creation of the plan and then rally their supporters to turn out to vote for it,” Spieler said.

You could say that the 2014 plan died because of a bad map. But they developed a bad map because they studiously avoided involving any community groups. In the end, they had a bad map and no supporters.

iA Writer 5.5 Improves WordPress Support

iA Writer just updated to version 5.5. This looks like a significant update, with one big feature that affects me: better support for self-hosted WordPress sites. Previous versions required the Jetpack plugin, which I balked at using. Now I can use the IndieAuth plugin. The OAuth2 plugin is also supported with a little more configuration.

This is my first post with iA Writer 5.5. It took me a couple of tries to get the plugin to work–documentation is scarce. But it works as advertised. Here’s hoping it leads to more posts here.

Markdown for Technical Documentation

It seems like this advice comes along periodically: Don’t use Markdown for technical documentation. Hillel Wayne is the most recent plea to hit hacker news, but there have been others.

Hillel Wayne, Please don’t write your documentation in Markdown

Markdown cannot carry data. There’s no way to imbue properties into text using markdown. Good documentation is all about the semantic markup. A “definition” is not just a different formatting or like. It means there’s actually a concept of a “definition” as a discrete concept in your documentation.

Matthew Butterick, in Pollen: the book is a program:

Markdown is a limiting format for authors. Why? Because Markdown is merely shorthand notation for HTML tags. As such, it has three problems: it’s not semantic, it only covers a limited subset of HTML tags, and it can’t be extended by an author.

Eric Holscher, Why You Shouldn’t Use “Markdown” for Documentation

Though many people have added extensions to Markdown, almost none have any kind of semantic meaning. This means that you can’t write a Class or a Warning, you can only write text.

Mister Gold, Stop Using Markdown For Documentation

With Markdown you can only write text. It means that if you need to grab the reader’s attention with some kind of notes or tips, you have to embed HTML.

I have focused on the lack of semantic data in all these criticisms, because I think it is the most important drawback. The lack of semantic meaning in markdown makes in unsuitable for many technical writing tasks. Yet, I still write in markdown. This post is in markdown. There are a couple of reasons:

  1. Its easy. I never forget the syntax. This may be because it is so limited, but it makes it easy to do simple documents.
  2. It’s ubiquitous. The fact that there are so many different markdown parsers is not problem, its a strength. It’s usually trivial to add markdown to a system or workflow, regardless of the environment

What are the alternatives?

ReStructurexText – If I were writing a book, I would probably use ReStructuredText. It is extensible, so you can add your own “roles”. But the syntax is pretty hard to remember. For example, here is the image syntax:

.. image:: images/biohazard.png
    :height: 100
    :width: 200
    :scale: 50
    :alt: alternate text

Of course, the benefit is that the image tag has a height, width, and scale: something few markdown parsers support. It’s heavily tied to Python, which is something I’m comfortable with. It’s also heavily tied to a single implementation in docutils.

AsciiDoc – The syntax is more in the spirit of markdown. It seems to have coalesced around a Ruby implementation, and left the original python implementation languishing[1]. I was unhappy with the HTML produced by asciidoctor is styled entirely by div tags. Title ; just styles applied to named div tags.

Pollen – Very nice system. The fact it requires Racket is both admirable and a real-world pain. I gave up after trying to write my own pollen command. Trying to debug the unexpected return type from a nested s-expresion did me in.

For now, I stay with markdown, and all it’s shortcomings.


  1. There are also two competing versions of aciidoc for python3: asciidoc-py3 and asciidoc3  ↩

Remote Cheese Tasting

In the spirit of supporting our local business during the pandemic, we signed up for a cheese-tasing course with Antonelli’s. We picked up a half pound of cheese from their shop: a pre-selected sampling of seven different cheeses. Then we embellished it with a little prosciutto, Castelvetrano olives, a baguette, and some wine. We then tuned into their video stream while they talked us through the full tasting menu. It was great, especially considering they had never streamed a tasting before and rushed into it with about a week’s preparation.

A cheese plate with wine and bread.

Three Days, Three Rings

One thing I noticed during these coronavirus work-at-home days is how absolutely sedentary I am when working from home. I’ve worked from home in other jobs, but I really notice it now. My Apple Watch detects essentially zero exercise, and very little activity. At work, all the small trips to the water fountain, to the restroom, to the cafeteria, they all add up. They don’t close my rings, but they at least make it look like I did something besides sit on my butt all day. At home all of those little trips are about 20 feet away, max.

In the last few days I’ve been making an effort to get out and close my exercise ring. I no longer have a commute, so that gives me an extra 45 minutes to an hour I can devote to exercise. I’ve been getting my rings closed, and breaking free of the stay-at-home ennui.