When looking for candidates, would you rather hire a writer who learned programming, or a programmer who learned writing? There are pros and cons to each approach. Let’s first examine writers who learn programming, and then in the next section look at the reverse: programmers who learned writing.
In Enough to Be Dangerous: The Joy of Bad Python, Adam Wood argues that tech writers don’t need to be expert coders, on par with developers. Learning to code badly (such as is usually the case with writers who learn to code) is often enough to perform the tasks needed for documentation. As such, Wood aligns more with the camp of writers who learned programming. Wood writes:
Wood says tech writers who are learning to code frequently underestimate the degree of difficulty in learning code. To reach developer proficiency with production-ready code, tech writers will need to sink much more time than they feasibly can. As such, tech writers shouldn’t aspire to the same level as a developer. Instead, they should be content to develop minimal coding ability, or “enough to be dangerous.”
James Rhea, in response to my post on Generalist versus Specialist, also says that “adequate” technical knowledge is usually enough to get the job done, and acquiring deeper technical knowledge has somewhat diminishing returns since it means other aspects of documentation will likely be neglected. Rhea writes:
In other words, if you spend excessive amounts of time learning to code, at the expense of tending to other documentation tasks such as shaping information architecture, analyzing user metrics, overseeing translation workflows, developing user personas, ensuring clear navigation, and more, your doc’s technical content might improve a bit, but the overall doc site will go downhill.
Additionally, while engineers can fill in the deep technical knowledge needed, no one will provide the tech comm tasks in place of a tech writer. As evidence, look at any corporate wiki. Corporate wikis are prime examples of what happens when engineers (or other non-tech writers) write and publish documentation. Some pages might be rich with technical detail, but the degree of ROT (redundant, outdated, trivial content) gets compounded, navigation suffers, clarity gets muddled, and almost no one can find anything.
Now let’s flip to the other side of the argument. What are the advantages of hiring programmers who learned writing? In contrast to Wood and Rhea, James Neiman, an experienced API technical writer, says that tech writers need engineering backgrounds, such as a computer science degree or previous experience as an engineer, to excel in API documentation roles.
Neiman says tech writers often need to look over a developer’s shoulder, watching the developer code, or listen to an engineer’s brief 15-minute explanation, and then return to their desks to create the documentation. You might need to take the code examples in Java and produce equivalent samples in another language, such as C++, all on your own. In Neiman’s view, API technical writers need significant technical depth to excel in this role.
Neiman and Andrew Davis (a recruiter for API tech writers in the Bay area) recently gave a presentation titled Finding the right API Technical Writer at an API conference in London. Their presentation format includes a Q&A exchange between the two. Scrub to around the 22-minute mark for the relevant part:
Here’s a transcript of two questions in their exchange (cleaned up a bit for readability):
Keep in mind that Davis and Neiman are trying to persuade more European countries to use Synergistech as their recruiting agency to find and hire API tech writers, so they’re presenting the need for engineering-savvy tech writers. These super tech-savvy writers are harder to find — hence the need for expert recruiters. Regardless of the agenda, Neiman and Davis argue for a higher level of coding proficiency than Wood or Rhea.
The level of coding knowledge required no doubt depends on the position, environment, and expectations at your company. Perhaps if the tech writer doesn’t have more of an engineering background, engineers will just send the tech writer code snippets to paste into the docs. But without the technical acumen to fully understand, test, and integrate the code in meaningful ways, the tech writer will be at the mercy of engineers and their terse explanations or cryptic inline comments. The tech writer’s role will be reduced to being an editor/publisher instead of a writer.
In my experience, Neiman’s explanation about developers instructing tech writers to create similar code in other languages (based on a 15-minute over-the-shoulder conversation at the engineer’s desk) goes too far. Although I’ve created simple JavaScript code samples (based on a pattern the engineers showed me), I’ve never been asked to create code samples across other languages. I could auto-generate code snippets for web API requests (using Postman), but to develop code across multiple languages tends to be more of the programmer’s responsibility, not the tech writer’s.
Neiman goes on to say that in one company, he tested out the code from engineers and found that much of it relied on programs, utilities, or other configurations already set up on the developers’ computers. As such, the engineers were blind to the initial setup requirements that users would need to run the code properly. Neiman says this is one danger of simply copying and pasting the code from engineers into documentation. While it may work on the developer’s machine, it will often fail for users.
This comment from Neiman does ring more true to me. As I argued for extensively in Testing your API documentation, you have to be able to test the endpoints, code samples, and SDKs in order to write and evaluate the documentation. It is usually true that programmers (who set up their machines months ago) have long forgotten or can’t even identify all the frameworks, configurations, and other utilities they installed to get something working. The more technical you are, the more powerful of a role you can play in shaping the information.
Neiman is a former engineer and says that during his career, he has probably worked with 20-25 different programming languages. Being able to learn a new language quickly and get up to speed is a key characteristic of his tech comm consulting success, he says.
But in this celebration of technical knowledge, companies make a mistake and assume that these programmers-turned-technical writers can easily handle writing tasks, because c’mon, everyone can write, right? However, without a stronger writing background, these programmers who are now writing might be a lot less proficient in areas where it really matters.
For example, recently I was working with an engineering team on a new voice feature for our product. The engineering team was partly based in India and other places, and they frequently met (during India business hours) to shape a document about the new voice feature. This documentation and the feature were in constant flux, so the team kept iterating on the content over the course of about two weeks after meetings with stakeholders, solutions architects, and other reviewers. After each review, the team sent me the document to edit and publish it for stakeholder reviews.
I wasn’t directly embedded with the team, nor was I a dedicated resource for the team. In this role, I simply acted as editor and publisher. But I had to turn around the gibberish they wrote at a rapid rate, usually in 1-2 hours. As this project was one of many I was juggling, I had to quickly restructure and rewrite the content (sometimes touching every sentence) to make it read like a native speaker had written it rather than engineers in another country. During this same time, I was working on rewriting our team website and other writing projects.
I have a tech writing colleague who is a former engineer, and I often wonder if he has the same writing skills to edit this content with the same speed and efficiency that I do. Of course, I shouldn’t make judgments, but I’m pretty good at both writing and editing. After all, look at the output on my blog. In just a couple of hours during the evening, I can write a post that is worth reading in the morning. Can engineers who lack writing backgrounds do this? If tech writers are increasingly playing publishing/editing roles instead of developing content directly (because the content is so highly technical that only specialists can create it), then shouldn’t companies prioritize writing abilities over technical abilities (to an extent)?
Further, companies who assume that “everyone can write” fail to distinguish the different levels of writing. It’s one thing to write coherent sentences in a paragraph or even a single topic, but can the writer read over 20 pages in a documentation system and ensure consistency across all the topics? Can the writer weave together workflows and journeys across these larger systems? Can the writer distill information from a long, complicated process into an intelligible quick reference guide? Writing skills fall along a spectrum, and while most professionals appear somewhere on the spectrum, their skills might not be enough to excel in ways that provide deeper value for documentation.
Overall, technical writers of all stripes are playing generalist roles in increasing ways, and in these generalist roles, strong writing skills rather than specialized knowledge might be more important. For sure, a combination of the two skills — writing and technical expertise — tends to be a knockout punch in the job market.
For an in-depth analysis of the dilemma between being a generalist or specialist, see my essay Be both a generalist and specialist through your technical acuity in my Simplifying Complexity series.
Wide, not deep understanding of programming
Let’s settle the question about the best candidate to hire by finding some middle ground between the two extremes. Clearly, tech writers need to understand code, but they probably don’t need to be engineers to the extent that Neiman argues (writing their own code in other languages).
Although you might have client implementations in a variety of programming languages at your company, the implementations will be brief. The core documentation needed will most likely be for the REST API, and you will have a variety of reference implementations or demo apps in these other languages.
You don’t need to have deep technical knowledge of each of the platforms to provide documentation. You’re probably just scratching the surface with each of these client SDKs. As such, your knowledge of programming languages has to be more wide than deep. It will probably be helpful to have a grounding in fundamental programming concepts and familiarity across a smattering of languages instead of in-depth technical knowledge of just one language.
Having broad technical knowledge of multiple programming languages isn’t easy to pull off. As soon as you throw yourself into learning one language, the concepts will likely start blending together.
And unless you’re immersed in the language on a regular basis, the details may never fully sink in. You’ll be like Sisyphus, forever rolling a boulder up a hill (learning a programming language), only to have the boulder roll back down (forgetting what you learned) the following month.
Full immersion is the only way to become fluent in a language, whether referring to programming languages or spoken languages. As such, technical writers are at a disadvantage when it comes to learning programming. To get fully immersed, you might consider focusing on one core programming language (like Java) and only briefly playing around in other languages (like Python, C++, .NET, Ruby, Objective C, and JavaScript).
Of course, you’ll need to find a lot of time for this as well. Don’t expect to have much time on the job for actually learning a programming language. It’s best if you can make learning programming one of your “hobbies.”
Strategies to get by in deeply technical situations
Suppose you find yourself deep in APIs that require you to know a lot more technical detail than you currently do (despite your programs of study to learn more)? How can you get by without a deeper knowledge of programming?
Keep in mind that your level of involvement with editing, publishing, and authoring depends on your level of tech knowledge. If you have a strong knowledge of the tech, you can author, edit, and publish. If you have weak tech knowledge, your role might involve publishing only. The following spectrum diagram illustrates this range of involvement:
If you’re stuck in the publishing/editing area, you can interview engineers at length about what’s going on in the code (record these discussions — Evernote has a nifty recording feature built-in that I’ve used multiple times for just this purpose), and then try your best to describe the actions in as clear speech as possible. You can always fall back on the idea that for those users who need Python, the Python code should look somewhat familiar to them. Well-written code should be, in some sense, self-descriptive in what it’s doing. Unless there’s something odd or non-standard in the approach, engineers fluent in code should be able to get a sense of how the code works.
In your documentation, you’ll need to focus on the higher-level information, the “why” behind the approach, highlighting of any non-standard techniques, and the general strategies behind the code. You can get this why by asking developers for the information in informational interviews. The details of what will either be apparent in the code or can be minimized. (See Code samples and tutorials for details.)
As you decide how much detail to include, remember that even though your audience consists of developers, it doesn’t mean they’re all experts with every language. For example, the developer may be a Java programmer who knows just enough iOS to implement something on iOS, but for more detailed knowledge, the developer may be depending on code samples in the documentation. Conversely, a developer who has real expertise in iOS might be winging it in Java-land and relying on your documentation to pull off a basic implementation.
More detail in the documentation is always welcome, but you can use a progressive-disclosure approach so that expert users aren’t bogged down with novice-level detail. Expandable sections, additional pages, or other ways of grouping the more basic detail (if you can provide it) might be a good approach.
There’s a reason developer documentation jobs pay more — the job involves a lot more difficulty and challenges, in addition to technical expertise. At the same time, it’s just these challenges that make the job more interesting and rewarding.
Techniques for learning code
The diversity and complexity of programming languages is not an easy problem to solve. To be a successful API technical writer, you’ll need to incorporate a regular regiment of technical study. You always have to be learning to survive in this field.
Fortunately, there are many helpful resources (my favorite being O’Reilly’s Safari Books Online). If you can work in a couple of hours a day, you’ll be surprised at the progress you can make.
The difficulty of learning programming is probably the most strenuous aspect of API documentation. How much programming do you need to know? How much time do you spend learning to code? How much priority should you spend on learning technology?
For example, do you dedicate two hours a day to learning to code in the particular language of the product you’re documenting? Should you carve this time out of your employer’s time, or your own, or both? How do you get other doc work done, given that meetings and miscellaneous tasks usually eat up another 2 hours of work time? What strategies should you implement to learn code in a way that sticks? What if what your learning has little connection or relevance with the code you’re documenting?
In a post called Strategies for learning technology – podcast recommendation and a poll, I linked to a 10-minute Tech Comm podcast with Amruta Ranade on Learning New Technology and then polled readers to learn a little about their tech learning habits. In the reader responses, most indicated that they should spend 30-60 minutes each day learning technology, but most spend between 0-20 min actually doing so. To learn, they use general Google searches. They mostly devote this time to learning tech at work, though some split the time between work at home.
Personally, I think spending 20 minutes a day isn’t enough to keep up with the knowledge needs. Sixty minutes is more appropriate, but really, if you want to make progress, you’ll need to devote about twice that time. Finding 1-2 hours of time (and motivation) at work to learn it is unlikely. I always feel like I’m not getting enough done as is during work hours — learning technology often feels like a side activity taking me away from my real duties.
Also, the information I need to document in the present moment is usually too advanced to simply learn from watching tutorials on Safari Books or other sources. But I can’t just start out consuming advanced material. I have to ramp up through the foundational topics first, and that slow ramp-up feels like a tangent to the real work that needs to get done.
For example, you might need to document the equivalent of Advanced Calculus concepts. But to ramp up on Advanced Calculus, you need to build a foundation with Trigonometry and Algebra. When you spend time studying Trigonometry and Algebra instead of the Advanced Calculus concepts that you need to document, it can feel like you’re not making any progress on your documentation.
One strategy I’ve found to work well is to divide the learning into “pomodoros” (a technique named after tomato kitchen timers). With the Pomodoro Technique, you set a timer for 20 minutes and focus on your learning task for that chunk of time. You can set a goal to complete as many pomodoros a day as you want. After about 1-2 months of these regular pomodoros, you’ll be surprised at your progress. I use the Focus app for my pomodoro timer:
Additionally, I recommend keeping a list of notes about technical details you struggle with while you’re trying to document something, and then during your pomodoros, focus on what’s listed in your technical notes.
Even so, this pomodoro technique for focus doesn’t solve the problem. It’s still hard to squeeze time in for the pomodoros. Whenever I squeeze these into my life, I end up squeezing other activities out.
There are a lot of questions about just how to learn code, and I don’t have all the answers. But here’s what I know:
- Developer documentation requires familiarity with code, though exactly how much expertise you need is debatable.
- You have to understand explanations from engineers, including the terms used. The explanations in your documentation should focus on the why more than the how.
- You should be able to test code from engineers so that you can identify assumptions that engineers are often blind to.
- To thrive in an API documentation career, you have to incorporate a regiment of continual learning.
- Completing several pomodoros a day over the course of weeks and months can result in significant progress in building your technical understanding.
Is being a generalist a career disappointment?
Technical writers will likely be generalists with the code, not good at developing it themselves but knowing enough to get by, often getting code samples from engineers and explaining the basic functions of the code at a high level.
Some might consider the tech writer’s bad coding ability and superficial technical knowledge somewhat disappointing. After all, if you want to excel in your career, usually this means mastering something thoroughly, right? You want to be an expert in your field.
It might seem depressing to realize that your coding knowledge will usually be kindergartner-like in comparison to developers. This disparity positions tech writers more like second-class citizens in the corporation. In a university setting, it’s the equivalent of having an associates degree where others have PhDs.
However, take consolation in the fact that your job is not to code but rather to create helpful documentation. Creating helpful documentation isn’t just about knowing code. There are a hundred other details that factor into the creation of good documentation. As long as you set your goals on creating great documentation, not just on learning to code, you won’t feel entirely disappointed in being a bad coder. This perspective doesn’t address all the issues, but it does provide some consolation at the end of the day.
For more information about working with code, see these two topics:
- SDKs
- Code samples and tutorials
Let’s look at one more topic in this jobs section: Locations for API doc writer jobs.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
116% Complete
116/165 pages complete. Only 49 more pages to go.
« Previous: The job market for API technical writers
© 2024 Tom Johnson
