Graphic Design and the Technical Communicator

“I do neat, not pretty.”

That’s what I tell all my visually minded friends and coworkers. My idea of doing something different is changing up the fonts on the standard Word templates, so I’m obviously not the guy you go to if you want something visually awe-inspiring. And, mercifully, I’ve been fortunate enough to work in organizations where I could work with a graphic designer.

So what could I possibly have to say about graphic design in a technical communication environment? More than you might imagine, actually.

What is a technical writer doing graphic design for, anyway?

In one- or two-person proposal shops, you don’t always have the luxury of having a graphic designer on hand to help make things neat and pretty. Take heart–if the project were that demanding of graphics, the company/department would hire one or bring one in for a special project. But for regular documents, such as correspondence, reports, or proposals, there aren’t always a lot of pictures, but there is a need for some graphic design.

Text Formatting

U.S. Government proposals usually have a set format:

  • 8 1/2 X 11 inch paper
  • 1 inch margins all around the text
  • 12 point font for body text (typically Times New Roman, but if not, you can try something else like Book Antigua, Georgia, or Calibri)
  • 10 point fonts for captions
  • Headings for individual sections

Given all these basic features, it’s important to be acquainted with the basic formatting features in Microsoft Word–still the default word-processing program for much of the U.S. business world. These basic functions, then, include setting margins, fonts, and headings.

Also, if you’re not yet acquainted with Styles, I highly recommend working with them. Styles are automatic templates for things like body text, heading levels (Heading 1, Heading 2, Heading 3), titles, and captions. They save you the trouble of having to reset the font size, color, boldness, italicizing, etc.

As an extra bonus, MS Word’s Table of Contents function generates an automatic TOC based on styles. Therefore, if you’ve done your heading styles correctly, all level 1 headings will align to the left margin, level 2 headings will be indented one notch, level 3 headings will be indented another notch, and so forth. If you’re not careful with your Styles function, you can find entire paragraphs recreated in your TOC. (To fix that, go back to the original paragraph, select it, and change the Style back to “Normal,” which is your default body text style.)

Some general font guidelines that I follow:

  • Make your heading fonts distinct from your body text to make the page more easily navigable for the reader. However, don’t use MORE than two fonts (also called typefaces) in a document.
  • There’s ongoing debate about this, but I prefer using sans serif fonts for headings and serif fonts for body text. (See the image below for what this means.) I’ve seen studies that show sans serif fonts are more readable for long periods of time, but I know I get a headaches reading whole pages with nothing but Arial on them. Again, when in doubt–especially on a proposal–stick with slightly boring Times, Times New Roman, or Cambria serif fonts for body text. Typical sans serif fonts for headings include Helvetica, Arial, and Calibri. If you have a in-house style that has more fashionable but still customer-acceptable typefaces, by all means, go for it!
  • Avoid underlining in headings or body text unless told to do so–usually by an academic institution or specific magazine publishers. Use italic, bold, or both.

Page Layout

Okay, so you’ve gotten your fonts and styles to behave as you want. You’re all set, right? Not quite.

One thing to pay attention to is spacing (that is, the amount of space between lines of text in the same paragraph, space between paragraphs, and space between headings and paragraphs). Spacing between lines is often measured in points. 12 points is approximately equivalent to one full row of regular text. You can fully align your text along the left margin if you have a full 12-point gap between your paragraphs. If you have zero points between lines, paragraphs should be indented .25 or .5 inches.

You don’t want to crowd your text all together, so standard single spacing usually works just fine (again, with your paragraphs indented). If you’re printing something that others need to mark up with the dreaded red pen, you might go to 1.5 or double spacing.

Another item that I argue with engineers about is text alignment–left justified (“ragged right,” as this post is using) or full-page justified, where text stretches from margin to margin. My engineering friends prefer full justification because all the texts align with the margins; I favor left-justified because the spacing is consistent. Bottom line: unless you are given a guideline, there is no “rule” about justified text–just keep things consistent.

Last thing: don’t use Comic Sans for official documents. I’m not entirely certain why, but Comic Sans is the Rick Astley of fonts, and your graphic designer will lose her mind if she sees it on the page. Just trust me on this.

Graphics

Proposals sometimes get very few visuals, either due to page constraints or lack of time and money to develop the images. If you’ve got the time and the space, however (and graphics are permitted in the proposal), you should take the time to add them. Graphics, like white space, break up the page and give the reader a visual point of focus. If “a picture is worth a thousand words,” then it’s also important that your graphics help tell your proposal “story.” This is especially important if you’re proposing a complex piece of equipment that is difficult to describe.

