What Does a Technical Author Do?

If you wish to work in tech however choose writing phrases to code, technical writing could possibly be your dream job. To be taught extra about what a Technical Author truly does (and the way a lot writing and/or coding is concerned) we requested Mike Jang, a Technical Author for over 20 years who’s at the moment a Principal Technical Author for NGINX at F5. 

What does a Technical Author do? 

Within the easiest phrases, a Technical Author writes directions (often known as documentation) for customers of merchandise. Within the context of constructing and deploying software program, documentation is often for builders, however Methods Directors, Safety Engineers, and DevOps Engineers can all fall below this umbrella too.  

Earlier technical writing sometimes catered to the top customers of merchandise somewhat than builders and maintainers. However since most shopper apps are designed to be self-explanatory for customers, documentation is now often for builders and different practitioners who create, run, and keep the underlying software program and infrastructure of these apps. Technical writing is completely different from UX writing, which refers back to the phrases you discover inside digital merchandise (corresponding to navigation bars, menus, and buttons).  

What does a typical workday seem like for a Technical Author? 

Whereas writing documentation is the obvious a part of a Technical Author’s job, it’s truly the factor you’ll in all probability spend the least period of time on in your day-to-day work. “I write perhaps 1 / 4 of my time,” says Mike. The remainder of the day is made up of actions like: 

• Organising and testing software program 
• Determining the method and schedule for releasing a brand new function 
• Figuring out and submitting bug stories 

Technical Writers sometimes write about model new options that haven’t been documented or launched but, Mike says. Experimenting on this early stage naturally results in discovering bugs and collaborating with growth to find out workarounds. Whereas submitting bugs seems like a diversion, Mike says it’s truly an enormous a part of what makes the function rewarding. “After I lastly get to the answer, I believe, ‘Wow, this truly works! I can’t wait to write down about this.’” 

Do you want to have the ability to code to be a Technical Author? 

At some firms, Technical Writers will take documentation written by builders and course of it into readable language that adheres to an org’s documentation requirements and elegance information, or write documentation primarily based on interviews with the builders who wrote the code. In these circumstances, you don’t must have expertise with programming, however Mike is an enormous advocate for getting hands-on with the product you’re writing about. “Personally, I don’t really feel I can write with credibility about one thing until I’ve used it myself,” he says.  

There are just a few conditions the place Technical Writers want some coding information: 

Implementing Docs as Code 

Docs as Code, the philosophy that try to be writing documentation utilizing the identical instruments as with code, is rising in popularity within the tech writing neighborhood. Underneath this mannequin, Technical Writers use code instruments like model management and steady integration to create, course of, and publish documentation. This method helps Technical Writers work in higher alignment with growth workflows and guarantee consistency all through a product’s documentation.  

“You wish to ‘write as soon as, publish in every single place,’” Mike says. “So, you utilize the identical terminology and explanations to explain technical ideas all through your documentation.” For instance, you’ll be able to set variables to retailer an evidence, after which pull that variable in wherever you want it within the documentation.  

Getting comfy with this workflow, terminology, and instruments (like GitHub) will allow you to stand out for those who’re beginning a profession in technical writing. Our Study Git & GitHub course is a superb place to begin.  

Collaborating with growth 

Whereas Technical Writers aren’t tasked with coding themselves, collaborating with builders is a big a part of the job. In these eventualities, it’s all the time helpful to be prepared and prepared to dig into the code your self. “If I check out a brand new function and one thing doesn’t work as anticipated, I can go to the builders and say, ‘I’ve tried out these steps, that is the way it’s purported to work, however what I’m seeing doesn’t match,’” Mike says. “Now we’re partnering on an answer as an alternative of my request getting thrown right into a backlog.” 

Working with code snippets 

It’s widespread for documentation to incorporate code samples, so it’s useful for those who’re capable of write or evaluate these your self, Mike says. “Consider the completely different single sign-on choices you often have now — you’ll be able to sign up with Google, with Amazon, and so forth,” says Mike. “These suppliers embrace code snippets which you’ll incorporate into your organization’s software program, however you could perceive if the defaults work in your case, otherwise you (or your readers) may have to change their snippets.”  

Undecided the place to begin with regards to studying to code? Try the talent path Code Foundations to get launched to primary coding ideas that translate throughout programming languages and domains.  

Do you could be a robust author? 

Whereas loads of Technical Writers occur to have English or Communications levels, being a refined author is much less necessary than being a transparent thinker and communicator on this function, Mike says. “If somebody’s considering is obvious, that comes throughout of their writing. A powerful grasp of language is, I believe, going to grow to be much less necessary sooner or later,” he says. “There are already AI instruments that may allow you to enhance the grammar and readability of your work (like Grammarly, or the Hemingway app).” 

Whereas different writing in tech (corresponding to content material advertising or copywriting) is for storytelling, persuasion, and engagement, technical writing is about speaking with readability and accuracy. “You’ll discover distinct variations between advertising fashion guides and technical writing fashion guides,” says Mike. “Technical writers by no means use phrases like ‘easy’ or ‘straightforward’!”  

What function is AI enjoying in technical writing? 

Whereas AI shouldn’t be about to automate Technical Writers out of their jobs, AI writing instruments can assist make technical writing extra environment friendly. That’s, so long as the instrument is safe and doesn’t expose proprietary firm information or code (this truly occurred at Samsung final yr). There are methods round this threat, corresponding to supplementing a big language mannequin with a “small language mannequin” of proprietary info that’s stored safe.  

Like different AI practitioners, Technical Writers need to discern the suitable time to make use of AI instruments and perceive their limitations. “Your organization may need an enormous Confluence web page with loads of proprietary details about how your product works,” says Mike. “An AI instrument can course of that right into a decently written abstract which a human can then evaluate and edit — doubtlessly big-time financial savings for Technical Writers.” 

Do you want a technical writing portfolio? 

Some technical writing job purposes will ask for writing samples. “An organization would possibly ask you to write down an outline of find out how to create a peanut butter and jelly sandwich, for instance,” says Mike. (The sandwich train is a part of our Code Foundations talent path if you wish to attempt it for your self!) 

In lots of circumstances, you should utilize an present pattern if you have already got some technical writing expertise that’s related to the business and function you’re making use of for. Don’t panic for those who don’t have samples although — you’ll be able to write one thing unique primarily based on the applying necessities. If you happen to’re actively job searching, it’s value making a portfolio web site: “Creating a web site utilizing any cheap Docs as Code instrument will illustrate not simply your writing experience, however your capability to make use of technical documentation instruments,” says Mike. You possibly can take a look at Mike’s personal skilled web site, which he constructed with GitLab and the Hugo static web site generator, for instance.  

If you happen to’re seeking to construct your portfolio of technical writing, think about contributing to Codecademy’s Docs. 

The place to attach with Technical Writers 

Mike recommends just a few communities to attach with Technical Writers and others seeking to get into the sphere: the Society for Technical Communication, Write the Docs, and Content material + UX are good locations to begin. These may also be good locations to get a way of present Technical Author salaries for those who’re simply beginning out (listed here are some extra ideas for negotiating entry-level salaries).