Career Technical Writing

Software technical writing is a dying career (but here’s what writers can do to stay in the software game)

By Jim Grey (about)

I had lunch recently with a fellow I worked for several years ago. He gave me my last job as a technical writer and my first job as a software tester. He’s currently leading product development at a different software company. “Times have changed,” he said. “I don’t have any technical writers anymore. These days, I want the UX to be good enough that documentation isn’t needed.”

A few days later I had a drink with another former boss. I managed testers and technical writers while I worked for him. Since then, he’s started his own consulting company. “Technical writing is dying off,” he said. “It’s all about clean, engaging UX now. I have talked to more than a hundred startup and small software companies as I’ve built my business. Almost none of them have technical writers, and almost all of them have UX designers.”

Smart tech writers see the writing on the wall.

It’s clear: companies are leaning into good user-interface design and stepping away from online Help systems and printed/PDF documentation.

It’s a relief. Nobody wants to have to read something to learn how to use a software product. When usage falls right to hand, users are happier and more likely to use the product more. Good UX really can reduce the documentation burden.

My last company had mighty good UI design. One technical writer worked for me, and she kept up with about ten developers. In past companies with lesser UIs, I needed one writer for every four or five developers. It took more words to explain those products’ cumbersome usage.

Admittedly, the latent technical writer in me wants to holler, “Users need instructions for even the best designed products!” Some interactions are incredibly hard to design well enough to forego usage instructions. And users will always need usage reminders for seldom-executed tasks.

But the writing is on the wall. If you’re not finding fewer technical writing job openings yet, you will soon. Fortunately, your skills transfer to other jobs in software development organizations. You will need to build some new skills for many of these jobs, but you might be able to land that first new job without them and build them as you work.

Tester or quality assurance engineer

Testers explore software systems looking for bugs. In some shops, they write and execute detailed test cases; in others, they explore based on high-level test charters. The goal is to report, usually by writing bug reports, on the level of quality the developers have delivered so that decisions can be made about when to ship.

Technical writers routinely find product bugs. At my last company, my lone writer routinely found really important bugs. The VP of Engineering even noticed: “She finds outstanding bugs,” he said. “It must be because she thinks like a user.”

When I shifted into testing 15 years ago, I designed my tests in much the same way I designed online help: by first asking what tasks users would perform in the system. Then I set about making sure those tasks worked. You can do this too. You’ll have plenty more to learn about testing, but this is a great place to start.

Existing skills you will use: Creating and articulating mental models of software systems. Exploring software to discover how it works. A basic understanding of how software is built and delivered. Writing.

But build these skills: Database skills, especially writing queries. Light coding or scripting, to help you automate tests. System administration, to help you better understand and manipulate the environments the software lives in. (Don’t be daunted. I’ve seen many writers surprise themselves when they quickly start to learn these things. It’s as if they soaked up technical abilities by osmosis, just by being around lots of people who have them.)

Product owner, product manager, or business analyst

All of these jobs involve understanding customer needs and translating them into user stories, specifications, or requirements that the developers and testers use to build software. They may involve building a vision for what a product needs to be to meet its market’s needs. These people usually work closely with developers and testers to make sure the vision is realized, and to resolve implementation challenges.

Existing skills you will use: Understanding of customer needs. Creating and articulating mental models of software systems (though, in this case, often systems that have not been built yet). Writing. A basic understanding of how software is built and delivered.

But build these skills: Negotiation, as you might need to manage expectations of customers, the development team, and sometimes even management. Estimation and project management, as you might have to participate in sizing work and projecting delivery dates.

Various UX roles

The UX field includes a number of jobs that, together, create the way the software works and feels for the user. Typical titles include UX Designer, Information Architect, Visual Designer, Interaction Designer, and Content Specialist. These roles involve work such as creating wireframes of screens, designing user workflows, performing usability testing of prototypes, interviewing users and sometimes even shadowing them as they work, writing field labels and error messages, and choosing typography.