A note on captioning graphics…one of my managers in the defense industry reminded me early in my time there not to just post a picture of a horse (for example) and label the caption, “A horse.” Captions should add some value, either explaining the graphic (“Control panel, top view”) or explaining why the subject of the graphic is important or interesting (“The Ares I-X test vehicle is the tallest launch vehicle NASA has flown since 1972″).

FSE Sep Test

This image, while visually interesting, doesn’t require a full-page treatment but could be inserted on one side of the page.

Images should be cropped and sized to best fit the page. A highly detailed graphic, such as an image with embedded text or multiple steps, could fit across an entire page width.

Ares I-X Flight Test

A detailed graphic like this would best be displayed across the full width of a page, or perhaps even given its own page!

Parting Thoughts

Again, the point with graphics and layout–especially in a proposal–is to make your pages visually interesting, neat, and readable. It can be easy to get carried away with lots of colors, fonts, and borders. If you’re showing off your company’s graphics capabilities, more power to you. However, if your goal is to tell a clear, understandable story, it’s better to err on the side of minimalism: two to three images per page, one big graphic, or a full page of smaller graphics–aligned in a way that doesn’t distract throw off the alignment of the text. If you’re creating a marketing brochure, you can of course get more creative with layout, colors, or text alignment. Visual appeal is useful for telling the story you want to tell; but your visuals shouldn’t distract the reader from what you’re trying to say.

Posted in audience, documents, graphics | Tagged , , , , , , | Leave a comment

Finding Useful Content on this Blog

I’ve been working on making this blog more useful to my intended audience—new or current technical communicators. I realize there are tags for various topics, but maybe a summary entry like this will help you find the “best of” my thoughts on a particular subject. Fair warning: this list does not cover every entry I’ve ever posted, so dig around as you see fit.

Thinking About Tech Writing

These essays are my attempts to explain the mental processes behind how I organize and write content.

Tactical Questions

These are on the practical side of things—how-to guides for specific work tasks.

Job Hunting/How to Get a Tech Writing Job at NASA

This has become a recurring theme, so I might as well put all my thoughts in one place. Some folks have emailed me wanting advice on getting any tech writing job while others have asked for advice on getting a job at NASA, which is a slightly different question. I’ve also included here a couple entries on potential future career outlets for technical communicators.

All the Things They Don’t Teach You in College

This is the advice I wish I’d gotten when I was in college.

Random Silliness

These are fun, but they don’t quite fit any of the other categories.

Posted in blogging | Leave a comment

Marketing Language in Proposal Writing

Proposals are marketing documents. This should be something everyone knows, but you’d be surprised how often that knowledge doesn’t result in effective marketing language in a proposal. Below are some thoughts on how to ensure that your proposal readers are getting the most “bang for the buck.”

Showcasing Your Market Advantages

Most requests for proposals (RFPs) to the federal government require the following sections in their responses:

  • Technical Approach
  • Management Approach
  • Past Performance

In each of these sections, you have the opportunity to not just explain what your widget/process is, but kick up the language a notch by including details or support statements that show why your organization is the perfect entity to solve a particular problem.

Technical Approach

