You're technical enough to use Docs-as-Code


During my interview for my last Technical Writer position, I was asked, “Do you have any experience with Docs-as-Code?” The company used it as its documentation solution, so it would’ve been nice if I had used it before. I had not. In fact, I had never heard of it. Apparently, I was charming enough to get the gig anyway, but I was nervous about my ability to learn the workflow quickly despite having been a Technical Writer for two years at that point. It turned out my concerns were unfounded, and not only did I flourish using Docs-as-Code, but for the past year and a half, I have made it my preferred documentation option. If you find yourself unsure of having enough technical prowess to wrap your head around Docs-as-Code, I will reassure you with this: if you’re the type of person who would peruse a page on this subject, you’re more than qualified to use Docs-as-Code.

You’re inherently somewhat technical

Chances are, since you’re here, you have some interest in what’s discussed on this page—either by personal curiosity or work obligation—which means you’ve met the prerequisite technical knowledge to be interested. Technical writing, in general, requires a base level of technical know-how (hence the name), and since you’ve found it’s an area of interest to you, you’ve already determined you’re capable of doing it.


If you’re a Technical Writer, it is your job to learn enough about the subject you write about to ensure your writing’s accuracy. For me, as someone who has been technical writing for five years, I’ve had to gain a working knowledge of all the fields I’ve been involved with, such as data management, information technology, audio equipment, gaming backend services, and even plastic molding. Each of my employers and I had the expectation that learning what was necessary was part of being a Technical Writer, and at no point did I question my ability to do so. I entered this discipline because I was able to use both sides of my brain in equilibrium, and every Technical Writer has this ability. Docs-as-Code is no more complex—and is oftentimes less so—than the technical fields a Technical Writer has to learn about.


People responsible for documentation that aren’t Technical Writers—such as Subject Matter Experts (SMEs) tasked with creating drafts—have even more incentives to want to use Docs-as-Code, as it attempts to move the needle closer to “technical” as opposed to “writing.” Docs-as-Code universalizes the tools and processes for everyone responsible for documentation, and you’re likely already using tools that require the same type of thinking no matter what field you’re in.

Docs-as-Code requires minimal technical knowledge

What you need to know to use Docs-as-Code is far less than what you already know just to fulfill your job requirements. For less (but still inherently somewhat) tech-savvy individuals, Docs-as-Code is extremely simple to set up and use. Any issues you run into can be resolved by finding them in the increasingly robust resources on the topic (such as docsascode.io!) or by asking a technical coworker to help you out for a few minutes. Heck, if you’re so inclined and aren’t put off by it (like I am, depending on my mood), ChatGPT can answer whatever questions you have in an instant. But once everything is set up—which will likely be done for you—and after you’ve used it a couple of times, you’re unlikely to encounter any problems.


For those of you who are primarily left-brained and already do technical stuff, Docs-as-Code will feel right at home. We know maintaining documentation can feel like a chore for you, but using Docs-as-Code in conjunction with tools such as those provided by docsascode.io will just feel like another minor step of the process you’re already doing, like remembering to turn off the lights before you leave the house.

Mistakes are easily reversible with Docs-as-Code

I have at least one story for every Technical Writing job I’ve had that didn’t have a Docs-as-Code workflow where a documentation mistake cost countless resources. They weren’t my mistakes, of course, since I’m incapable of making any, but if an engineer left an outdated spec in the manual or a PDF got sent out with a placeholder that an SME forgot to change, the effects on the company, its operations, and its reputation could be felt for weeks or longer. I was once a witness to a product manual that had to be recalled after being printed and included in the packaging due to a critical error so we could include a notice about logging on to the website to get an updated version of the manual. With Docs-as-Code, correcting a mistake like that is as simple as pushing a new commit to the documentation repository before anyone has a chance to see it.


If you are laying eyes on this text, I promise you that you are technical enough to use Docs-as-Code. As someone who has been in multiple fields as a Technical Writer, using it has been a game changer, and I wish I could have pitched adopting it to my previous employers. If you’re still not convinced or you have questions about how to get started with Docs-as-Code, reach out to the folks at docsascode.io so we can hook you up.


Written by: Randy Fluharty

Comments

Post a Comment

Popular posts from this blog

What is Docs-as-Code?

Image
The Docs-as-Code (DaC) approach to writing documentation has been gaining popularity in the last few years. Although it's a relatively new term, people have been using DaC-style workflows for almost as long as computers have existed. They just didn't call it "Docs-as-Code." The fact that lots of people have now heard the term is a testament to how many more people (and companies) are using the DaC workflow. To be clear, parts of this post will be my opinions about DaC. I've used some form of DaC for my entire career in the software industry, most recently as a Technical Writer. While it's true that some people raise objections to the DaC workflow, I find it telling that DaC is used both by startups and the largest software companies in the world. For example, Meta, LangChain.com, Python’s official documentation, Django docs, and Apache.org all use DaC. As with any approach, DaC has its own set of advantages and disadvantages. In this post, I’ll define the DaC ...
Read more

Is AI useful to Technical Writers?

Image
Since the head-spinning rise of ChatGPT , most people simply refer to the current crop of generative AI large language models (LLMs) as "AI." LLMs are powerful systems trained on extensive data and have opened new avenues in many fields, including journalism, creative writing, coding, and even visual design. However, when it comes to writing documentation, their use continues to be complex and nuanced. While generative AI is immensely helpful in some areas, it faces critical challenges in others, particularly due to its inability to validate the truth of its own outputs. In this post, I’ll explore the specific strengths and limitations of LLMs in the domain of technical writing and some best practices for using them effectively. I should also say up front that I'm currently employed as a Technical Writer, so I have some understandable biases when it comes to this subject. However, I am definitely not in the camp of people who dismiss AI outright. In fact, I'm currentl...
Read more