Tag Archives: Technical communication

A new vantage point

Around 1610, Galileo Galilei, pointing his newly invented telescope at the sky, became the first person to see bulges on both sides of the planet Saturn. He didn’t know what they were. It took 45 years before another astronomer, Christiaan Huygens, figured out that they were rings surrounding the planet.

For 350-plus years since then, every view we had of the rings came from the same vantage point: from outside.

Until last month. For the first time, the Cassini spacecraft slipped between Saturn and the rings, turned its camera away from the planet, and started taking pictures from inside the rings.

Cassini flying inside Saturn's rings
This illustration is part of a NASA animation that shows Cassini’s trip inside the rings. The inset captures an actual image that Cassini sent back.

Following Cassini’s example, I’ve begun considering how I can look at things from new vantage points. If I’ve always looked at something in the same way, have I really seen it in its entirety? Maybe not.

Here are a few things I’m trying to see from new vantage points.

Mergers and acquisitions

My company, Extreme Networks, has acquired parts of 3 different companies over the past year. As a result, our technical writing team is growing rapidly. New people, with all sorts of different backgrounds, are learning our tools, our workflows, and our corporate culture. A lot of anxiety comes with the experience of being part of an acquisition.

I actually have experience with this. I’ve seen things from the other side of an acquisition. Now is a great time for me to remember how it felt — and thereby to help make it easier for the newcomers to our team.

Starting out

My recent participation in the STC Carolina chapter’s mentoring program has given me a new appreciation for how hard it is to break into the technical communication field — from finding a specialty (software writer, e-learning developer, scientific editor) to creating a personal brand to simply landing that first job.

Colliding worldviews

Look at the current world scene and you’ll see people with fundamentally different worldviews. More and more, those worldviews seem to be colliding — and the more they collide, like particles in an accelerator, the more sparks seems to fly. The greater the differences seem to become.

I’m still trying to grasp that. More important, I’m trying to understand the people whose worldviews are different from mine. If I can understand the people on the other side, maybe we can find something in common that we can use as a basis for moving forward together. Maybe that’s too much to ask. I don’t know. But I do know that talking beats shouting, so that’s what I try to do.

(If you’d like to try, too, Jesse Lyn Stoner recently shared some practical tips for taking a stand without polarizing others.)

Epilog

Cassini has been orbiting Saturn since 2004. On Friday its mission will reach its grand finale when it dives into the planet’s atmosphere. When it transmits its last data from inside Saturn’s clouds — a vantage point no one has ever seen — humankind will gain more knowledge about Saturn’s atmosphere than ever before.

How have new vantage points helped you in your professional life? Can you think of other vantage points you’d like to gain?

Advertisements

It’s not your text

Hey, wow. I was looking on the internet and — what do you know? — I found a list.

Yes, I realize that the internet is full of lists. Many of them exist simply to entice us to click. A few might entertain or inform, and then I forget them in 5 minutes.

A very few are worth recommending. One such is this list of rules for editors, compiled by the Baltimore Sun‘s John McIntyre. If you’re in any part of the writing business, hurry on over to The Sun and take a look.

I lingered long over Rule 4: It’s not your text.

You are in the middle of things. You have a responsibility to assist the writer in achieving their purpose. You have a responsibility to the publication to maintain its standards and integrity. You have a responsibility to the reader, the party most commonly overlooked in these operations, to meet their needs of clarity and usefulness. Your personal preferences are subordinate to these responsibilities.

quill penSo it is with editors, and so it is with technical writers as well. We have a responsibility to the company we represent, to maintain its standards and integrity (to the extent it has them), and to present its products in such a way that our readers can use them effectively.

We also have a responsibility to the reader, to meet their needs of clarity and usefulness. This is our paramount responsibility, because this is the one we have to get right. We might get away without perfectly reflecting the company’s style or brand image, or without perfectly describing the product’s features. But if we don’t meet the reader’s needs, so that they stop reading and walk away (or dial tech support), we’ve failed completely.