The technical approach section is where you describe your solution to the RFP’s problem. Whether Agency XYZ needs a part, product, or system, the customer is expecting the best product/service they can get for the lowest price. Marketing language here would focus on why your solution is best for the customer. The key is to argue from your strength(s):

  • If your product is a proven, known commodity, you emphasize its reliability, industry acceptance, or availability.
  • If your product is less expensive, you emphasize cost.
  • If your product is more efficient than others, you emphasize the ability to produce multiple activities quickly, operate easily, or reduce consumption of resources (money, part count, time, energy)
  • If your product’s greatest value is its advanced technology, you want to emphasize the benefits its new approach might convey (faster, better, cheaper–pick two). However, this approach also might need to include some sort of hedge to calm fears about using  an unproven product. If your product or approach are new, you can mitigate that risk by pointing the customer to your superior performance or staff in the Past Performance or Management sections.
  • If your product and all of its competitors are nearly equal in technology, quality, or capability, you need to emphasize some other aspect of your organization to help you stand out, such as the quality/experience of your people, your level of service, your past history with the customer, or price.
    (Note that I put price last. If “lowest bidder” is the primary consideration, by all means, go there; however, Section M of a typical federal RFP will tell you what the most important factors are in an award decision. If technology is the customer’s #1 priority, you want to talk about why your technology is superior. If price is the customer’s #1 priority, you will probably need to provide more detail in your cost proposal to show that you have accounted for everything and that your lowest bid is, in fact, realistic.)
  • Some managers will employ “ghosting” in their proposal language. This is where, if you know your competitor(s) and how they approach things, you make slight digs against their approach by explaining how your approach is superior to process X (without naming your competitor, of course). Just be certain that your approach is superior. I’m not a huge fan of this tactic, but then I don’t like negative advertisements in elections and people who use them still get elected, so if you think it’s necessary and appropriate, ghost away.

Management Approach

This is where you talk about the people who will ultimately do the work. You might be required to provide a paragraph or full resumes of your best and brightest. In either case, you shouldn’t just copy and paste from an existing resume or bio and consider your work done. Your team members’ background information should be customized to emphasize the types of relevant experience they have for completing the task you’re proposing.

I’ve observed over the years that a company’s management approach also has become increasingly important. This is especially true in Department of Defense or NASA, where more firm fixed price (FFP) or performance based contracts are being issued. In both cases, the government doesn’t always know what product/service it wants, only what outcome they want and how much they’re willing to spend. In that case, a company’s management approach becomes paramount: the customer will want to know who is doing the work, how they will be organized, and what processes or procedures are in place to ensure that the work is delivered as promised.

Because programs and companies can vary greatly in size and scope, I won’t attempt to name all the different types of management or team structures here or suggest which type will work for which situation. However, as with your technical section, the important marketing-language rule here is to focus on your strengths:

  • Experienced staff – An advantage when the customer is interested in reliability and in-depth knowledge of their operation; not always an advantage when the customer is looking for new thinking.
  • Relationship with the customer – An advantage if you are familiar with how an organization runs and are on good terms with them; not an advantage if your relationship has been contentious or if you have had performance problems.
  • Educational background – Having a lot of team members fresh-out of college is an advantage in scientific or high-tech proposals where new thinking is expected; and, too, many scientific projects require Ph.D.-level educations to handle the work.
  • Team structure – Is your team “lean and mean” to ensure low cost and quick communications or is it “deep,” with enough varied personnel to call upon in case you need “bench strength” for specialized problems or surge situations? Again, the low-cost alternative doesn’t always win, especially on high-cost, high-risk programs.
  • Supplier/subcontractor base – This one can get overlooked, but if you’re a prime contractor and depend on a lot of subs, the quality of that team matters. Also, if your team consists of multiple categories of small businesses (8(a), Minority Owned, Woman Owned, etc.), the customer can ensure that you and they get credit for getting work to those types of companies.

Past Performance

This is simply your track record to prove that you’ve done a specific type of work before or work of similar difficulty or scope. The marketing angle here is pretty straightforward, as you want to point out the similarities between your past work and the proposed work as well as how well you’ve performed on those projects. You have done well, haven’t you? Okay, maybe one of those projects wasn’t your company’s best experience. If you have enough experience, don’t include that customer and use another. If you don’t have any alternatives, what are you doing to fix the situation? As in most situations, don’t lie about your past. Don’t claim to do things you haven’t done or make a connection between past work and the proposed work if it doesn’t exist.

All that said, again: play to your strengths. In situations where the government is asking for something risky and high-tech, they will rely as much on your past performance as technical approach because past performance can be verified.

  • Cost: If you met your cost estimate or came in low, that’s a good thing.
  • Schedule: If you consistently met your proposed schedule or delivered early, those are good things.
  • Quality: If your delivered product service required very few “do-overs” due to workmanship or service issues, by all means, note that.

Do you know how you stand with your customer(s)? Do your front-line and project management teams have ongoing, positive relationships with them? Are you delivering the product or service they expect? Do you send your customers satisfaction surveys quarterly or annually to get some hard numbers? If the answer to all of the above is “no,” depending on your past performance can be risky because a) you don’t know what your customers will say, and b) the awarding agency will follow up with your references to determine if what you said matches the customer’s reality.

Concluding Thoughts

The “marketing” aspect of proposal writing is the messaging you include throughout your proposal document. Therefore, as with any marketing product, you want your messaging to be consistent. This can be challenging if you have multiple people writing the proposal, in which case it’s good to have a kickoff meeting to discuss your themes and messages before everyone runs off and starts writing. For example, if the people writing the management section are convinced that the strength of your proposal is the quality of your machining, your customer will be confused if that machining isn’t mentioned in the technical section. Your strengths also should be highlighted in your Executive Summary so that the customer knows what to expect when they dive into the details. You don’t just want to explain what you do, you want to show why you do it better than anyone else!

Posted in documents | Tagged , , , , | Leave a comment

Health Tips for the Tech Writer

