Learning to code as a technical writer

A recurring question from people entering the tech writing profession is “Should I learn to code?”. This query has become hugely popular in the docs-as-code age, where writers and developers live in the same DevOps trenches, eating the same CI/CD rations and publishing docs using broken tools that often lack maintainers.

My answer is “These are not the learnings you’re looking for.”

You don’t want to learn how to code. What you want to learn is how to make your life easier and more pleasant when working all day with developers, because that’s what being an embedded docs-as-code technical writer means these days. Learning to code is a valid, if not very direct, way of accomplishing the goal of becoming a developer’s ally, though it kind of misses the point. It doesn’t help that the term “coding” has become full of life-changing promises, a trend that has led people to sign up to expensive bootcamps that teach you the elements of masonry and then tell you can build the St. Peter’s Basilica.

What bootcamps apparently fail to acknowledge is that learning how to code is not enough to become a software engineer, as knowing English is not enough to become a technical writer. For developers, coding is simply a tool, an enabler. Senior developers don’t code that much; instead, they spend their time reviewing other people’s code, analyzing complex problems, and figuring out how systems can react to growth. Similarly, senior tech writers don’t write that much, working instead on gathering information and planning for impact (unless you’re still at stage two of the docs hierarchy of needs).

Of course you need to know how to code in order to build software, but you can’t make it your main priority. You have your own docs priorities already.

Start the journey from your needs

Unless you’ve an insatiable appetite for knowledge (in which case you won’t mind spending a weekend coding tic-tac-toe in OCaml) I’d argue that learning how to code like a software developer is a partial waste of a time if you’re a technical writer. Many have tried and ended up so frustrated that they gave up on the topic entirely, to the point of adopting the stance of shunning code and focusing on words instead. To avoid burning out while approaching the software development mindset, the best thing you can do is to start the journey from the things you care about the most at work: the documentation you produce.

You’re already using tools that are nothing but a bundle of scripts and structured data that outputs HTML and runs on containerized infrastructure. Start by wondering how all that works, and how you can improve it. Perhaps there’s a process that could be more efficient or faster, or there’s an error message that has been haunting you since you joined the company. Maybe you’d like to improve the look and feel of the documentation, making the callouts a little more handsome. Whatever the reason, it must stem from something that resonates with your objectives. Consider the development of tools such as Pandoc, Vale, or the Docsy theme: All are software projects that facilitate technical writing, and were either created by technical writers or benefited from the continuous feedback and support of technical writers as testers, documentarians, or stakeholders.

It doesn’t have to be just tools: A fantastically good way to begin your learning path is to improve the act of writing documentation. For example, you might want to contribute in a more direct way to API design, add automatic checks when docs are built, or understand how the product UI is made so that you can find opportunities for bringing docs closer to the user. It requires learning things like OpenAPI, YAML, JSON, data structures, dependency management, continuous delivery, curl, make, and so on. It might not look like coding to you, in the sense of furiously typing random C++ code in a green phosphor terminal, but, trust me, it’s already what developers spend a sizable chunk of their time with every day. All the cloud scaffolding, metadata editing, build and release automation, code commenting: all that is software development already.

You do that, you become a devling*.

The benefits of becoming a devling

The first upside of learning how to use developer’s tools for your own benefit is that you become more autonomous and less dependent on engineering time, which is a blessing, because engineers are almost invariably busy and hate being interrupted to answer your questions. You can become an early user and tester, merging slightly with the role of QAs and technical support, to the point you’d suggest improvements in how things are deployed or configured. Here are more things you’d do that would make your engineering team happy:

• Build and run the product yourself.
• Create add-ons to a docs site using Python or MDX.
• Modify CSS or JS to fix something in the docs site.
• Automate docs stuff using PowerShell or Python.
• Edit strings meant for CLI output in code.
• Design and document APIs using OpenAPI (YAML).

Engineers will never ask you to do anything more complicated than running a shell script or composing a curl command. As a technical writer, you do the same every day: You never ask developers to come up with a new content template. In some specific cases, you might be asked to create sample apps, a task for programmer writers and devrels. Your code doesn’t have to be a masterpiece, though; it just has to work. It must be reviewed by an engineer anyway.

The second benefit of becoming a devling is that you can grow into a trusted coding associate in several niche areas in which many developers might not be proficient, such as OpenAPI design, markup languages, structured content, prose linters, static-site generators, and so on. You know that feeling of admiration and respect you experience when developers do their best to provide clean drafts and use the Oxford comma while learning from your edits? Developers will feel the same when you show them a PR that follows their coding standards to improve code comments or format the CLI output of their scripts.

So, no, don’t “learn to code”. Learn to help yourself using code.

Clarification: my stance is not “you don’t need to learn coding, ever”. What my post says is “be strategic about what you learn and how”. Having coding knowledge can make all the difference, but if I was an employer, seeing a coding badge or coding course in your resume wouldn’t tell me a lot. I want to know what you’ve made with it that had an impact on docs and your workflow, how it helped you solve problems and improve collaboration.

* Devling: Young developer, developer spawnling.