Technically Speaking

I’m pleased to announce the launch of my new portfolio website, located at www.paulpehrson.com.

In creating this new design, I used WordPress for the underlying functionality of the site. That gives me a lot more flexibility when I want to add or edit content. The previous version was static HTML that I designed, but was rather difficult to update.

You’ll notice that the WordPress theme used for the portfolio is similar in structure to the theme for this blog. That’s because they are both based off of Trevor Riehl’s Urban Sprawl blog. Back when I modified the theme for this blog, I contacted Trevor, and he sent me the files he had used for his theme. Then he gave me a lot of help in setting it up. I guess I learned, because I was able to set up my portfolio and customize it with out any help.

So, check out my portfolio site and get back to me to tell me what you think. I’m not using it as a blog per-se, despite using blogging software as the back end. I’m not allowing comments or pingbacks, and I’m not storing the information chronologically. In any case, if you want to comment on the design, or if you see an error that should be corrected, do me a favor and drop a line as a comment to this thread, or go ahead and use the Contact Me link on the portfolio site.

[Blog administrator’s note: I received the following e-mail from my supervisor today. It illustrates the trouble that can be encountered when you offshore documentation.]

My sixth grade son came home yesterday with an MP3 player that he got on trade. Surprisingly, he also got a CD with the software and device drivers and a user manual. In my house, I have to play technical support for all electronic gadgetry and computer-based equipment, so I started reading the manual. Granted, the MP3 player is not an iPod so I wouldn’t hold it to Macintosh standards, but below are a few choice excerpts from the guide that illustrate why our profession is important and that you should think twice about outsourcing documentation.

Do not use this device in the extremely thermal, cold, dusty, and watery circumstances..

More simple under FM interface, it only can do until the 3rd step and deleted is present channel. Please plug the USB cable out after the safe injection when delete the files in the computer. Otherwise it will show that the file has not been deleted.

Warning: This program can just be used by the person who is professional to repair this machine. This upgrade maybe can cause the machine can not work again because of the incorrect operation.

The normal MP3 user can be troubled by ‘Material Leakage’ and they would not like others to read themselves’ personal data’, they only can delete this ‘private data’ when their friends borrow their Mp3, which it cause big trouble.

Firstly, the user can see the format tool, select ‘Partition and password protect’ and select the suitable space for the password protected disk and then set up username and password, input ‘New username’ in inputting username, input ‘new password’ in the inputting password, after confirming ‘new password’, click ’start’, then it start to divide disk.

Remark: When connecting PC with player to transfer data, any operation is forbidden. During this period, do not get out the USB in order to avoid data transferring not completely or player damage.

There is some noise in the damaged MP3 and even can not play music, please assure that the file is complete.

Internet scammers get more and more sophisticated every day. Well over a year ago, I warned you on this blog about the trouble of what are called “phishing scams“. This weekend I’ve been inundated with e-mails that are purportedly from PayPal, warning me that my account has been flagged, and if I don’t follow a link given in the e-mail, my account will be suspended.

For a while, the phishing scams I’ve seen have been mostly bad imitations of e-mails sent by companies. If anything, they give a graphic with the institution’s logo, but not much else of substance. They are usually rife with misspellings, and at first glance are easy to see as being phishing attacks.

However, this PayPal email I got this weekend threw me for a loop when I first opened it. The e-mail address has been faked, but appears to be genuine. The e-mail uses valid links to PayPal’s privacy policy and even includes a link to a warning on PayPal’s website warning of phishing attacks.

Here is a picture of the message I received. Click on it to enlarge it.

When I examined the email further, I looked at the code and noticed that none of the images from the e-mail were stored on PayPal servers. Instead the images were being fetched from an external website that I won’t name here.

I also noticed that the link that is the “Click Here” link was redirected through Google’s webserver to an external IP address, to a subfolder named “paypal.com” If you weren’t paying close attention, you might think that the link went to a legitimate PayPal page.

Be careful. This is another attempt to get your account information to steal your money. If you ever get an e-mail from your bank, or other financial institution (like PayPal) be VERY careful if they tell you that you need to update your information or they will suspend your account. This is a very common method of phishing, but is not something your bank will usually do.

In any case, you should never click on the links in such messages. Instead, type in the URL of your financial institution manually in your browser’s address bar. If they legitimately need you to take some action on your account, usually the first screen you’ll see when you log in will tell you. But make sure that you’ve typed the URL in yourself. Never EVER follow links from your e-mail to your bank or financial institution.

There are a lot of scam artists out to get your money. There are a lot of ways that they are trying to accomplish it. You can protect yourself and your money by being VERY careful anytime somebody e-mails or calls you about one of your accounts.

If you get a message that you believe is a phishing attack, you should see if your e-mail provider supports “report as phishing.” (Gmail, for example does.) You can also send the message to your financial institution to verify that it is genuine. If its not, they will then be alerted that an attack against their clients is occurring.

Good luck, and be smart!!

The other day I got an e-mail from a developer who was writing about what he considered to be an under-exposed feature in the software that we develop. After explaining the feature, he finished with the following quote:

“[M]y sense is that we don’t advertise/capitalize on this.

“If we do already, dismiss this as coming from someone who doesn’t read [name of product] docs … “

I wanted to respond: “Yes it is in the manual already, and why aren’t you reading the documentation? You would waste less of your time trying to figure out the features (and then trying to broadcast them to the rest of the development group) if you would read the documentation first!”

Instead, I said, “Thank you for your comments. Information on this feature can be found on page [x] of the [guide name].”

Yesterday’s Salt Lake Tribune featured an article that relates to technical writing in an intersting way.

Apparently last October there was an incident at Hill Air Force Base, where a mechanic made a mistake that caused over six million dollars in damage to an aircraft’s engine. (The plane in question apparently costs over $200 million.)

A contributing factor was deemed to be a lack of proper documentation for removing landing gear pins after performing maintenance on the plane.

Here is a quote from the article:

“Investigators concluded that, while Air Force guides correctly instructed Raptor mechanics to install the landing gear pins before performing maintenance on the airplanes, there were no similar step-by-step instructions to ensure mechanics remember to take the pins out prior to clearing the aircraft for use. “

Who says documentation isn’t important? Way too often people talk about how expensive documentation is, and how there isn’t a visible return on investment for the money spent in the documentation department. I think a better question is “How expensive would it be to not document our product properly?”

Read the rest of this entry »