Make your documentation specific

Programmers grasp the importance of precision when they/we write code.

Then too often it seems they/we forget it when writing documentation.

Somewhat ironically, I’m not going to include many specifics here. I don’t begrudge any individual for being too busy to leave notes or edit them too meticulously. But it’s a pattern I’ve now observed in several places I’ve worked: a ton of relevant information exists in two-person instant messages, months-old emails, or one person’s head (so we hope they remember it) and not in an established location that any person in the group can use as a reference.

The tech community developed its preferences against overdoing documentation and toward lean startups/Agile methodology for good reason. The global flow of paperwork is excessive. Small teams shouldn’t need to maintain complete logs of every action by anyone at anytime for any reason. All things being equal, less documentation is probably better than more.

All the same, writing down important information for reference goes a long way to not wasting the time and energy of new people – and by extension, not wasting the money of the organization.

I actually think my workplace, the Earlham CS Department, has a structure to handle this better than most: a wiki that any employee or student in the program can edit with minimal training. Teaching people the habit of updating the wiki after major project updates helps preserve institutional memory (funny enough, teams of students have a high turnover rate) and helps new people integrate into the system faster.

Minimizing bureaucracy is good. But making concise, specific, actionable, relatively frequent updates to community-accessible notes is also good. Teams can find a balance.

Glass on the floor of the Internet

I saw this tweet today:

