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
Career

Twenty-five years in the software salt mines

By Jim Grey (about)

Tomorrow it will have been 25 years since I started my career in the software industry.

It might seem odd that I remember the day only until you know that I started work on Monday, July 3, 1989, making my second day a paid holiday. The office was nearly deserted on my first day. My boss regretted not having me start on July 5 so he could have had an extra-long weekend too.

I was 21 years old when I joined that little software company in Terre Haute. I’m 46 now. I have worked more than half my life in and around the software industry.

taught myself how to write computer programs when I was 15. When I was 16, my math teacher saw some of my programs and praised my work. He encouraged me to pursue software development as a career. He began to tell me about this tough engineering school in Terre Haute.

I graduated from that tough engineering school hoping to find work as a programmer. Jobs were hard to come by that year, so when a software company wanted to hire me as a technical writer I was thrilled just to work. And then it turned out I had a real knack for explaining software to people. I did it for twelve years, including a brief stint in technology publishing and five years managing writers.

I then returned to my technical roots, testing software and managing software testers. I learned to write automated functional and performance tests – code that tests code – and it has taken me places in my career that I could never have imagined.

Office
My office at one of my career stops

I’ve worked for eight companies in 25 years. The longest I’ve stayed anywhere is five years. I left one company in which I was a poor fit after just 14 months. I’ve moved on voluntarily seven times, was laid off once, and was fired and un-fired once (which is quite a story; read it here). Changing jobs this often isn’t unusual in this industry and has given me rich experience I couldn’t have gained by staying with one company all this time.

I’ve worked on software that managed telephone networks, helped media buyers place advertising, helped manufacturers manage their business, run Medicare call centers, helped small banks make more money, enabled very large companies to more effectively market their products, and gave various medical verticals insight so they can improve their operations and their business.

Some of these companies were private and others were public; so far, I’ve liked private companies better. Some of them made lots of money, some of them had good and bad years, and one of them folded. Some of them were well run and others had cheats and liars at the helm. Some were very difficult places to work, but those were crucibles in which I learned the most. Others have brought successes beyond anything I could have hoped for a quarter century ago.

I did, however, hope for a good, long run in this industry, and I got it. But I’m also having a hard time envisioning another 25 years. It’s not just because I’d be 71 then. I really like to work, and – right now at least – I plan to do so for as long as I am able. But I’m starting to have trouble imagining what mountains I might yet climb in this career. Maybe that’s part of reaching middle age – indeed, many of my similarly aged colleagues, some with careers far beyond mine, have gone into other lines of work. I’m still having a lot of fun making software, though. I currently manage six software testers, one test-automation and performance-test developer, and one technical writer. I get to bring all of my experience to bear, and encourage my teams to reach and grow. I don’t want to stop just yet.


If this sounds familiar, it’s because it’s an update of an eariler post. Cross-posted to my personal blog, Down the Road.

Categories
Quality Testing

When test automation is nothing more than turdpolishing

By Jim Grey (about)

I used to think that writing a fat suite of automated regression tests was the way to hold the line on software quality release over release. But after 12 years of pursuing that goal at various companies, I’ve given up. It was always doomed to fail.

In part, it’s because I’ve always had to automate tests through a UI. When I did straight record-and-playback automation, the tests were enormously fragile. Even when I designed the tests as reusable modules, and even when I worked with a keyword-driven framework, the tests were still pretty fragile. My automation teams always ended up spending more time maintaining the test suite than building new tests. It’s tedious and expensive to keep UI-level test automation running.

But the bigger reason is that I’ve made a fundamental shift in how I think about software quality. Namely, you can’t test in quality – you have to build it in. Once code reaches the test team, it’s garbage in, garbage out. The test team can’t polish a turd.

Writing an enormous pile of automated tests through the UI? Turdpolishing.

I’ve worked in some places where turdpolishing was the best that could be done. Company leadership couldn’t bear the thought of spending the time and money necessary to pay down years of technical debt, and hoped that building out a big pile of automated tests would hold the line on quality well enough. I’ve led the effort at a couple companies to do just that. We never developed the breadth and depth of coverage necessary to prevent every critical bug from reaching customers, but the automation did find some bugs and that made company leadership feel better. So I guess the automation had some value.

But if you want to deliver real value, you have to improve the quality of the code that reaches your test team. Even if the software you’re building is sitting on a mountain of technical debt, better new code can be delivered to the test team starting today. I’m a big believer in unit testing. If your software development team writes meaningful unit tests for all new code that cover 60, 70, 80 percent of the code, you will see initial code quality skyrocket. Other practices such as continuous integration, pair programming, test-driven development, and even good old code reviews can really help, too.

