Is writing API documentation going the way of the keypunch operator?

I’m in the process of writing one of several academic articles that my current profession (professor) demands of me. An essential part of the process is indulging in the diversions and distractions necessary to retain some sanity throughout the process. Today’s diversion was updating my global bibliography. Unfortunately, that idea turned out to have some depressing side effects, which I’m here to share with you.

It turns out that there’s a lot of research being done in how to automatically generate API documentation. Having written a lot of it and read a lot more, I can certainly understand the motivations. What I didn’t realize was from how many different directions the problem was being attacked. Someone even patented an idea for it (US 8819629 B2, in case you were wondering).

Continue reading “Is writing API documentation going the way of the keypunch operator?”

Party like it’s 1995

Garmin GPS-III on table
My GPS-III Pilot getting to know the 21st century, again

A couple of days ago, I fired up my trusty Garmin GPS-III Pilot to take on a ham-radio trip. After it initialized and found itself, it declared the date to be Dec 2, 1995. I let it sit for a while, thinking that it might just be slow in waking up. After several hours, however, it remained convinced that Christmas 1995 was only just a few weeks away. I had another GPS (or 6) to use, so grabbed another one for the trip and I didn’t get a chance to investigate this temporal lapse until this morning.

It turns out, that this flashback was the result of a date-rollover error. Basically, the GPS uses a 10-bit number to count the number of weeks since January 6, 1980, when time began for GPS units. With 10 binary bits, you can represent 1,024 different things–weeks, in this case. After 1,024 weeks, after the GPS’ calendar returns to the beginning, back in 1980. This occurred in Aug, 1999, but was easily anticipated and GPS units manufactured shortly before that date could be programmed to accommodate the event by correcting for values that would result in a date that predated its manufacture. But, it seems that my GPS has lived long enough for that correction to no longer work as it did 15 years ago (i.e. the corrections to the current week values result in a date that’s reasonable to the GPS: 1995).

It turns out that many vintage GPS receivers manufactured in the mid to late 90s have similar problem, so it’s one that’s easily fixed by using a program written to update even older GPS units in preparation for the 1999 event. After running this program, my GPS-III Pilot is now living in the 21st century and is enjoying a morning in the sun on the back deck as it catches up with what’s been going on in GPS circles recently (i.e. it’s downloading the current satellite information from the GPS satellites).

This is interesting in that it’s a reminder of how even well designed software can surprise you, and it makes me wonder why I’m so attached to a GPS unit that’s almost 20 years old. It could be because we have had a lot of adventures together or it could be that I’m just a pack rat. Either way, we’re both sync’d up to the correct time.

The Internet-of-things is not about things

Tracy Rolling wrote a detailed, first-person, customer experience report in Medium about the limitations of activity tracking. It’s not that we can’t track activities, but that the resulting information is something less than useful to the average (read, non-fanatic) consumer. In her article, she describes how her activity tracker can log all manner of data, but it really doesn’t provide much in the way of information that’s useful to her on a daily basis. Consequently, it should come as no surprise that activity trackers are abandoned after just a short period.  Her article highlights the value of the end-to-end customer experience.

Looking in from the outside (I don’t own an activity tracker), I don’t know that this fall into disuse is because the tracker puts itself out of a job (saying, in effect, “You’ve achieved your goal! Congratulations. My work is done.”) or it just doesn’t live up to its promise, whatever that was at the time it was bought. In either case, it highlights what seems to be an inherent challenge that the Internet-of-things hasn’t overcome: providing a durable customer value.

In spite of the recent hype, tracking things isn’t new. I’ve been connecting things to devices and vice versa for 35 years. Connecting them to the Internet is new, but recording telemetry is not. The fact that every person in the civilized world is carrying a powerful computer (usually in the shape of a telephone) is a recent phenomena, that one would think holds some promise. However, without a need (be it present or latent), connecting monitoring transducers to a smartphone or the Internet still seems like it’s in the solution-looking-for-a-problem phase of technology.

It’s not unlike the early days of cell phones or PCs–when the technology was a solution in search of a problem. Eventually, problems will be identified (or invented) and then connected with solutions. However, in the meantime, there’s much to learn about both.

Facebook, Twitter, Ham radio?

Social media?
Social media?

It turns out I’ve been a social media user (perhaps even somewhat of an expert) for almost 30 years, now. Time to update my resume.

According to this article, amateur radio (a.k.a. ham radio) is the original social media. Um, OK. Let’s compare and contrast…

The article cites these examples:

  • Talking to people in England and Australia
  • Using abbreviated words (e.g. BCNU = be seeing you in ham radio and when texting)
  • Providing communications during emergency situations
  • Using technology
  • Thousands (millions?) of people can hear/read what you send in an instant

OK. There’s no arguing that they have some things in common. In fact, ham radio (Morse code, to be specific) had a speed advantage over texting in a demonstration on the Jay Leno show some 10 years ago. This report from Indiana University had somewhat different results, however, so your mileage may vary–mine would be embarrassing, so I won’t even bring that into the discussion. But, to be fair, let’s look at some of the differences that the report from Indiana University illustrated, if not highlighted.

  • Ham radio requires a desk-mounted piece of equipment (and a long antenna that wasn’t shown), while texting requires a device that fits in your pocket
  • Ham radio is somewhat more inconvenient (see previous point)
  • Not shown, but you can send a text to many more people than you can send a ham-radio message
  • A text can be sent in English (or any other language that you can type on the keypad), while ham radio messages are coded in Morse code. (Granted, you can also speak over ham radio…like a phone, for example)

