Category 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

Technical Writing: The 60th Best Job in 2013

Some interesting statistics about the technical writing profession over the last few years. I’m surprised it has slipped so much in the rankings, although there is a lot of competition for jobs requiring technical skills.

Technical Writing ToolBox

Technical Writing is the 60th best job in 2013 Technical Writing is the 60th best job in 2013

Following the yearly tradition, Comcast released  a list of top 200 different jobs in the U.S based on five criteria: physical demands, work environment, income, stress and hiring outlook. The data for this report came from the Bureau of Labor Statistics and other government agencies in U.S.

Technical Writer was the 60th best job in 2013 though it slipped 23 ranks as it was the 37th best job in the same survey in 2012, and it slipped 34 ranks as it was the 26th best job in the same survey in 2011. Read the complete list of Careercast 200 tops jobs in 2013 here and the methodology of ranking here.

Technical_Writer_Rank_37_2012

Technical_Writer_Rank_26_2011

Average Salary of a Technical Writer in 2013

Average salary of a technical writer in 2013 is $65,178, up 3% from last year.

Salary_Increase_2013

Work Environment for Technical Writing job

Technical Writing received a score…

View original post 191 more words

Leave a comment

Filed under Technical 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”

Else

Cell.Value = “n”

End If

Next

End Sub

Leave a comment

Filed under Information Design, Technical Writing

Templates – The Fickle Shortcut

In the world of information design, templates exist for everything under the sun. Blogs, resumes, websites, everything under the sun has a shortcut that will, in theory, do the design work for you. All you have to do is plug in your information, and viola, all done. Templates are vital shortcuts.

Templates are also dangerous. Very very dangerous.

We use templates because we want to increase efficiency and maintain consistency. Fantastic! I agree, templates are great for that. The danger of templates comes in the form of preexisting templates. I’ll clarify with this bold statement: the best template, nay, the only template you should ever use, is the one you design yourself. For all the thousands of preexisting templates for whatever project you have, they will ultimately hamper your work for two reasons:

1) Preexisting Templates are Unoriginal

If you use the first template on the list of templates, your work will look the same as everyone else who chose the same template. You don’t have to create a resume or website so radical the likes of which no ones ever seen, but you will be far from unique. Originality stands out in today’s society.

2) Unsatisfactory Design Flaw

Everyone differs on the idea of a perfect template. Mainly because everyone’s individual needs differ. Your individual design ideas do not have the 100% eHarmony compatibility match somewhere on the internet. Although several templates may come close, one or more lingering small details will always haunt you during the entirety of your project’s lifespan. Your project will not be perfect if you are not satisfied.

Fortunately, an easy solution exists.

Note in my bold statement that I said “design” and not “create.” Templates, much like programming and website coding, don’t need to be made from scratch. The simplest way to create a template is to borrow ideas from pre-existing templates. By taking individual features you enjoy from multiple templates, you create a design that not only works 100% for your needs, but also looks a bit less cookie cutter. Just because you are selecting a template does not mean you cannot change it. The template police will not hunt you down.*

Being willing to get technical helps a lot. A willingness to edit a few simple fields (color, font, size) goes a long way towards change you enjoy. Resumes are easily tweaked in word/OpenOffice, for the blog/web page designer, a little CSS editing is all you need. A simple Google search points the way.

Templates are important, and taking some time to make one you are happy with will pay off in the long run. A happy template equals happy projects. 🙂

*Though you should not use copyrighted/protected work without permission, of course.

Leave a comment

Filed under Information Design, Technical Writing, Web Design

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.

2 Comments

Filed under Technical Writing, Writing