Bob Watson ponders technical writing, API documentation, and the world in general
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!”
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.
My wife and I were part of team who staffed the medical and dental clinic in Rus Rus, a small village 70 miles inland from the Caribbean coast and five miles north of Nicaragua. In our most recent trip to Honduras, I had time to mingle with the people who came from miles around to visit us in-between my radio-operator duties.
I speak enough Spanish to carry a conversation, but that’s of only minimal benefit it Rus Rus. The majority of people who came to visit us spoke only Miskito. Nevertheless, I managed to chat with a few of the people who spoke Spanish. I didn’t plan to interview them, but my curiosity can be hard to suppress.
I’m fascinated by the insights that simply chatting with the customer can reveal (to the point I’m getting a degree in it). By listening to the locals, I found that our visits are quite welcome by the local population, but they can also be quite an exercise in patience for them. And, that’s after they walk for hours, or days in some cases, to visit us. In keeping with my theme for this year, I consider…
When I met Luis, he had been waiting outside the clinic for over a day to have a painful tooth extracted (after suffering with it for several months before our visit). Luis lived about two hours away by truck or five or six hours away on foot. At this point, Luis was getting pretty hungry because the last time he’d eaten was before leaving to come visit us.
The dental clinic is very popular on these trips, and there is always quite a queue for the services they provide–often, there are many more patients in need of dental services than we can accommodate. Not knowing that he might have a long wait to see the dentist, Luis didn’t bring any food with him and returning home for the night wasn’t a viable option. Luis was debating whether to return home (in order to eat) or continue waiting to have his tooth pulled–a difficult decision given the lack of information he had available. I hope he was seen, but I wasn’t able to follow up with him–I had to return to my duties as the team’s radio operator shortly after our conversation.
Fortunately, IHS of MN, the group that organizes the trip, cares about their service. Hopefully, we’ll come up with a way to help people like Luis come prepared for a longer wait, or maybe provide more information about where they are in the queue so they can make an informed decision about what to do. Because they actively seek feedback from the volunteers, I’m sure we’ll do better to make time.
On this trip, I’m glad I was able to have a chance to see how our visits looked through the customers’ eyes and be able to provide that feedback.
This question has come up a few times recently and the answer, like the answer to so many technical writing questions is, “it depends,” of course. Which begs the next question, “depends on what?”
Well, at the root, what the reader wants to accomplish, perhaps most critically, how do they want to accomplish it.
I researched this a couple of years ago and found the multi-topic/page format was used in the API reference documentation we studied to be twice as common as the the single-topic/page format.
Now, because a format is more popular doesn’t necessarily mean that it’s better. Looking at this chart from the study shows that the format preference shifts towards the single-element per page format with larger APIs. It’s possible that the difference observed is nothing more than an artifact of authoring systems or organizational style guides.
Research on how people construct knowledge, however, tends to prefer the multi-topic/page format (to a point). If you are constructing knowledge about an API, you might look for an overview, some sample code, some explanations of some key methods, go back to the overview, look at some more sample code… Lather, rinse, repeat. Such a learning method is best facilitated by a big topic in which the reader can skip around to see quickly all the related information in whatever order his or her learning style desires. Doing that with each topic in a separate page requires multiple web-server accesses, each interrupting the flow for more time than in-page navigation. While the 2-3 seconds it might take for the page to load doesn’t sound like much, if it breaks the reader’s flow, it degrades the learning experience.
A key part of this learning method is the intra-page navigation–to facilitate meaningful skipping around, or random access to an otherwise sequentially oriented topic. This topic came up in a discussion about the scrollspy feature of Twitter Bootstrap, which provides some very helpful in-page navigation elements. The advantage of scrollspy is that it builds the in-page navigation when the page loads, which makes it much easier for the author (and maintainer) of the topic.
I’m finally getting back online after being in Honduras for two weeks and then spending the next two weeks catching up to the life I left behind.
For the last two weeks of February, my wife and I were in Honduras working as members of a brigada medica (medical brigade) with the International Health Organization of Minnesota (IHS of MN). We worked as a part of a medical & dental team—my wife was an interpreter and I was a radio operator. The organization deployed eight teams to various parts of Honduras. Our team went to a field hospital in Rus Rus, a small village in the jungle, 60-some miles inland from the Caribbean coast of Honduras and just five miles north of Nicaragua in La Mosquitia.
IHS of MN has brought medical brigades to Honduras for 33 years. This was our second trip with them and our second time at the field hospital in Rus Rus. Last year, I filled in as an interpreter for the medical staff when I wasn’t on the radio. This year, we had a surplus of interpreters, so when I wasn’t working the radio, I mingled with the local people who came to visit the clinic and got to know more about them and their lives.
As with our trip, last year, it was an amazing experience. We had the pleasure to work on a dedicated team of volunteers who provided health and dental care to people who would otherwise not have access to these services.
More stories, photos, and videos to come!