[tweet https://twitter.com/sarah_edo/status/1013427276350873600]

For posterity:

Sarah Drasner @sarah_edo: I miss the useless web. I miss your grandpa’s blog. I miss weird web art projects that trolled me. I miss fan pages for things like hippos. I wish I didn’t feel like the web was collapsing into just a few sites plus a thousand resumes.

I was using dial-up as a kid at the time the “useless web” last existed in a meaningful way. I don’t remember it well. I suspect I would have liked it.

She’s right that it doesn’t exist anymore, at any real scale. That got me thinking back to an interview between MSNBC’s Chris Hayes and the tech/media guru Tim Wu, talking about why the Internet is now bad:

TIM WU: And you know, the old days, links were seen as treasures. Imagine that.

CHRIS HAYES: So true.

TIM WU: So like, someone, Yahoo, its basic idea is, here are some good links to go to. You know, a whole business was built on that premise. It was like, we’re a bunch of guys who hang on the internet and here are the coolest links.

CHRIS HAYES: [laughs] Here are some links.

TIM WU: Yeah, so now, so that’s the experience back then. Today, you wander off the safe paths of the internet and it’s like a trap. You know, you click on the wrong thing, suddenly fifty pop-ups come up, something says, hey, you’ve been infected with a virus, click here to fix it, which of course, if you do click on it, it does infect you with a virus, it’s teeming with weird listicles and crazy things like, reason number four and how you can increase your sperm count or something, and you have to kind of constantly control yourself. You have to be on guard, it’s worse than, it’s a mixture of being in a bad neighborhood and a used car sales place and a casino and a infectious disease ward, all combined into one, and that is not relaxing. Yeah, let’s just put it that way.

I’ve thought about that exchange a lot.

For a regular user of the Internet, and even for someone like me with a comparatively huge advantage in privilege, education, access to technology, and skills, the Internet is a dangerous place to be. Yes you can get to just about anything you want to, but the journey is perilous. It’s like a mirror was shattered and you have to walk across the glass to get to your bookshelf, or desk, or couch. It’ll be great, if your feet don’t get punctured.

Wu traces the problem back to (I think) the correct source: consolidation of power on the Internet that broadly reflects similar consolidations in radio and television. My inference is that it goes something like this: talent flocks to the places that can pay a lot. Smaller places can’t afford the talent, so they aren’t able to handle security as well, or to defend their IP against copycats or knockoffs, or to ensure that the public knows they can be trusted where another site can’t. Aggregation theory takes over because the major players can provide a better (in this case read: safer) experience to users. Smaller players shrivel and disappear so that scammers (and personal resumes, as Sarah Drasner mentioned) overwhelm other small players left on the web. And you get the bad Internet.

There are ways that individuals, companies, and organizations can mitigate the problem. But the fundamental structure and incentives drain smaller sites of the resources needed to make and share good stuff online.

This is why, like many people, I don’t feel comfortable trusting some random link to a site I’ve never heard of. I mostly ignore those links and stay within the “safe paths of the Internet.” I’m sure I miss good stuff, but I also miss a ton of bad stuff.

I want more useless things online. I want to see Rule of Fun apply to more of what circulates online. I want the open web to work. Making that happen in a sustainable way is as much a political project as an individual one.

If you want a small taste of what the useless web might look like, check out Inspiring Online, a great source for a grab bag of delightful Internet miscellany in its purest form.

Tools I use for work

As a student and then a self-employed person, I went through several phases of experimenting with programs and devices to do my work. These have been the ones that have stayed with me.

Some notes app

I use Apple Notes for on-the-go notes and once in a while move everything over to Microsoft’s more structured OneNote for long-term storage.

Freedom

Usually my self-control is pretty good. When I’m reopening Twitter for the fourth time in an hour and quickly running into the same tweets I just saw, I know I need the intervention of an external force. Three clicks of the Freedom icon on my Mac and I can block Twitter (and any other distracting site, if I need to) for as long as necessary.

A browser

If the Internet is something you use, this is important. I use Chrome but I have Firefox on all my devices as well.

A terminal*

Ever since I learned to use Unix in college, setting up a terminal (or the Windows subsystem for Linux on Windows 10) is always one of the first things I do. My .bashrc has been incrementally expanded and contracted and relocated for a few years now, allowing complete and portable customization of my shell environment.

(*–pedantic: Yes, it’s technically a “terminal emulator“. No, this particular language difference does not matter to me.)

A text editor

For code, short messages, drafts, and occasional distraction-free writing, I always have a text editor. The default programs are fine, but I like Atom on my Mac and Microsoft Visual Studio on my Windows desktop. If I’m running a terminal I use vim.*

*If you’re torn in a Unix environment, just use the one you learned first – vi, vim, emacs, nano, whatever. In almost all cases, the differences are less important than loud people say online.

An office suite

In 99% of cases this is Google Drive. I use it for word processing and for my sprawling budget spreadsheets. Collaboration is easy, the interface is pleasant, and it’s free. Microsoft Office has more features, though, so if I need more tools than Drive supports I turn to Office. Exception: I use Keynote on my Mac for presentations because I like it quite a lot. I seldom use any other presentation tool.

A scanning app

I don’t like to carry around a lot of paper. I digitize my receipts and other paperwork whenever I can. When I had a desk I could use a document scanner, but now I just use Scanbot Pro. Once I have PDF’s and upload them to the cloud, I discard the paper copies. I will almost never need them later anyway, and a few megabytes on a computer is better than several drawers in a file cabinet.

I do keep paper copies of tax documents and papers that are significant as paper artifacts, but everything else gets scanned.

Some bibliographical tool

This I used more as a student (and now faculty member) and I hesitate to include it in a list I’d prefer to be general, but it saves a lot of time. Most people can use Zotero. I work in CS where most people write in LaTeX, so I use the BibTeX format instead whenever I can. Usually citation contents can be directly exported in that format from the site where the source was accessed, but if not the LaTeX world is well-documented and most labels (e.g. “author”) are intuitive.

What I don’t use

I’m not a strictly minimalist person, but a lot of the utilities and helpful programs you can find online aren’t necessary. Investigation, installation, configuration, and maintenance take time that could be better used elsewhere, in return for questionable time savings in the long run. I don’t use a window manager on my Mac, for example, because mostly managing windows on my Mac is fine with the built-in tools.

Being cautious about what I install helps save time and delay the inevitable buildup of system cruft that has to be purged once in a while.

This is it

There are a dozen other tools I’ve used: QuickBooks accounting software, map/direction tools, chat clients, maybe an email client, etc. In specific cases, those are worth exploring and probably worth running. This is a list of what I consider a solid foundation for productive work for most people.

Lessons from running my business

Millions of people are self-employed or run small businesses, and millions do one of those for a while and then move to something else. It’s hard for me to imagine that any of us has learned something unique to us individually.

It’s also incredibly easy to find other writers talking about it, sharing the things they learned, and the lists have a lot of overlap. A lot of the lessons also come across as pedestrian.

Still, I wanted to do a retrospective of my own experience. I wanted to approach it from a somewhat narrower perspective. To compile my list, I asked: What made an impact? What lessons did I learn from starting, running, and closing a one-person business that will cause me to act differently than I acted before I ran the business? Here are some of my answers, which of course I reserve the right to revisit.

People will give way more power to you than they should, and you have to be ethical about that.

I always asked permission before going into people’s files. And yet I was consistently told, “Oh, there’s nothing in there that’s secretive or anything, do anything you need to.” This was stunning to me.

I also saw the downside of this trust, repeatedly: computers bricked entirely by the IT support scam industry exploiting predominantly elderly people with little computer savvy and trusting hearts. On a few occasions I saved the computer only because of the sheer laziness of the scammers: one locked up a Windows computer with a particular encryption tool and set the password to “123456”.

Work honestly, and beware people who are willing to do otherwise.

Sometimes you fail. That hurts but it’s (probably) okay in the end.

This was especially true late in the business, as I was winding down and could see I had too little time to finish everything. I had a few uncomfortable phone calls and text exchanges trying to establish a compromise that met as many of my (understandably) annoyed client’s needs as possible within some tight time constraints. The end results were good for none of us but acceptable for all of us.

You will make mistakes and fall short. And that’s (usually) fine, if you patch it up as best you can, make amends, and learn from the experience.

Location is important.

I did not quit because I didn’t like the work. The job itself was fine. A few projects were great, a few were terrible, and most were in between.

I quit because the place I was living didn’t have what I needed for personal and social fulfillment (I’ll likely return to this topic in the future). I’ve never wanted to define my life around economic considerations alone, and I have the luxury of making that choice. When I got the chance at a job that paid about the same, in a place that in other respects was much better for personal development, I took the opportunity and left.

Coda

I closed down but mostly consider the business a success. I started because I needed to generate money for student loan and car payments. I made some money, got a few nice things, built my confidence, and proved my self-sufficiency. I figured out a few things I don’t want to spend my life doing. I could hardly have asked for a better first job after college.

Robot forecasting, circa 1978

In The People’s Almanac 2, published in 1978, there is a section entitled, unpleasantly, “Robots – Artificial Slaves”. It’s a reminder that fear of the robots coming for us all isn’t new.

After some history of androids in ancient literature and mythology, it gets to the interesting parts. For example:

Modern robots would not be possible without miniaturized electronic circuitry and sophisticated computer technology. Their most important component is the computer brain, housed in the robot body or elsewhere, which is programmed to perform certain tasks or react in certain ways to specific stimuli.

I’ve always appreciated this way of thinking about prosthetics and pacemakers:

[Robotic] devices used in medicine make the Bionic Man and Bionic Woman seem plausible. Artificial limbs employ signals from the nerves to the muscles so that people wearing them can use them as if they were really their own. Some devices, called cyborgs [!], go inside the body; e.g., the pacemaker, which regulates heartbeats.

Today most people have at least passing awareness of robotics, but this makes clear what a niche conversation it was at the time:

The leaders of robot manufacture for industry, which, according to robotics expert Gene Bartczak, is an extremely fast-growing field…

Finally, here’s the vision that – while humorously premature in its timeline – has a ring of prescience:

In the future, robots, not people, will go to distant planets with inhospitable climates, and there they will work for a few years and die.

[British roboticist M.W.] Thring predicts for future household use a robot that will scrub, sweep, clean, make beds, dry-clean clothes, tape television shows to be replayed, activate locks, choose library materials and print them by teletype, and more. It will not look human, though it will be sized for human households. In all likelihood, its computer brain will not be attached to its body, but instead will be conveniently housed in a closet. Its spoked but rimless wheels will enable it to climb stairs. Through a sophisticated computer program, it will be able to recognize and categorize objects – differentiate between a drinking glass and a cup, for instance. Available sometime in the 1980s, according to Thring, it will cost about $20,000 and have a life of about 25 years.

At the Third International Joint Conference on Artificial Intelligence at Stanford in 1973, scientists predicted robot tutors by 1983, robot judges by 1988, robot psychiatrists by 1990, and robot chauffeurs by 1992.

The story draws its inevitable ominous conclusion:

By 2000, scientists predict, there will be one robot for every 500 blue-collar workers, and robots will be smarter than humans and able to reproduce themselves for their own ends. And then, it is possible, but not likely, that the human dream of owning the perfect slave will turn into a nightmare, as the robots turn their attention to their human masters.

For what it’s worth, here are the 2015 robot density figures for a few advanced countries and for the world (figures from the International Federation of Roboticshighlighted by Robotics Business Review). Note that this chart shows robot density for all workers, not just blue-collar workers, so the apples-to-apples ratio should be even more dramatic given the smaller denominator.

Code here.

I have four observations.

  1. The slavery analogy was probably meant to be clever or illuminating. It’s not.
  2. The robot/AI apocalypse is not upon us, even in the age of high and rising robot density. The tech community should work on mitigating the effects of mass automation, to be sure, but it should not come at the expense of addressing existing problems of economic inequality, racism, demagoguery, and institutional stagnation. Tech policy changes should focus on what to do about workers who have already lost their jobs to automation, or who will in the next five to ten years.
  3. A lot of what the article predicts is likely at some time in the future. I expect “robot psychiatrists” and “robot tutors” will come before the “robot judges” for institutional reasons, but it will probably happen, maybe in my lifetime. I’m still not worried about an AI apocalypse.
  4. The generally delightful People’s Almanac 2, while sounding close to modern in discussing robotics, contains just 4 indexed references to computers. Go figure.

[I wrote this post and most of the code months ago, and I’ve added it here as part of migrating some of my favorite content to my new site.]

AI will be fine

Artificial intelligence will probably save lives, make lives better, and not destroy all of humanity.

On the one hand I just want to believe this. On the other hand there seems to be evidence that it’s true.

First, AI will save lives by a direct substitution of hardware/software for human labor. An explosion that would kill a mine worker would destroy a robot instead (raising questions about the personhood of software but clearly saving the flesh-and-blood person). A network of self-driving trucks will make fewer bad driving decisions than a network of tired human truckers.

Second, intelligence in humans seems to have increased at around the same time as violence in humans has decreased. If intelligence causes people to behave in less violent ways (arguable but plausible), then a piece of software exponentially smarter than a human might be at least somewhat less violent than a human.

For example, advanced AI can create better weapons, but it might also be less eager to launch them. Enter this classic xkcd:

I don’t worry about the rise of artificial intelligence from an extinction-of-the-human-species perspective. I do worry about it from the perspective of standards of living and human purpose, which are a lot harder to come by if virtually all work is done by technology. That’s a social problem that’s a century or so away, but we’re probably already seeing early signs of it.

By all means, worry about AI if you’re in a social/economic/demographic position where that’s your most imminent worry. But worry for the right reasons.