Morgan Witt on Austin Land Use

Candidate for Austin City Council Place 7, Morgan Witt, quoted in the Austin Monitor

The reality is that when we talk about preserving neighborhoods as they exist right now, that means we’re excluding people from those neighborhoods, If we don’t develop in these neighborhoods, people build outward. That means the people most vulnerable to being displaced because of lack of affordability, they have to move further out of the city; they have less access to resources, they have more transportation costs to get to work, but also we as a city have to spend more money in infrastructure to build out so that people can access the city.

While we think that not developing in these neighborhoods is protecting the environment, the reality is sprawl is a huge environmental issue. We really need to think about how can we be more inclusive as a city and allow more people and more diverse people to live in the neighborhoods that exist so that everybody gets the opportunity to live that Austin experience and share in that neighborhood character.

I wish her luck in her campaign.

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.