While they have some things in common, they are also different in many ways.

I have fun with ham radio and I’ve talked to far-away places. For the past two years, I’ve used it to support humanitarian work in eastern Honduras. That I can string up a wire and talk to someone in Brazil without any additional equipment beyond the radio that’s connected to the wire, never ceases to amaze me, but is it social media?

I’ll settle for calling it technical communications.

A day late and a click short

An ad from my Facebook feed
An ad from my Facebook feed

The other day, this little plastic piece broke causing my 9-year-old car to spray hot engine coolant all over the road and emit plumes of steam from under the hood. AAA rescued the car and a tow truck  brought it home. Fortunately, the broken part was easily visible in the engine compartment and a quick search identified several options for purchasing a replacement.

As auto parts go, it looked like one of the easier to replace, but it broke on Monday and I wouldn’t be able to get to it until the weekend, which would inconvenience my wife and daughter who drive the car. So, I called my favorite auto mechanic, Accurate Auto Service, in Snohomish, who could (and did) fix it right away.

Problem solved. Which brings me to…

Yesterday. Facebook tried to add value to my browsing experience (and their bottom line) by showing me the ad in the photo.

Thanks, but no thanks.

They do this a lot, and while I understand how Facebook lives to sell ads, I’m not sure why they think that showing me something I looked for (and found) two-days earlier is something I might still be interested in. I’m sure they have the numbers to show this works enough to keep doing it, but it brings to mind some troubling implications:

  1. What were they  (i.e. their algorithm) thinking when they picked this ad? Is that how I really shop? (maybe) but more troubling still, what else do they know about me better than I do? Which leads to…
  2. How were they watching (I know, tracking cookies and what not, but how far does that go? Are they watching me type this?)
  3. What would I have thought if this had happened 10 years ago? 20 years ago? (There’s another blog post)
  4. Why does this not bother me anymore? Are baby pictures and cute dog videos really that valuable to me?

How did I ever survive without Facebook there to show me baby pictures for the low, low price of being able to look over my shoulder when I do other things on the Internet? Truth be told, it’s really easier to just stop thinking and look at the cute baby pictures–and therein lies the real problem.

 

Bridging the decades

DB-9 connector used by RS-232 connections to PC

After installing the solid-state drive and experiencing what 2015-technology has to offer, I finally installed the serial (as in RS-232) and Firewire-400 ports to connect my turn-of-the-century technology to the new computer. So far, so good. Windows 7 drivers all installed without complaint, and they seem to work well–quite well, as a matter of fact.

As Hannibal of the A-Team would say, “I love it when a plan comes together!”

It seems like only yesterday

Copying files on the new computer
Copying files on the new computer

Only 13 years ago, I bought my last desktop computer. Rest assured, I’ve bought newer computers in the intervening years, but they’ve all been laptops of various makes and sizes. My most recent laptop was more like a portable desktop in terms of CPU (Intel I7) and memory (8GB…it seemed like a lot for a laptop, 2-1/2 years ago) and a fancy graphics chip. I thought that would make a reasonable replacement for my aging desktop, but after editing some video recently, I reevaluated that conclusion. I think it was when the keyboard reached 150+ degrees Fahrenheit (according to the IR thermometer).

In 2002, when I bought the last desktop for video editing, this it what $2,000-some would get you: 1 GHz 32-bit processor, 1 GB of RAMDAC memory, 100Mb/Sec Ethernet, Firewire 400 and USB 2.0 (stop giggling). It’s gone through a few hard drives, video cards, monitors, and other peripherals, but it’s still chugging away running Windows XP (SP3). For several years, it did a decent job editing DV videos with reasonable aplomb. However, since almost melting the keyboard of my laptop, I’ve been shopping for a new desktop–until last weekend.

I saw the computer I wanted on sale at Costco and, as often happens when visiting Costco, it somehow ended up in the cart. Since then, as I should be revising my dissertation, I’ve been going through the process of migrating the features and functions the old desktop performed to the new computer. Eventually, the old desktop will join the collection of obsolete computers that have taken residence out in my garage. It’s in the process of migrating from the old to the new that I provides the contrast between then and now.

Starting with Firewire 400. Who uses that? (I do.) I need this to connect to my DV and HDV camera and tape deck collection at least long enough to copy their content to a hard drive.

And the RS-232 serial ports. When did they stopped including those on computers? I still have some devices that connect over serial cables, so I’ll add a couple of ports for those.

While addding these cards helps bridge the technological generation gap(s), I’m hardly sad about how technology has improved over the years. Gigabit-ethernet makes connecting to the NAS much faster. SATA drives are a big step up from the older ATA drives in speed and capacity, increasing file transfer speed considerably.

But the biggest treat came from the solid-state drive (SSD) I added, which made possible sustained file transfer rates from the internal SATA drive of more than 150 megabytes/second (as in the photo). That’s  8-10x faster than the desktop it replaced and 3x faster than the laptop that was supposed to be my next desktop–this is now limited by the SATA drive.

So back to copying files and installing apps.