In one of the Peanuts cartoons, Charles M. Schulz has Charlie Brown say, “My mind and my body hate each other.” It’s a typically Charlie Brown-ish moment, and as a brain-focused non-athlete for most of my life, I related to it for a long time. The problem with this mind-body “argument” is that it really isn’t helpful. You don’t “have” a body, you are a body, and if you don’t take care of your body, that mind you use to crank out glorious prose won’t be much use to anyone, especially you.

All of this came into sharp focus this past year, when I helped my friend Dede (D2) write a class on lifestyle management for obesity patients at Florida Hospital. Without going into exceptional detail, the important overall message of the class was that four major factors play into an unhealthy body–nutrition, exercise, sleep, and stress–and if you aren’t paying attention to all of them, you’re going to end up with an unhealthy body (and thus an unhealthy mind). D2 and I tried to tie the classes together by cross-feeding the impacts of one factor on the others into each class. For example, if you’re under stress, you’re probably not sleeping well; lack of sleep can reduce your desire for exercise and can create metabolic changes that cause you to crave unhealthy foods. And so forth.

To use an engineering metaphor, your body is a system, or really a system-of-systems. Something that you’re doing (or that’s being done to you) in one part of your body can and will eventually affect the others. As a result of some behaviors–overloading on soda, smoking, eating a lot of junk food, not exercising, etc.–you can end up with several problems, which being overweight can make worse, such as diabetes, heart disease, back problems, and even depression.

Tips

Again, without reciting the full 13-week class, I’d just like to offer some general thoughts on the four areas of the class that I applied to my own life–perhaps you’ll find them useful as you maintain your own “system of systems.”

Nutrition

The best things you can do for your diet are to mind your portion sizes and to reduce your intake of restaurant foods and processed foods at home. American restaurants, in particular, have become infamous for distorting their portion sizes out of all sense of reality. The thing with processed foods (most of the things you find “in a box”) is that they have a lot of preservatives and not a lot of nutrition in them. You need to focus on eating “natural” foods. And by that I mean vegetables, not processed vegetables; actual chicken/fish/dairy, not substitutes, whole grain instead of white bread. Focus on the foods on the perimeter of your grocery store–the bakery, produce, etc.–rather than a lot of the long-shelf-life stuff in the aisles.

Exercise

Seriously, do some sort of physical activity that gets you moving. I walk a lot because I’m not particularly graceful at team sports or even on a bicycle, but I’ve also been going to a gym for nine years. (Oh yeah, you need to do this in conjunction with eating less/better foods–otherwise, you’re not going to accomplish a whole lot.) If walking doesn’t work for you, try yoga. Or Pilates. Or you can wash your hands of Pilates and try something else. But the most important thing is to get moving–like 30 minutes a day. Once you’ve started that habit, you can move into more aggressive activities like weightlifting or “cardio” (which is a code word for jumping around and sweating at speed for a good stretch). I go to my local YMCA, where they have trainers to help you set goals, suggest exercises that might work for you, and help you set fitness goals.

Sleep

This one surprised me, but this past summer I started losing energy by mid-afternoon and seriously needed a nap–anything from 20 to 45 minutes or more. A few things were happening, as it turns out, but one of them was sleep apnea, which was brought on by being overweight and stressed out. Lack of sleep was also affecting my mood. My shift to better eating and more exercise helped with the weight, and those oh-so-sexy Breathe Right strips helped me breathe better while I sleep. Result: no more energy crashes, not as many naps, and a better mood. Far be it for me to argue with my own body.

Stress

You know better than anyone what’s causing stress in your life. Maybe it’s your work situation, maybe it’s finances, maybe it’s personal matters. In addition to not being fun, stress, too, can cause you to gain weight through a variety of metabolic changes that take too long to explain here. Whatever things are causing you stress, you need to take action to fix them or recover from them. In addition to bringing yourself up from things that are dragging you down, it helps to do things that uplift you and make you feel relaxed and happy–preferably something that doesn’t involve food or drink. If massage doesn’t work for you, maybe a hobby will work or reading or praying/meditating or just hanging out with friends or family (unless they’re the ones causing you stress!). Me, I pick up my Annual Pass and go walking around Walt Disney World. To each his/her own.

I won’t tell you that after taking action on all of the above that I am now an Adonis with six-pack abs and 7% body fat (as I told my trainer at the Y, “I’d settle for a couple of cans”). Quite frankly I think it’s an accomplishment that after six months I no longer leave the Y feeling or looking like I’m going to die. I’ve cut out some major junk out of my diet (no more Diet Dr. Pepper or hot wings, alas), made a determined habit of exercising, found constructive ways to clear stress from my mind, and managed to get through most of my days without the need to crash for a nap.

