Categories
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.”

Wild
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.

Categories
Process Project Management Quality

If you want to ship software, stay in touch with how much you suck

By Jim Grey (about)

My colleague Matt Block recently posted on his blog a link to an article about how a software shop’s business model affects how well agile scrum works for them. It breaks business models down into emergent, essentially meaning that the company builds product to meet goals such as selling ads or driving traffic, and convergent, essentially meaning that the company builds product that directly serves a target market. The article argues that agile is made for emergent and is a poor fit for convergent. That’s just a sketch of the article; go read it to get the full flavor.

Eminence says: Monrovia Sucks!
Graffiti found in the town neighboring Monrovia.

I’ve always worked for companies following convergent business models. We’ve made our money by selling the software we created, which made it always important to deliver a certain scope by a certain time. When those companies implemented agile scrum, they could never fully adapt a key principle of it: when it’s time to ship, you ship whatever is built. In a convergent world, scope is king; you ship when everything specified is built.

I e-mailed my brother, Rick Grey, a link to this article. It’s great to have a brother who does the same thing I do for a living as we can talk endlessly about it. I thought we’d have a conversation about how to scope an agile project, but instead he had a brilliant insight: What if agile is good for convergent-model companies because it tells you sooner how much your project is off track? He gave me permission to share his e-mailed reply, which I’ve edited.

– – –

What if the companies we’ve worked for and all the other convergent-model teams of the world are doing agile just fine? By “just fine” I mean “as good as they do waterfall,” which may not be “just fine,” but we’ll get to that in a minute. Meanwhile, consider:

Long waterfall project:

  • No one pays real attention to progress (there’s always next month to catch up)
  • Engineers go dark, checking out huge sections of the codebase and not merging them back for long periods
  • Engineers (who are notoriously poor estimators) claim 50% done when it’s really about 25% – and then, as the code-complete milestone nears, they (usually innocently) claim 90% done when it’s really 70%
  • A couple of days before the code-complete milestone, engineering finally acknowledges they won’t hit the milestone and delays delivery to QA – “but we’re 95% done, for sure”
  • Under the pressure of already having missed a deadline, developers quietly take shortcuts to make it possible to hit the new QA delivery date
  • Weeks and months of unmerged changes come crashing in, creating conflicts and compile/deploy problems, further delaying delivery to QA
  • QA, now staring with a multiple-week handicap on an already-too-aggressive schedule, quietly takes its own shortcuts
  • QA finds hairy showstopper bugs and so the ship date gets moved
  • Management is livid, so QA goes into confirmatory testing mode just to get it out the door

Agile project of the same size:

  • Much of the above happens at a smaller scale, one iteration at a time
  • You fail to deliver everything planned starting with the first sprint
  • Instead of spending 80% of the project thinking you don’t suck as an organization and the last 20% realizing that you do, agile lets you feel like you suck every step of the way
  • Takeaway for management: “agile sucks” and/or “we suck at agile”

I assert that most teams are bad at delivering under a convergent business model. The hallmark pathologies of software delivery under a convergent model are too numerous and powerful for most teams to overcome, but their struggles are masked by waterfall until the end. Agile surfaces the problems every iteration. You feel like a loser by week 4 instead of week 40.

But this is actually a win. You get better project visibility and a tighter feedback loop, meaning you’ve got a better chance to make adjustments earlier to get the most out of your team you have. Embrace the feedback loop as a chance to make things better, and learn not to view it as proof of how much you (collectively) suck.

– – –

I will add that agile also helps you keep resetting expectations within your organization, because it makes it standard practice to keep reestimating what it will take to finish everything. This is just what I was talking about in my last post (read it here).