stone bridgeI’ve heard the technical writer described as the bridge between subject-matter expert and reader. I used to bristle at that metaphor: I thought it implied a passivity on the part of the technical writer, as if we were nothing more than a conduit carrying information from one actor to another. “People walk on bridges,” I remember complaining.

Now, in my old age, I’m more comfortable with the bridge metaphor. Maybe I have a higher opinion of bridges: some of them are engineering marvels, and even the simplest ones are mighty useful. But mostly, I think, I better understand that it’s not my text.

Yes, I play an important role in the transaction between expert and reader. But it’s not about my personal preferences. If I want my name on something, I should write a novel.

My job is to make the information good, and that’s nothing to sneeze at. But it’s not my text.

Serve the profession. Serve each other. Serve the truth.

These are remarks I made earlier this week at the STC Carolina chapter’s 50th anniversary celebration (with some local color edited out). I offer them as a salute, and an encouragement, to everyone in the technical communication profession.

Fifty years ago our forebears brought forth a new organization, dedicated to promoting and cultivating the profession of technical communication in this area.

It’s a testament to their vision that this idea – cultivating the profession of technical communication – sounds perfectly normal to us today. In 1967 it was crazy talk: technical writers were often an afterthought, subservient to the engineers and scientists they worked with. At universities, technical writing, when it was taught at all, was usually a little enclave within the English department.

The founding members

STC Carolina 50th anniversary logoWhen I got here in 1983, I got to know three of our chapter’s founding members. Dr. Edmund Dandridge, professor of English at NC State University, made a name for himself as a teacher and researcher.

Richard Russell – Dick Russell – retired from IBM just about when I arrived. A whole generation of technical writers regarded Dick Russell as a trailblazer and a mentor.

Austin Farrell without a doubt was the chapter’s father figure. I don’t think he actually smoked, but I can picture him wearing a cardigan sweater, holding a pipe in his hand, offering fatherly advice and wisdom to the people who followed him as leaders in the chapter.

I was privileged to know these founding members, but here’s what I want you to know about them: they were pretty much the same as you. They believed that technical writers, designers, illustrators, and managers should be recognized as professionals – just like the engineers and scientists they worked with. They believed in sharing knowledge and helping people grow in their careers.

The legacy they started

Fifty years later, we look on the legacy they started, the legacy that you all have helped build. I’m grateful and proud that the Carolina chapter has always had strong programs and events, strong competitions, and, of course, strong people.

I keep coming back to the people. If this chapter has a proud history it’s because of its people. Because of all of you who cared. You cared about the profession. You cared about each other. You cared enough to share your skills and knowledge, to mentor, to celebrate each other’s achievements.

You cared. You served.

Even though I said we’re not subservient, our profession really is built on service. We serve our audience – the people who use the information we create. Service is the heart of what we do as technical communicators.

Some of you were active in the chapter many years ago. Some of you are longtime members and have played vital roles. Some of you are relatively new: your hard work, your inspiration, your caring and serving will write the history of our next 50 years.

So, from today onward, how will we serve our profession? Continue reading

Will you still need me? STC at 64

Today, the first full day of the annual STC Summit, marks the 64th year that STC (the Society for Technical Communication) has been in business.

Sgt. Pepper's album cover with STC logo

Hmm…What if I Photoshop all of the STC staff and directors’ faces into this image?


Which brings to mind a Beatles lyric:

Will you still need me, will you still feed me,
When I’m sixty-four?

The “Will you still need me?” question is especially relevant as STC — a 20th century organization — copes with flat membership numbers and attempts to navigate the changing professional landscape of the 21st.

As I’ve said before, I think the technical communication profession — and the people in it — still do need STC. But the reasons are changing, and have been changing for some time. As a result it’s not a sure bet that STC will remain relevant over the next few years. Continue reading

The first all-emoji technical manual

