Tag Archives: technical writing

Technically Writing With Purpose

(Inspired by a writing prompt from The Daily Post)

One of the things I love about technical writing is the ability to write without having to resort to flowery language. While embellishing an email or newsletter is fun on occasion, I do not need to tell a story in a user manual. The only epic journey involved in furniture assembly involves a trip to IKEA  during a holiday weekend. My purpose in creating documentation often involves explaining something, and then removing half the words in the hopes that users will be less scared by a 50 page manual than a 100 page manual (do not be scared reader, I have graphics!) While I am exaggerating a bit, there is a reason you will never see this in a user manual:

You are advised to enter as many search fields as possible, for when accessing the seemingly infinite cosmos of data records, a broad search may bring thousands, nay, tens of thousands of results! While one could seek the aid of “alphabetical” or “recently added” sorting options, the daunting task of filtering so many records is certain to bring you to your knees after reaching page four of four hundred with not even the slightest hint of your beloved result in sight. So beware, dear reader, always enter at least two or three search terms, least you find yourself staring directly into the abyss.

Instead, I would write something like this: Enter additional search criteria if too many search results appear.

My purpose in technical writing is often to explain, not to reveal anything about myself. This might sound odd to the student tasked with providing original thought and justification, but even in creative writing a little brevity (and a little less preposition use) can go a long way. Your editor will thank you later.

Leave a comment

Filed under Technical Writing, Writing

The Computer Programming Humanities Major

When I first played with Excel in High School, I noticed an interesting little code feature tucked away in the macro section. People with experience in Basic programming can set up basic codes to perform macros and automated functions. Having at the time just completed a Visual Basic class I considered this to be a valuable tool to explore later on.

Then eleven years passed…

…and fast forward to last week when I found myself needing to perform a big spreadsheet edit. Put simply, for a column in a list of product rows I needed to insert a “Y” if the product in the row was over a certain dollar amount, and a “N” if it was less. Performing this task manually was a problem considering the spreadsheet consisted of over 16,000 rows.

After consulting the great and mighty Google I failed to find an obvious solution. Fortunately one tech help page suggested to someone with a similar problem to write a macro. I realized I could do something similar to automate the process.

Although I never got past basic Java (recursion killed me) before committing myself to the humanities, I remembered enough to come up with a basic If-Then statement which, after some tweaking, solved the problem nicely. Trying to remember Basic programming took some time, but it was much faster then trying to manually edit the spreadsheet myself.

Moral of the story? Having the “tech” in Technical Writer pays off.

For the record, the code I wrote is below. I’m pretty sure it was more complicated then necessary, but it worked!

Sub PriceCheck()

Dim Cell As Object

For Each Cell In Sheets(“mdd1”).Range(“AN2:AN16860”)

If Cell.Value > 500 Then

Cell.Value = “y”


Cell.Value = “n”

End If


End Sub

Leave a comment

Filed under Information Design, Technical Writing

Usability Testing – Avoid Front Page Overload

I learned many web design tricks in graduate school. Many of them seem rather obvious in hindsight, like putting the most important information at the top of the web page. After all, the more scrolling viewers go through, the less likely they will see all of the information on the page.

Web Design Rule #1: Web page visitors are very impatient. Don’t make them think.

The obvious solution to preventing scrolling is to eliminate scrolling entirely. Well, some scrolling is inevitable (I certainly cannot write blog posts that short!) but the key idea remains the same: put your key information front and center. Yet this is a double edged sword. While users should see the most valuable information first, cramming too much information in that limited initial space is very dangerous.

Since I happen to work in medical equipment sales, I’ll use two medical equipment manufactures to demonstrate this point. Take a look at Sklar Surgical Instruments. See anything interesting? That’s the problem, there’s too much interesting to see. This little three column layout is not only crammed with so much information, the information is badly prioritized. While the “what’s new” header in the left has some interesting new information, technically the middle and right columns also present new information.