And, again, I think the “systems approach” to health is important because it helps me take a balanced approach. It’s not just a matter of going to the gym every day and working out like a crazy man to “fix” everything. It’s a slow, steady, lifestyle change that encompasses what I eat, what I do with my body, how I rest, and how I relax. In short, it’s about taking care of the whole person, mind and body.

Posted in personal | Tagged , , , , | Leave a comment

Dressing for Success–Male Tech Writer Edition

I’ll preface some of this so I don’t come across as a killjoy: I hate wearing neckties. My most comfortable clothing combination is a Hawaiian shirt, jeans, and gym shoes. However, I’ve learned the social necessity of dressing to fit the occasion and conforming with the requirements of the society in which I travel. Sometimes I’ve learned the hard way by not dressing appropriately, so maybe you can learn from my mistakes. If you’re not a conformist, this blog entry isn’t for you. However, this is advice I wish I’d paid attention to when I was younger.

Let’s start with an obvious but unspoken truth: people judge us by the clothes we wear. A while back, I attended a social gathering that was described as “semi formal.” Much to my dismay, I saw everything from jeans to t-shirts.”Casual Friday” has degenerated in some cases to flip-flops and t-shirts. You don’t have to be “that guy.” In fact, I recommend against it.

If you plan to spend all your time working from home and plan to never use Skype or a video chat system, then this advice doesn’t apply to you. If you plan on interviewing, meeting with clients face to face, or attending social gatherings, perhaps you’ll find this useful.

Basic Definitions

Casual
I don’t have to explain this. Casual is what you wear at home, when you’re off duty. It’s a casual country. The challenges arise when we face occasions where we are expected to go out of our way to look more presentable.

Business Casual
This varies from place to place, but in general this means Dockers or other cotton pants (not jeans) and a golf shirt or collared shirt with no necktie, plus black or brown shoes and dark socks. Jeans are allowed more often in the office, but if a social gathering specifies business casual, they’re generally a no-no.

Semi-Formal
This means a jacket and tie. Dockers are still permissible, and your pants and jacket don’t have to be the same color. Again, dark socks, dark shoes, no sneakers. This is also usually acceptable for job interviews or client meetings unless the client or event specifies otherwise.

Me Greg Rick and othersFormal/Business
If an event specifies formal attire, this means you’re wearing a suit–matching jacket and pants, maybe a vest thrown in, depending on the current style and your preferences. Ties can be colorful, and you can usually get away with one membership pin of some sort on your lapel. If you’re working and a suit is required for the job, you can usually lose the jacket if you’re away from the crowd or out of sight from the boss. If you can afford it, I highly recommend going to Men’s Wearhouse or some other store to get a tailored suit rather than something off the rack. I’m allergic to flowers, so I keep them off my lapel, but that’s always an option. If you feel like getting fancy (and if you go to Men’s Wearhouse, they’ll probably suggest it), you can get a pocket handkerchief to match the color of your shirt.

20110522_111139__MG_9725Black Tie
This is a specific variation of formal, in that you have to wear a tuxedo, usually black, but not always, with a vest (optional) and a bow tie–again, black, but fashionistas would probably say you can get away with something else. If you’re traveling with a date, you can do a subtle color matching of your shirt or tie with whatever they’re wearing. One thing you might consider buying for yourself is your own tuxedo and have it tailored properly. If you’re doing things right, you only have to buy one and it’ll pay for itself after 2-3 events (you can buy one for ~$200 whereas it costs about half that much to rent one with the pants and shoes).

The Most Interesting Space Geek in the World

White Tie
I have never attended a white tie event, but my general impression is that the look is white, down to the socks and shoes, and can include a long white tuxedo with tails, top hat, and white gloves. White tie events are for things like formal events at the White House. If you get to go to one, let me know what it’s like and how the dress code pans out.

What if they don’t specify the dress code?
For gosh sakes, ask. I showed up at a NASA Flight Readiness Review (FRR) in business casual gear (golf shirt and khakis–you know, Jake from State Farm). I arrived to find myself surrounded by suits. FRRs are considered formal business affairs because you or your organization is signing off to the agency that yea, verily, you believe the rocket is safe to launch. Ooops. Needless to say, I hid in the very back corner of the room, closest to the door so I could escape as soon as possible. Lesson learned.

