From HTML to AI: What the modern technical writer’s toolkit looks like

Learn what tools and techniques industry experts use from this roundtable discussion on technical writing.

To celebrate the National Day on Writing on October 20, we met with several technical writers and technical editors for a virtual roundtable discussion. Ashley O’Brien (City of Saint Paul), Seth Kenlon (Red Hat Software), Jason Hibbets (Soul Surfer Consulting and managing editor at We Love Open Source), and Jim Hall (Hallmentum) talked about a range of topics, including the tools professionals use in their roles, the skills you need as a technical writer, and the importance of general skills in the field.

We’ve shared the full video, but here are a few highlights from our discussion below.

We rely on different skills

Jason emphasizes the importance of knowing HTML basics and staying updated on changes. Jason deals with various file formats but primarily works in Google Docs and Markdown. He relies on Grammarly and has recently started using ChatGPT for tasks like generating better title options and, summarizing video scripts. Jason mentions the “human in the loop” concept, where AI assists but content is reviewed by a human before publication.

Ashley discusses her work in prototyping and concept creation, using collaboration software like SharePoint, Google Docs, and Mentimeter. She uses Adobe XD and other prototyping tools. For note-taking and organizing insights, she uses OneNote and Microsoft Lists. Ashley checks work readability with the Hemingway app and focuses on knowledge management tools for self-help resources.

Seth mentions using GitHub, DocBook, Markdown, and other low-overhead structured texts. He highlights the importance of understanding basic tools like XML and Markdown and content management systems like Drupal and WordPress. Seth notes that with experience, anyone can quickly adapt to new tools, emphasizing a broad view of tooling to carry knowledge into new projects.

An art and a science

Seth emphasizes that a lack of knowledge in a particular area can be a strength, as it prevents assumptions. He highlights the importance of understanding the process and precision in technical writing, using the example of order of operations in instructions. Precise language is crucial, as words have specific meanings, and distinctions like “can,” “should,” and “must” are vital.

Jason adds the importance of collaboration, communication (written, verbal, and video), and focus. He compares technical writing to coding, where minimal context switching is necessary to avoid mistakes.

Ashley views technical writing as both an art and a science. She emphasizes design skills, problem-solving, and knowing when to seek inputs. The art aspect involves empathy, curiosity, and incorporating one’s style and experience. She underscores the importance of continually refining technique by staying connected with others in the field and learning from best practices.

Tools in your virtual toolkit

Ashley emphasizes starting with research and practicing writing research questions. She suggests learning project management tools like Trello and Kanban methodology and encourages professional networking for primary research.

Seth agrees and shares his approach of aligning his knowledge with job expectations, and quickly learning new technologies when needed. He also mentions the value of knowing a general scripting language for automating processes. Seth emphasizes the importance of having a compulsion to try new things, likening it to a programmer mindset where understanding the order of operations is crucial. He stresses the value of being curious and continuously learning new tools and technologies.

Jason adds that understanding organizational tools like Trello and Basecamp is crucial for content management during the editing process. Jason advises building a portfolio, understanding the target audience, and possibly starting a blog to gain experience. He also highlights the importance of contributing to blogs and publications, especially those related to open source.

---

Thanks to Jason, Seth, and Ashley for this engaging discussion about technical communication.

More from We Love Open Source

• Enhance your writing skills with Ollama and Phi3
• A quick guide to create an efficient rubric using genAI
• Getting started with Llamafile tutorial
• Harness the power of large language models part 1: Getting started with Ollama

This article is adapted from “Technical writing roundtable” by Jim Hall, and is republished with permission from the author.