In the end, the average visitor will have difficulty focusing on one section of the site. I admit the layout holds some merit for frequent visitors who want to quickly see what is new and exciting with Sklar. Yet this overload of “new” is quite unfair to first-time visitors interested in what products Sklar sells. That little yellow products link is not easy to spot.

Quick Aside: I’m not a big fan of three column layouts, though I admit it holds value for e-commerce stores. The company I work for, Medical Device Depot, happens to use one rather effectively. Then again I might be biased. 🙂

On the opposite end of the spectrum, Clinton Industries utilizes a very effective front page. New information cycles through the middle, while easy navigation to their products other details are easy to spot. You simply cannot get lost when looking for products when it leaves a trail of breadcrumbs for you to retrace your steps.

One more fun fact: serious usability testing utilizes eye tracking. Technology actually exists which allows testers to track where a person first focuses their eyes on a web page.

This is why a high Google pagerank is important.

Leave a comment

Filed under Technical Writing, Web Design

Unlearning the Essay

I’ve mentioned before that I’m not a big fan of the English Literature degree. Here’s another reason why I believe it inadequate preparation for most professional careers:

The 1,000 2,000 3,000 any number above 350 words essay.

Every English Literature class requires the essay, an overly long piece of writing that accomplishes three goals:

  1. Prove that you actually read the required material and pay attention in class.
  2. Prove that you are capable of coming up with a clever and sophisticated argument.
  3. Prove that you can analyze scholarly essays by using an overly complex system of citation (MLA, APA, or Chicago, pick one) and pretending to sound original.

These points hold merit in developing skills you will use in the real world. Yet the execution demanded by English Literature professors through this essay holds no merit whatsoever. An essay is a long drawn out series of black words on white pages. For scholars and professors this boring presentation is fascinating. In the real world, your thousands of words will go ignored.

Real-World Example: In the ecommerce world I work in, if I want to make my point to a customer I not only require a nice design, I also require brevity in words. I can, and often must write a product description in less than 350 words (one standard page). If I go beyond this length, prospective customers  must scroll down excessively, and I risk them losing retained information and interest in the product. Essays often require at least 5-10 pages, usually more on the upper levels of literature classes. I can count the number of times I’ve written something that long at work on one hand. And I can spare a few fingers in the process.

Whew, that was a long paragraph. Still with me? My point is, although commonly used and hated by students everywhere, the long essay is too frequently used in the college level. Students need to learn to be brief and make their points quickly. Their future bosses don’t want an introductory paragraph, thesis statement, support, and conclusion. They just want the thesis statement.

Incidentally, the essay also fails in a design standpoint as well. If I used any of the above formatting tricks in a paper in college I’d lose points. Yet they actually help me design my information, which technical writers need to consider when drafting a document. If technical writers designed all of their documents like essays, they would not get very far. My blog design is white letters on a black background for a reason.

Leave a comment

Filed under Information Design, Technical Writing, Writing

The Evolving English Degree (I.E. What you *can* do with a BA in English)

A long time ago (2007) in a community college far away (about 20 minutes from my house), I took a class trip to attend a Broadway production of Avenue Q. The opening number of the play was “What do you do with a B.A. in English?” Given that I was about to finish my associate degree in English I found this song highly amusing, partly because it was true…at the time the play debuted.

The truth is I’m not a big fan of the classic English degree. I, a holder of a B.A. in English, should clarify. I hate the English Literature degree. When I was finishing my community college days (I was a “attend community college for two years then transfer to a four-year school” student) I realized that, while I enjoyed reading old books and writing papers on them, I was not getting any real world skills. Unless you want to become a literature professor, knowledge of Chaucer and Melville will not help in a workplace setting. I wanted to continue developing my writing skills; however, I did not want to spend my valuable class time sitting in a circle talking about old books. I could attend a book club instead and save thousands of dollars.

Fortunately for people like me, colleges are seeing the need for non-literature based English classes. Writing as a professional skill is actually rather critical in the workplace. Mainly because of the following adage:

When writing skills are needed, it is often a lot easier to teach a writer (technical/business/niche workplace skill) than it is to teach (technical/business/niche workplace) people how to write.