On the other hand, there are informal social occasions that don’t require the full tux and tails. Depending on how well you know the people involved and the location of the event, it’s still better to slightly overdress. An employer of mine splits the difference for social events, wearing a blazer and turtleneck rather than a tie. I’d say “Use your common sense,” but I’ve seen too many examples of people who don’t have it to offer that advice. When in doubt, ask a friend. Or, in my opinion, a lady friend. Or a sister. Someone whom you know has your best interests in mind.

Other Basics

Here are some basics that I shouldn’t have to include, but good grief, I’ve seen enough silliness that I must now include them:

  • Maintain good grooming: shower, comb your hair, shave or keep your beard trimmed neatly, trim your fingernails. If you wear your hair long (like a young employee of mine did), consider a pony tail so it doesn’t distract.
  • Make sure your clothes are in good condition: don’t wear things with stains or holes in them. If your suit is wrinkled, make sure that you get it to a dry cleaner a week before the event so you have time to have it pressed.
  • Don’t forget to wear a belt. Or suspenders. Pick one, but wear it. (This one comes from my father who zinged me on that more than once.)
  • Don’t overdo the cologne.
  • Learn to tie a necktie. Learning to tie a bow tie, while a nice thing to know, is not completely necessary, as they sell more pre-tied bow ties than full-length ties. Of course your circumstances could vary.

Okay, I’m done nagging. Relax. If you make a fashion faux pas, it’s not the end of the world. That said, it can be a situation that causes others to question your judgment. Why? Because in some circumstances if you can’t make the effort to learn and match a simple dress code, people will wonder if you can keep your work products in order. It’s superficial and ridiculous, but it’s human nature.

Guidelines for Women

I will not even attempt to decipher women’s fashion requirements. Best of luck to you.

Exceptions

I was going to titled this section “Exceptions to the Rules,” but really fashion is about taste, and tastes change. My suggestions above might be considered too bourgeois or informal for some people, too stuffy for others. And there are folks like my former employer who are just anti-necktie and manage to get away with it. I’m the sort of fellow who gets taken aside and asked if I didn’t read the invitation correctly. So maybe you can brazen things out and wear high tops with your tuxedo. Bully for you. Meanwhile, if you’re not a particularly flashy dresser but don’t want to embarrass yourself, then perhaps my advice will be of some use to you.

Posted in personal | Tagged , , , | 1 Comment

Finding the Information You Need: The Magic of Keywords

I have a friend at NASA who is terrified of the way I use a computer. He’s convinced I’m a member of the Borg collective because of the speed with which I find information on the internet. And while I like to tell him that “resistance is futile,” there’s really no big secret to finding things on Google or any other search engine.

It all comes down to keywords.

Life Before Google

In the dark ages before Google (that’d be all of 10 years ago), a lot of research was still done in “the stacks,” those long, quiet, dusty rows of library shelves filled with dead-tree things called books.

My introduction to in-depth searches of the library came in a college course on research methods, and it served as an excellent basis for researching in the digital age. (I’ll pause briefly to thank Dr. Franklin Court at Northern Illinois University for his most enjoyable education on this topic–he managed to make researching and, in a separate class, Charles Dickens interesting and worthwhile–two things I would not have believed possible.)

Why on Earth would anyone subject themselves to the Reader’s Guide to Periodical Literature? To write papers, of course. You get a notion for providing a new insight into, say, J.R.R. Tolkien’s The Silmarillion. You read some passages that reminded you a great deal of John Milton’s Paradise Lost. You want to write a paper to prove that yes, in fact, Milton served as one of the sources of Tolkien’s back story to The Lord of the Rings. How do you go about such a preposterous quest? Aside from the usual reading of the two works themselves, you have to look for what critics might have said about the two works. Does anyone else have the same theory you did? Some Ph.D. who’s already published? Maybe. But how do you prove it?

You look for keywords. You’re not going to find full-sentence references in the index that magically answer your question: “Yes indeed, third-year college student: here’s how The Silmarillion borrowed from Milton’s Paradise Lost!” Instead, you have to look for shorter subjects: you go into a critical edition of Paradise Lost and see if you can find individual words in that book that match words you’re trying to write.

Before there was “Googling,” there was indexing. That’s a skill that still exists, but is often taken for granted by people unaccustomed to textbooks: someone takes the time to read a text and identify specific topics within the text so that the reader might find them more quickly. What indexing is doing is identifying the most important words related to a topic you’re studying. You find a lot of those words in the chapter names, headings, and subheadings of your basic classroom textbook. Indexes are ways of providing you with a mental map to other fields of knowledge. If you use the right “magic words,” you can cut down your search times considerably.

