Aside Archives

All good technical writers go to heaven

I’m a reasonably technology-savvy guy. I’ve owned computers pretty much since it was possible to do so. I have an embarrassingly large collection of gadgets. But since getting into ham radio a bit, I’ve developed some ideas about technical documentation, manuals, and so on. I’m writing this, of course, after spending hours trying to work my way through a  digital scanner manual which is massive, detailed, and about 97% worthless. I’ll probably try it over and over again. However, right now, the manual is in the bottom of my kitchen trashcan under a layer of moldy scalloped potatoes. I’ll fish it out at some point.  Then I’ll take it out, put it on my driveway and run over it several times. Then I’ll burn it and dance in circles around the little paper fire. Not that I am frustrated or anything.

First, let’s get this digital scanner issue out of the way. The darn thing clearly will do everything except clean your refrigerator.  (By the way, I looked–your fridge needs cleaning.) So, it would absolutely be a challenge to write documentation for such a product. Remember the inverse relationship between user-friendliness and the number and complexity of functions. The more stuff a piece of technology will do the less user-friendly it is.  That said, why jam a zillion obscure capabilities in a product if those functions are so hard to use that they limit the customer to the geekiest of the technogeeks?  Also, three words: Quick Start Guide.

Then you have the problem of translation from Chinese and Japanese. This is no small matter. Like most ham radio operators, I have an interest in Asian poetry. I have a particular book of haiku that shows the original poem in Japanese. Then it has a very literal translation into English which almost never makes any sense at all. Then this book shows multiple translations of the same Japanese into English–and it can be stunning how different they are. That is because the translators have to interpret, not just transliterate.  Now, I know a radio manual isn’t talking about the morning dew on an evergreen branch, but good translation, particularly from Asian languages, is a highly complex (and expensive-to-hire) skill. However, in fairness, I’ve got piles of useless manuals written in English by guys from places like, you know, Wisconsin.

There ought to be a law. One law there ought to be is that TV shows should not be allowed to have any doorbell sounds in them because when a doorbell rings on TV I think it’s my damn doorbell and I get up and answer the door and there’s nobody there.

Another law is that the engineers who design a piece of technology should not be allowed to write the documentation. 

Now, there is an obvious argument for engineers writing the manuals for products they developed. They know them more than anyone. No wait, they are the ONLY people who know their products. But the problem with engineers communicating clearly is that (a) they are engineers, (b) they are too close and too familiar with their own product. When they are writing documentation, much of what they are writing about is so second-nature to them, they can’t take on the perspective of a new reader who is unfamiliar with the product.

(I mentioned that engineers writing their own product documentation ought to be illegal. This requires penalties. And, yes, you’ve already thought of the best penalty. Engineers caught writing their own manuals have to spend a few months reading other engineers’ manuals.)

Ideally, engineers should sit down with technical writers with no knowledge of the product. If they can’t find a technical writer, a high-school English teacher will do. That forces them to keep going over these complex details until the writer gets them and can communicate them as only good writers can. Alternately, if they can get my 8-year-old granddaughter to understand that you can

Press Func to display Site QK in Scan mode (easier to find Department if you Hold on System first). D# is first digit of Site QK. Blinking number on the right is second digit of Site QK

she can write an Asia-form Chinese poem about it and illustrate it with crayons. And that would be better than the typical documentation.

This is why I’m quitting my job, learning Chinese and Japanese, getting a degree in electrical engineering, another in software design, and becoming a technical writer. The money will just come rolling in. I also want to be a cowboy.

Dale
N4HEY

Trader’s Net discontinued

Shelby County ARC decided in their last meeting to discontinue Trader’s Net. I think this is the right call. With so many places online available for sale & trade of ham equipment, we have found in the last couple of years that listings on the net were somewhat infrequent and also seemed to lead to few actual transactions. The .32 repeater is a really good one, and perhaps in the future the club might decide to do a different kind of net on the repeater. 

If you have a central Alabama ham-related website, or manage a net, or have any other duties along those lines, please delete Trader’s Net from any of your listings. 

I want to thank all the folks that were regulars on the net for their support. Also, big shout out to Suzanne, KK4KIR, who called the Trader’s Net for a long time and made it a pleasure.

David Hanna funeral expenses Go Fund Me:

http://www.gofundme.com/davidhanna