The University of Maryland Baltimore County (UMBC) happens to be one such college. Their English degree consists of two mutually exclusive tracks: an English literature track, and a communications and technology track which develops skills applicable for both print and electronic media. Media students will use in the workplace. Going to UMBC and getting an English degree on the latter track was an easy choice for me. I found writing about the latest trends in technology infinitely more useful than writing about old books. Colleges all over the country are implementing similar additions to the English major. Additions reflecting the need to develop writing skills that directly apply to workplace settings. Considering the new challenges and opportunities in image brought forth by online and  social media, these additions are critical.

So when I say I have an English degree I mean just that – an English degree, not an English Literature degree. My workplace toolkit is not The Divine Comedy. I actually don’t have much classic literature experience at all. The English degree I hold is adaptable, it allows me to write my way into a job. Literally. My first real (and still current as of this writing) job after college involves maintaining a website for a medical device business. Although I did not know anything about medical equipment when I started, within a month I knew everything I needed to know because of the writing and analytical skills I developed. Now I can tell you how to hook up an ECG, or the difference between a otoscope and opthalmoscope. And all the while I write to convince doctors and healthcare professionals that they should buy this cool equipment from the company I work for. Obviously my medical experience does not permit me to perform an exam or open heart surgery. I am not a highly trained healthcare professional that attended years of brutal medical school. I simply fill a niche, yet essential role.

And there are tons of those roles out there. It is what technical writers do.

That is the awesome thing about being a technical writer. I can adapt. I wield a mean pen and do not need to quote ancient authors. I am not sure where my future careers will take me, though I am confident that I will be able to write my way into an enjoyable position. I acknowledge that on the grand scale of college degree usefulness English Literature is not bottom of the barrel. However, I will argue that an English Literature degree is archaic in today’s digital age. The English degree will always continue to be relevant as it quietly adapts to a constantly changing world. Eventually, the world will begin seeing this.


Filed under Technical Writing, Writing

Defining the “How” in “How can I help you?”

I discovered an interesting post from one of the technical writing blogs I follow during my Sunday morning blog catch-up. Technical communicator  Shweta Hardikar recently wrote a blog post pondering “embedded help” or, helping users solve problems without calling it help.

Although programs are constantly evolving and taking advantage of multimodal interaction, one important question remains: “how do I use this program?” Users want immediate results, they don’t like to read through 50-page user manuals and guides. Looking up answers takes the user outside of the program experience, ruining the immersion. And honestly, how many people actually bother to read or even keep the user manuals that come with programs? Although companies are getting smarter (and eco-friendly) with user manuals by storing them in the program or on a  CD, the fundamental problem of having to go outside the program remains.

That is where embedded help comes in. Embedded help integrates the help directly into the application instead of through an outside source. This often takes the form of text that appears directly on the application, or via an easily accessed button. Not sure what a particular option does? Instead of making the user look up that bulky/poorly accessible user manual, offer a button labeled “help” or “?” if you don’t like the idea of using the word help.

Not every section of a program requires embedded help. Indeed, the golden rule of maintaining simplicity should remain in effect. The key behind using embedded help lies in anticipating where the user might have a question. A handy accessibility rule for programs and vital for web navigation, especially if you are running a business.

When I create product pages for Medical Device Depot my supervisor constantly stresses the importance of clarity. I always have to anticipate where the customer might experience trouble when ordering a product, and provide necessary clarification through embedded help. If I don’t include this explanation then the best case scenario is that the customer calls and asks, an unlikely possibility. At worst, the customer won’t buy the product, or accidentally order an incorrect product. Suffice to say, none of these scenarios are particularly desirable.

Here’s one example: when purchasing an emergency drug kit the customer must input additional information. I use popup help buttons to help clarify necessary details just in case the customer is uncertain. This not only saves time and trouble, it may prevent the loss of a sale due to lack of understanding.

Examples of how embedded help directly assists a customer. (Click image to see it in full size)

Leave a comment

Filed under Technical Writing, Web Design