This week the technical communication world is abuzz over the April 1 release of Remco Children’s Bedroom Suite: Assembly Instructions. Written by breakout author Julian Rebusser, it’s the first technical manual written entirely in emojis.

Recently I caught up with Rebusser, Skyping from a very hip coffee shop on the West Coast, for this exclusive interview.

Leading Technical Communication: Welcome, Mr. Rebusser, and thank you for agreeing to appear in my blog.

Rebusser: You’re welcome. I read somewhere online that your blog is influential, and I’m all about building my personal brand.

Tell me about your new book.

It’s got all the instructions for unpacking and assembling a full suite of children’s furniture: bed, night stand, armoire, desk, chair. For a few extra bucks you can even get a lamp

Assembling all of that must require a lot of complicated steps.

Yes. And when I wrote it as a conventional manual, it was like 20 pages of crap

What inspired you to write an all-emoji technical manual?

I had an epiphany one morning, waiting for the barista to brew my double-shot caramel macchiato

Wow. What was that like?

Well, for the first time ever, I thought about my audience.

You hadn’t thought about your audience before?

Of course not. Great writers don’t think about their audience. They think about cool, hip ways to express themselves. But for 2 or 3 minutes that morning, for some reason, I thought about my audience. And I realized something.

What did you realize?

Well, who usually assembles a furniture set for children?

Their parents, I suppose.

Right. And who are those parents?

I’m not sure I follow.

They’re Millennials! Digital natives. People who don’t read books

They don’t read books?

Of course not. They don’t like to read anything. I saw that in an article online.

And so the children’s parents….

Right. If I gave them words they’d never read them.

So, instead, you gave them….

Emojis! Millennials love emojis. I saw that online too. And I knew I was perfect for the job because I speak fluent emoji.

What happened next?

In no time my 20-page draft was down to 2.

Can you give me an example?

It used to take a whole page to explain how to bolt the legs to the bed.

And now?

Now it’s boltlegslegstwobed

I — I’m speechless.

I presented this last week at Write the Docs, and they were speechless too.

So now everyone knows you as the first all-emoji technical writer. What’s next?

Well, it’s all still hush-hush. Can you promise to keep a secret ?

Sure.

Next year when Remco rolls out its do-it-yourself flower garden, I’ll be there with an emoji-based augmented-reality experience. I’m calling it Pokemon Grow.

I can hardly wait.

It’ll totally blow your mind.

Yeah, I’m sure it w– mind blown

Welcome to your professional home

Close up of a graduation cap and a certificate with a ribbonThis week brought one of my favorite annual events: the celebration at which the students in our Technical Communication program at Duke University receive their certificates.

This year’s group was especially engaged and astute. Their capstone projects reflected their enthusiasm and skill.

Here’s what I told them during our celebration.

A person who aspires to become a doctor passes through a carefully prescribed series of steps: medical school, internship, residency. An aspiring lawyer goes to law school and takes the bar exam.

But people follow all kinds of paths into technical communication. I majored in the humanities and hoped to be the next Bob Woodward, until I discovered that technical writing paid better than writing news. Your other instructors were researchers, software engineers, and trainers. One even went to school to study technical writing. Each of us followed our individual path until we found our professional home.

You too came to this place from a variety of backgrounds. Your cohort includes an academic editor, a user-interface designer, a couple of teachers. You’ve worked in medical research, medical transcription, policies and procedures. We even have an actor and playwright.

Whether technical communication turns out to be your professional home, or you apply the skills and principles you learned in this class in other lines of work, you’ll always be part of the technical communication community.

It’s a diverse community that lives and works all around the world, encompassing many different disciplines in many different industries.

Despite its diversity, its members share a common belief in providing information — relevant, factual, truthful information — to the people who need it, when they need it, where they need it. That belief drives us to make a positive difference in the world.

The members of our community are also creative, and, in our own way, we enjoy having a good time. In fact, right after this we’ll adjourn to the bar and argue about the Oxford comma. Actually, I’m kidding. We don’t argue about the Oxford comma. Every technical communicator knows that the Oxford comma is indispensable.

