A Theory of Documentation

“Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances – so software usually needs them all.

And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.”

—Daniele Procida, “What nobody tells you about documentation.” Divio. Accessed: November 12, 2018.

Probably applicable to any kind of documentation process you need to replicate, not just for software.

Other 9/11s

On September 11, 1973, the Chilean government was overthrown by a CIA-backed military coup d’état that killed or disappeared a few thousand people. Over the years, the government of General Pinochet arrested, imprisoned and tortured more than 28,000 people and over 200,000 people (2% of the population) were forced into exile because of this coup.

There are other 9/11s. We would do well to remember these others, where the United States were the perpetrators and not the victims. I try to do this by playing a song by Victor Jara, who was tortured and found dead in the streets of Chile on September 16, 1973.

It might also be worthwhile to think about today. There is a 9/11 being created in Yemen by Saudi Arabia using weapons made in the United States and with the support of the United States government.

The Encyclopedia of Science Fiction

“Of all the things you can read on the internet, The Encyclopedia of Science Fiction is one of the only good ones. In perpetual conversation with itself, ever growing and expanding—perhaps threatening, in its accumulated obsessions, to become self-aware—this index of the fantastic documents possible pasts and futures alike.”
—M.H. Rowe. “The Encyclopedia of Science Fiction is the Best Place on the Internet
Self-Referential, Argumentative, and Never Dispassionate.” Lithub.com. August 16, 2018.

M.H. Rowe’s article is a love letter to The Encyclopedia of Science Fiction. The whole thing is fantastic. If you aren’t interested in diving in after reading it, you’re never going to be.

My favorite entry, thus far, is infodumps. Also, I appreciated the reminder to read Ted Chiang on my first dive in.

Obesity in America 2018: 7 charts that explain why it’s so easy to gain weight – Vox

“Sure, it’s possible to have a small, healthy meal at a restaurant. But researchers have found that people typically eat 20 to 40 percent more calories in restaurants compared with what they’d eat at home.”

—Eliza Barclay, Julia Belluz, and Javier Zarracina. “Obesity in America 2018: 7 charts that explain why it’s so easy to gain weight.” Vox. August 9, 2018.

Key take aways: eat at home, reduce portion sizes, drink water, eat a variety of foods, and reduce sugar intake.

The Intellectual Dark Web

The Internet is such a bizarre rabbit burrow of ideas. I came across the term: “Intellectual Dark Web” while skimming a Jacobite article providing an assessment of the “movement”. The article pointed to an aggregating website, which in turn links to guides like, “How to join the Intellectual Dark Web — a user’s guide.”

I suspect this is something that will gain some mindshare. On first blush, it seems like horseshit. But, I thought I’d post a note to look a little deeper later.

Nothing wrong with the wanting a space for the free exchange of ideas, particularly unpopular ones. But, intellectual and dark implies quite a bit more, as if a negative light shines through the ends of the Overton Window.

Sounds like bunkum and flimflam, but even error has its uses.