Keywords are all about concepts and context. Rather than look for specific terms, you’re sometimes better off thinking descriptive. You’re not going to find Lucifer (later Satan) in The Silmarillion any more than you’ll find Morgoth (previously Melkor) in Paradise Lost. But you will find the concept of the “fallen angel.”

Today, if you do a Google search, you’ll get 649,000 results. In the paper-based world, there might have been that many sources, but you wouldn’t find or want all of them; plus, you only had a week to research and write the paper. So then I have to narrow down my search a bit by looking for other keywords: power, kingdom, hell, et cetera. As I dig through the critical texts, I’m able to sort the wheat from the chaff and find which sources include more common elements than others. This connecting of keyword “dots” is essentially what search engines are doing.

Today, of course you can throw all those keywords into Google and find a paper by one Zach Watkins covering this very territory. Nicely done, Zach. And lucky you: you got to do it the easy way.

[Note to Students: I learned later that Tolkien hated literature prior to 1500, so my paper was probably a bunch of drivel. But what the heck, I had enough coherent sources and made a convincing argument, so I got the A.]

Searches in the Real World

Okay, I used my college paper example as a fun way to work through the paper-based logic of keywords. In reality, you need specific images or sources that back up something you’re saying for a research report. The important thing to do when narrowing your search is to focus on the nouns. Let’s say you want to find out what percentage of the federal budget is spent on healthcare.

I’ve already provided you the keywords you need: percent federal budget healthcare.

Or say you want to find a video with a particular quotation that you like. You can go to YouTube (a decent source for video clips, along with Vimeo.com and others) and do your search from there. For instance, my sister was heading off to the dentist the other day to take care of my nephew’s tooth, which had been knocked out. I input “Dune the tooth” into YouTube’s search engine, and came up with this:

But let’s say you don’t know what you’re looking for. Again, it comes down to the nouns or concepts in your query. It really comes down, sometimes, to typing a single set of words that, when combined, would match the gist of your query. A friend of mine is convinced that “everything is on the internet.” He might be right. It might not make sense and you might not get the results you want, but the results you do obtain might help you clarify your quest.

And as you go forth, easily typing things on your computer, give silent thanks that you don’t–unless you’re in a college research methods class–have to create your own index or wander the stacks doing things “the hard way.”

But

Posted in documentation, documents, research | Tagged , , , | Leave a comment

Thinking Like an Engineer, Working Like a Writer

This blog was inspired by a response to my blog regarding my readers in India. One reader, Amruta, wrote that she appreciated my help on thinking like an engineer. First off, thank you to Amruta (and the rest of you) for reading! I’ll try to make this entry as useful as possible. I’ve covered some of this ground before, but maybe other thoughts will occur to me as I go along.

A while back, I talked about the fact that I prefer writing about engineering rather than science. Part of this preference occurs because I’m fascinated by gadgets, and part of it is because engineering is inherently a human activity. You’re not trying to figure out how the universe works but how a human-designed tool (hardware, software, or process) does or will work. If there’s a human purpose in mind, you can get someone to explain it to you. In science? Not so much.

When I’m approaching a new engineering topic, I have to start with what I know. That might be quite a lot in the case of rocket propulsion or space architecture; it might be depressingly little, as in the case of writing about automobiles or biotechnology. Regardless of my starting point, the most important thing for me to understand is: what is this widget/technology supposed to DO?

I’ve written elsewhere that often I use an airline route structure in my head to help “connect the dots” of my content to places I’ve already been. “Oh!” I think as I read, “This connected to X.” Or I’ll find an analogy in the work: “This part of the system functions like a radiator.” Or I’ll fall back on actual technical knowledge of the physical universe: “This widget is dissipating heat.” The most important tools I have at my disposal are science/technical knowledge, analogies, and logic.

Scientific/Technical Knowledge

Science, technology, engineering, and math are not for everyone. People dislike them or aren’t interested in them for any number of reasons–bad at math, perceived lack of socializing (or social value), bored by numbers, impatient with lab work, etc. As it happened, I grew up with an interest in science and engineering, which was helped along by parents, teachers, and my own reading–science fact and fiction. I had enough interest to be fascinated by what technology could do, but not so much interest that I wanted to do the work myself. As a result, I’ve learned just enough to be able to write about rockets, spacecraft, etc., to be useful but not so much that I’m dangerous (trust me, no engineer with a grain of sense lets me touch the rocket). I write about engineering topics for non-engineers, for the most part (politicians, legislative staffers, and that ever-elusive “general public”). If I have to write for other engineers, I need to delver further into the weeds and learn more vocabulary, acronyms, and actual science.