But whatever you do, don’t expect your software test team to be a magic filter through which working software passes. You will always be disappointed.

Categories
Quality Testing

Giving testers less to do

By Jim Grey (about)

I hear legends of companies who hire nothing but programmers in their test departments, and rely almost entirely on code-based tests in their software development methodologies. I’ve never seen such a shop in person. Out here in the Midwest, most testing involves humans directly exercising user interfaces.

Eric Jacobson recently wondered aloud on his blog whether testers are simply too busy finding bugs through the UI to move into more technical or programmatic testing. My typical experience has been that Development doesn’t deliver software to QA that is solid enough that testers didn’t have to spend the bulk of their time making sure the UI and the immediate interface with the database are working.

For years my schtick was to join a company when it is transitioning from small to mid-sized, when it was feeling crushed by quality problems caused by mounting technical and defect debt. They had focused on getting to market fast but had grown a tangled mess of code. My response was always to grow the QA team, primarily by hiring automation engineers to build out large automated regression suites.

After doing that at a couple companies, I lost interest in the strategy. It was expensive, it took too much time, and it never moved the quality needle enough. It just seems absurd to me now to prop up years of thin development practices with more post-development testing, especially given that automated tests in QA generally work through the UI and are therefore brittle and slow.

flood
The view from my deck after a particularly heavy rain. You’d better believe the sump pump was running.

It’s like when my home’s crawl space used to flood after each heavy rain. A company that specialized in drying out crawl spaces recommended $6,000 in a French drain, multiple sump pumps, and encapsulation to move the water out and keep the moisture from seeping up into the house. But a buddy of mine who builds houses said, “You’ve got a negative grade around your foundation. Buy $300 in topsoil and a couple cases of beer. Invite all your friends over and issue them shovels. Fix the grading and you’ll keep the water from getting in.” I went with the topsoil and the friends. I also put in one sump pump, just in case. It runs pretty much only when the rain is torrential.

In case my admittedly imperfect metaphor isn’t obvious, the graded topsoil is the unit testing, and the sump pump is the lightweight QA automation solution. Let’s try preventing the bugs from getting in as much as we can, shall we? But let’s still check for the odd and extreme cases that are bound to get by.

This is the hierarchy of testing similar to the one Mike Kelly recommends in this blog post. (He’s building on the work of Brian Marick, by the way, who gives a framework for testing in this blog post.) Mike recommends building on the order of thousands of automated unit and component tests, hundreds of automated business-logic tests, and tens of UI-level automated tests. The unit tests run fast and frequently. The inherently slow UI automated tests run far less often.

That’s what I resolved to try after I lost my will to build huge automated regression suites in QA. I deliberately took a QA leadership role with a company transitioning out of its startup phase. The product wasn’t yet too large and too saddled with technical and defect debt; I felt like we could make up the lost ground. After some encouragement from me, the fellow who ran engineering began insisting that developers write automated unit tests for all new code. We started building each release into an environment where developers could perform rudimentary testing on it themselves with realistic data. Their goal was to make sure all the happy paths work, so that when my testers get in there they are not immediately stymied by obvious critical bugs.

Before we started to make this transition, I quietly started tracking a simple little metric. I counted the defects QA found, plus the defects created in the release that were found in production, and divided by the number of development hours in the release. The metric was a little mushy because I was working with estimated and not actual hours, and because I was having to make judgment calls about which defects in production were caused by the release and which were latent bugs. But it’s hard to ignore the order-of-magnitude improvement we got on this metric. We were tracking to about .3 defects per development hour in the couple releases before we made these changes, and within two releases we dropped to about .05-.09 defects per development hour and held steady.

This had incredible impact. Initial quality went way up in QA, meaning initial quality went way up in production. Just adding these two steps was like flipping a switch not only on many of the quality challenges we faced, but also on the amount of chaos and churn we experienced as an overall engineering team.

A side benefit was that developers seemed happier. It wasn’t that writing tests made them happy – it didn’t. They would rather have built more new stuff. But delivering better code into QA meant that they spent less time in the fix-test cycle and were interrupted by way fewer production crises. They told me that finally they could focus.

The reason why I titled this post as I did – and it’s meant to be tongue in cheek, by the way – is because my strategy means hiring more developers and fewer testers. But the benefit to testers is that they get to do far more interesting work, going deeper, thinking more creatively, and exploring more technical kinds of testing.

I can’t imagine ever moving to an all-code testing strategy. All automated testing can do is repeat series of actions. Skilled human testers can cope with complexity and adapt to change, gain and synthesize knowledge and apply it to their testing, know from experience where the product is likely to be broken, and explore the system creatively. The kinds of products I’ve always delivered and am likely to keep delivering will always need that.