Many of you have already heard the terrible news about David Hanna, WX4NCS. David was the victim of an awful accidental injury and passed away in surgery at UAB on February 10, 2018. This is a shock, of course. For the last few years, David was a mainstay on VHF. He had served as the Assistant EC in Jefferson County and was a frequent net control operator for several of our nets. Anyone who knew him knows that he had a servant’s heart and was a kind and gentle person. He was also passionate about the safety of people in bad weather event and that was why he gave so much of his time to the nets. He was also a welcoming voice on the repeaters and many newer hams will remember him for his outreach and encouragement of ham operators. David loved the Lord and he was a devoted family man. He leaves his wife Lucretia and their pride & joy, their little girl Alivia. Please remember his friends and family in your prayers. That is David Hanna, WX4NCS, silent key.

Taking and passing EC-00

I recently completed ARRL’s course, EC-001 Introduction to Emergency Communications,and I thought I’d post a few notes on the experience for those who are considering taking the course.

The first thing to know is that this is a real course, with reading and homework. You register for it at ARRL’s website (register here.) It costs $50 if you’re an ARRL member. You register for a particular time frame. For example, here’s the next section coming up:

Course Dates:

Wednesday, Dec 30 2015 – Friday, Mar 04 2016
Registration Dates:
Monday, Nov 02 2015 – Wednesday, Dec 16 2015
Course Cost:
$50.00
Total Seats:
30
Available Seats:
15
Note that you participate in the course over 9 weeks. Notice also there’s a limit on the number of students per section.

 

The course is done online via Moodle, the popular online education portal. Once registered, you are assigned a mentor. I worked with a terrific guy, Richard “Doc” Strait, AC8AL.

 

The course content is divided into 29 lessons in six sections. The student reads the content of each lesson, working at her own pace, which sometimes includes a short video and some outside resources to read. But, generally, each lesson just takes maybe 10 minutes to go through. At the end of the section is a little multiple-choice self-test (ungraded.)

 

You learn how to write (and pass) ARRL Radiograms. The course covers all kinds of angles for net operations in emergencies.  It covers communication skills, how to play nice with others. There’s a unit on Marine radio. It’s really an interesting grab bag of topics.

 

Each lesson then has a homework assignment. This is the real work of the course. Most of the assignments (called “activities”) require writing about 1 to 2 pages (typed). I will say, then: If you’re not comfortable with the idea of writing 30-50 pages in 9 weeks, this course might not be for you.

 

Most questions ask the student to apply what’s been learned in a lesson to a hypothetical situation. Something like this:

 

 Let’s say you were in charge of an emergency net for situation X. What are the kind of considerations you would have in deciding what kind of stations to set up in the field?

 

What are some of the behavioral guidelines for hams who are working for served agencies?

 

 If you were deployed someplace, make a list of the personal items you’d need and the radio gear you’d take.

 

 

A few of the assignments require you to have conversations with ham operators in leadership positions. Those require a phone call or a radio contact or an email.

 

When the student finishes an assignment, she uploads it. The mentor reads it and comments. In some cases, my mentor just said “Good job, Dale” and gave me my grade. In other cases, he provided a really generous amount of constructive feedback based on his experience. I was quite impressed with how much I was able to interact with him, which is why the limited number of students who can sign up for the course at a given time is important.

 

The student can work at her own pace during the course, with the goal of getting it done in 9 weeks. I had weeks where I knocked out a lot of the lessons, to make up for weeks when I didn’t. But, really, given that I work full time, I needed the full 9 weeks. I know students can apply for an extension. There’s an online forum on Moodle where students can interact, comment, ask questions. It wasn’t used much in my case. I think there were only 5 or so students who signed up and maybe just 3 or 4 of us who completed.

 

At the end of the course, the student takes a final, multiple-choice test online. Two tries at it. (By the way, I accidentally made a zero on the first try. Pulled the window up and then somehow screwed up the window and lost that “chance.” So, be careful.

 

My tip on the final exam is to pay close attention to the review questions that appear at the end of every lesson. Hint, hint.

 

That’s it. I found it interesting, useful, and engaging. That said, I HATE Moodle, which I find awkward to navigate. A lot of colleges and high schools are moving away from it for that reason. Plus, this appears built on an older version of Moodle. That’s just a quibble, though.

 

 Dale
N4HEY