You can pick up quite a bit about how your hardware or software works just from watching it in action or by talking to the people designing and building it. However, if you’re interested in broadening your skill set and general fund of knowledge about the sci/tech world, you can try the following sources:

National Geographic
How Stuff Works.com
Popular Science/Popular Mechanics
Discover Magazine
BoingBoing.net
Gizmodo.com
Science 2.0

A good set of encyclopedias–harder to come by these days, but Wikipedia.org is not always reliable.

I got started on the science path reading Tell Me Why books as a kid.

A friend got me the Engineering an Empire series from The History Channel. It’s a treatise on architectural technology and how people built things throughout history.

The Great Courses has some interesting content….

In any case, there are some good books and sites out there that you can read or shows you can watch that make science education non-boring.

Analogies

As I’ve written elsewhere on this blog, science fiction is an excellent form of mental training for the aspiring technical writer. The primary reason is that SF writers take the reader–usually via the viewpoint narrator–through an unusual environment or technology in a literary fashion, often using different analogies, similes, or metaphors for explaining how that environment or technology works. Consider this description of an alien’s view of time from Kurt Vonnegut’s Slaughterhouse-Five:

The Tralfamadorians can look at all the different moments just that way we can look at a stretch of the Rocky Mountains, for instance. They can see how permanent all the moments are, and they can look at any moment that interests them. It is just an illusion we have here on Earth that one moment follows another one, like beads on a string, and that once a moment is gone it is gone forever.

Or Arthur C. Clarke’s description of “superspace,” from which he postulated a near-light-speed propulsion system in The Songs of Distant Earth:

No one could really imagine a millionth of a centimeter, but at lest the number itself – a thousand thousands – was familiar in such human affairs as budgets and population statistics. To say that it would require a million viruses to span the distance of a centimeter did convey something to the mind.

But a million-millionth of a centimeter? That was comparable to the size of the electron, and already far beyond visualization. It could be grasped intellectually, but not emotionally.

And yet the scale of events in the structure of space was unbelievably smaller than this – so much so that, in comparison, an ant and an elephant were virtually of the same size. If one imagined it as a bubbling, foamlike mass (almost hopelessly misleading, yet a first approximation of the truth) then those bubbles were…

a thousandth of a millionth of a millionth of a millionth of a millionth of a millionth…

…of a centimeter across.

Again note the effort to tie the unfamiliar to the familiar. You won’t always have that opportunity in technical writing; however, it’s important that you can at least think in familiar terms as a way of helping you navigate the mysteries of whatever job has been put before you. And because you’re dealing with complex topics, it’s important that you try to use the simplest, most straightforward language you can.

Logic

I’m using “logic” rather broadly here, but what I’m trying to convey is using your reasoning to visualize how the various pieces of a particular technical puzzle fit together. In the same blog where I talk about using the airline route structure mentioned above, I also discuss how it’s important to do your own analysis of the content you’re given to understand how words and concepts are used in your given topic. For instance, after quite a bit of time reading various technical reports and reviewing schematic diagrams, I learned “rocket science” by understanding it linguistically. Which words are the subjects? Which words are the verbs? Which ones are the objects? What parts are performing specific types of actions upon other parts of the system? What is the outcome when those actions are performed?

If anything, my learning of propulsion systems came about through the logic of linguistics and storytelling: you start with a cold engine at the tail end of a rocket on the launch pad and you end with that engine firing hot gases out the bell-shaped nozzle at the back and and launching the rocket into space. What are all the actions that have to happen in between to make the beginning and the ending fit?

English literature major tricks aside, logic helps you best organize your information into a format that makes sense to you and the reader. Are you talking about a process? If so, you want to arrange your information chronologically. Are you describing a different collections of objects? Perhaps you’d be better off describing them by function, size, or location. Your writing needs to have a flow that makes sense to you but also makes sense to your reader. S/he will have a specific use for the information you are sharing, and that, too, needs to be taken into account. You might want to tell the history of your product and how proud you are of all the hard work that went into making it; however, the user just wants to know how the blamed thing works.

Concluding Thoughts

Amruta, I hope you found this useful. As I have other ideas on the thinking behind technical writing, I’ll continue to share them. I am very structure-focused in my approach. I like to bring order to chaos–which is sometimes that’s exactly what’s handed to me; once I have my structure, the detailed writing follows from there. A document filled with prose to match Hemingway and grammatical precision good enough to make Strunk and White weep with joy won’t matter a whole lot if I don’t know what story I need to tell my reader. That’s true no matter where you’re writing.

Posted in audience, blogging, engineering, philosophy, science fiction, technical writing, Technology | Tagged , | 3 Comments