How many spaces to put after a period. That’s what we argue about.

Read my message to a previous class from the same certificate program: You’re now a technical communicator.

Is augmented reality part of technical communication’s future?

While walking my dog last night I came upon a mother and her young son standing on the sidewalk. She was holding her smartphone high in front of her, pointing it toward the western sky.

As I came near she announced, “Mars and Venus.”

skymap_screenshots

The Sky Map map (Screen shots from Google Play)

I learned the names of the planets and stars the old-fashioned way: standing outside on cold nights with my dad, and studying the sky atlas he gave me. But today I guess there’s an app for that. There are actually several apps, as a cursory Google search will attest.

I think it’s cool that you can aim your phone at the sky and learn the basics of stargazing. I think it’s very cool that many of the apps are using augmented reality.

When I got home I downloaded one such app, Sky Map. True to its name, Sky Map immediately gave me a clear, easy to use map of the heavens. I haven’t yet sussed out what all of the icons mean. But I had fun using the Time Travel feature to see the positions of the moon and planets on the day I was born.

Do I sound like a space geek? Guilty as charged.

When it comes to augmented-reality apps, though, I’m still unsure about a couple of things.

No business case?

Number one: the stargazing apps are very low-cost. Many, like Sky Map, are free. So it’s hard to see whether there’s a business case for using AR in training and technical communication.

I write documentation for networking hardware — switches and routers. I can easily imagine how customers would like AR documentation that shows them how to attach brackets to switches and mount them together in a rack. But does customers would like translate to customers would pay for? Or to customers would choose my company over our competitor?

In the absence of clear answers, would my company invest in the tools, time, and training needed to develop such documentation?

Not ready for prime time?

Number two (and maybe this follows from number one): it seems so far that AR is mostly the province of gamers and app developers — not technical communicators or training developers.

skymap_screenshot2

Time Travel, Sky Map style. Recognize the date?

Most of the literature about AR in technical communication is still speculative. An article might say, for example, Here’s what AR is, and here’s how I think it could be applied to tech comm. Or: Everyone loves AR, and tech comm is on the verge of embracing it. I’ve seen only a handful of isolated case studies in which AR actually is being used for technical communication.

One such case study is General Motors’ myOpel app. GM began distributing the app to Opel owners a few years ago. Does anyone know if they’re still doing so? Or if they’ve expanded the idea to other brands? (A quick peek at Google Play reveals that myOpel is still available but it’s getting only tepid reviews.)

So, despite the star-struck articles (one of which — full disclosure — I wrote in 2013), I remain unconvinced.

What do you think? Do the stars say that AR will be a big part of technical communication’s future? Have you done AR work for technical communication or for training and if so, have you succeeded in making the business case for it?

Living and learning: 2016

Merriam-Webster picked surreal as its 2016 word of the year, and…yeah. At times this year I’ve felt like Alice in Wonderland, and I’ll bet you have too.

One thing remains as true as ever, though: if you’re not learning, you’re not living.

Here are some things I learned this year:

The future is technical communication

screen-shot-2016-02-25-at-6-07-54-pmTechnology is moving forward at breakneck speed. People want technology. People have different learning styles.

Who can deliver the information people need to make use of, and enjoy, the technology that’s all around them? Technical communicators, that’s who.

That’s the gist of Sarah Maddox’s keynote speech at tcworld India 2016.

I think Sarah is saying that we need continuously to hone the technical part of our job title, while not neglecting the communicator part. And I think she’s absolutely right.

We care a lot about our professional society

STC logoSome of my most popular posts this year dealt with the Society for Technical Communication (STC) and its role in a changing world. How can STC remain relevant when the traditional roles of professional societies are changing? How can it serve a community that’s growing ever more diverse, in terms of the kinds of work we do?