This might seem like a real stretch for a technical writer. But my experience is that writers often have innate insight into bad UX: if it’s hard to write about, then it’s hard to use. I find that technical writers can often extemporaneously evaluate product usability and give very useful ideas on how to improve UX.

Existing skills you will use: Interviewing. Understanding of customer needs. Creating and articulating mental models of software systems. Writing.

But build these skills: This depends heavily on the role, but: Design, in general. Graphic design. Usability testing. Prototyping.

These jobs crackle with career growth. But if you’d rather stay true to writing, you can shift into marketing communications, instructional design, or even good old-fashioned business writing (policies and procedures, disaster recovery plans, and the like). My town’s biggest employer is a pharmaceutical manufacturer; lots of software writers here have shifted into validation writing, which is an FDA compliance activity. You might even be able to move into writing technology articles and books; I’ve done a little of that. And some software technical writing jobs will likely always remain in regulated industries, and on government contracts, and for highly technical products.

Nostalgia for my former technical-writing career makes this a sad passage for me. But I think this trend toward effective UX is better for the user, and gives writers good paths for growth.

Process Quality The Business of Software

“Software engineering” might be an oxymoron

By Jim Grey (about)

I’ve said it to my test teams many times: Making software isn’t quite engineering. Building a bridge – now that’s engineering. You determine how long the bridge needs to be, how much load it needs to carry, and what kind of bridge to build (steel truss, concrete arch, etc.), and from there it’s mostly mathematics and physics. Just run the calculations and you’re good.

We have bridge-building down. With a couple of notable exceptions, such as the Tacoma Narrows bridge which heaved and twisted and finally collapsed (video here), new bridges seldom fail. Old bridges fail sometimes, but it’s reliably due to accident or neglect.

The S Bridge at Blaine

My apologies to any civil engineers who stumble upon this post. I’m sure you’re cringing that I’m overlooking many subtleties of your discipline.

There’s nothing subtle, however, about how often software fails. Our users aren’t happy about it, but they aren’t surprised by it, either.

For any thing you ask a software developer to build, there will be a whole bunch of valid ways to do it, each with its own unique ways of creating failures. This is especially true when when that developer enhances existing software that he or she didn’t make in the first place. It’s tough to predict exactly how the enhancements will affect the rest of the software. The more lines of legacy code, the more time and analysis it takes to think that through.

If a developer had unlimited time and money, it might be possible to deliver perfect software. Ah, a developer can dream! But here’s where bridge-building and making software have an important thing in common: time and money are never unlimited.

I sympathize with the folks who call software a craft. People who make software use tools and knowledge in its design and construction. These are hallmarks of craft.

Another way that software is like craft is that it’s difficult to fully separate the design from the making. Even when one person designs the software and another writes the code, the coder has to make a bunch of lower-level design decisions along the way.

The software craftsmanship movement meets corporate resistance because revenue and profit ride on what we build. Our companies need to sell features to meet revenue projections, or deliver bug fixes to retain customers. That’s why timed delivery is so important: if you wait too long to deliver, the opportunity to grow or retain revenue begins to shrink.

Feeling pressure to deliver, yet knowing that if we deliver junk we’ll be in an even worse pickle, we tend to manage software-development projects like engineering projects. I think we feel like we have better control when we manage them that way. But that feeling of control can’t mask it: no matter how tightly you plan a software project, no matter how you shape your development and delivery processes to mitigate risk, no matter how much you try to predict the troubles you’ll encounter, you will discover things along the way can seriously derail those plans. It happens in two-week scrum sprints just as it does in ten-month waterfall projects. Discovery is simply endemic to software development.

As a software project manager, I try to build in buffers for the unknown. I also steer projects daily based on what we discover, adjusting plans and communicating impacts to whomever needs to know. I try to make sure our development practices deliver the best possible code to test, and then I try to arrange testing to find the worst bugs first so that near the hoped-for end, only minor bugs remain. Despite all that, important bugs still sometimes reach the user.

We ship when the software is good enough. What “good enough” means varies from context to context, but it is unfailingly short of perfect. Shipping at good enough means you succeeded.

If I delivered bridges that way, I’d never drive over one I built.