Posts

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

Image
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 thi...
Post a Comment
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...
Post a Comment
Read more

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 ...
Post a Comment
Read more