As 2017 begins, STC is looking for a new CEO. Whoever gets the job, and whatever things they choose to prioritize, I hope they’ll appreciate the passion and dedication of STC’s members.

DITA isn’t cheap (but it’s still worth the cost)

DITA logoEven as more organizations embrace DITA for developing their content, we hear that DITA is complex and hard to learn. Overcoming DITA’s acceptance hurdles was one of my most commented-on blog posts this year, as was my plea for greater sensitivity to the writers’ learning curve.

Yes, DITA is powerful. But it didn’t get that way by being simple. I’ve come to appreciate that writers need time to absorb the underlying principles, which happen to align closely with the principles of good technical writing, and they need time to learn the how-to aspects as well. It’s time well spent, I think.

A leader is a storyteller

monsterWe saw it in this year’s political news: for better or worse, people are drawn to the leaders who tell the best stories.

As technical communicators, we’re by nature good storytellers.

Does it follow, then, that technical writers have an edge when it comes to being good leaders? I think it does.

Don’t take things too seriously

The year truly has been surreal. Many of our deeply held beliefs — about leaders, about governments, about the course of history — have been challenged if not overturned.

Yet my most-read post in 2016, by far, was a collection of jokes. That taught me not to take things too seriously, and especially not to take myself too seriously.

It reminded me that we’re all human beings. We all need to connect with each other and, sometimes, share a laugh.

I hope I’ve connected with you, at least a few times, in 2016. I hope we’ll continue to connect in 2017. And even share a laugh or two.

Related: Living and learning: 2015

Showing the way in a surprisingly different world

leadwolfThe recent surprise election of Donald Trump as president of the United States has occasioned a lot of writing that I can sum up like this: Suddenly the world is very different than I thought it was. How do I (or we) deal with that?

One particularly poignant article came from technical communication blogger Danielle Villegas — TechCommGeekMom. Danielle pondered what the election results, and the conditions leading up to them, mean for technical communicators. Are we seeing the end of the trend toward globalization? How easy will it be to find work if you live in a rural area, away from a city?

Toward the end of her article, Danielle issued a call to action:

The proclivity of technical communicators, from my observations, is that they have big hearts. They have strong ideas, they are organized, and they know how to take action. They are generally open-minded, they think “outside the box” for solutions, and they understand the importance of reaching out and embracing the world because the proliferation of the internet has warranted it. We can make a difference in how we approach our work, both domestically and internationally, to set an example of best practices of being decent human beings trying to help each other progress and survive in this world.

How can technical communicators show the way, or “set an example,” in the way Danielle describes? How can we use our “big hearts” to bring progress, and perhaps bring reconciliation, to the fractured world in which we live?

Here’s my stab at an answer. I hope all of you will chime in with your comments. Continue reading

Where do the technical writers fit?

The other day Sarah Maddox posed the question Where do technical writers fit in an organisation? It’s a question my colleagues and I have bandied about for most of my 30-plus years working in technical communication.

The answer has evolved during those 30-plus years. And it’s tempting simply to throw up my hands and give the standard consultant’s answer: it depends.

smaddox

Sarah, like all of us, is looking for a place to fit in

Sarah doesn’t advocate for any one answer, either. Instead, she deftly states the case for including technical writers in each of these parts of the organization:

  • Engineering and product management
  • User experience (UX)
  • Support
  • Marketing
  • Developer relations

Here’s what I make of it.

We’re not an island

There’s one place in the organization where the technical writers definitely should not be, and that’s off by ourselves.

I didn’t always feel this way.

Early in my career, when technical writing was still being defined as a profession, it was important for the writers to establish an identity as a team and emerge from the backwaters of wherever they’d been placed on the org chart — usually in product development.

In companies that formed separate technical writing teams, the writers were better able to collaborate on tools, training, and best practices. Their managers could fight for a place at the table alongside development, marketing, and support.

The separate-team approach was what I experienced at IBM, and it wasn’t until maybe the mid-1990s that we, as a profession, had evolved past it. Continue reading