Write the Docs: Putting the “tech” in technical writer – Swapnil Ogale

This talk at Write the Docs Portland 2021 was given by Swapnil Ogale. Swapnil is a technical writer at Redocly (and a guest blogger here at KnowledgeOwl!). He has worked on a number of software projects in the area of documentation. He helped found the Write the Docs community in Australia. 

This talk was about how we as documentarians can embrace the technical toolset and methodologies used by developers, and embrace a Docs-as-Code workflow. It was inspired by a recent experience in Swapnil's job search. The role was essentially creating documentation for developers, but he wasn't hired because he didn't have enough experience in coding and programming. This got him thinking about how technical writers can gain that added experience.

Tools that technical writers use

Speaking to other technical writers over the years, Swapnil realised he was not alone. He had experience with Markdown, Git, and static site generators, but how do technical writers transition from just being product writers to adding a bit of tech to their arsenal? 

Swapnil mentioned the tools that we commonly use as technical writers including Word, Help Authoring Tools like Madcap Flare, and vector image software like Madcap Capture, and noted that these existing tools can be a great way to transition into some technical aspects. For example:

• Microsoft Word is a collection of XML files. Say a fellow technical writer sends you a .docx file but you can’t open it. You can directly edit the XML files. (You can also familiarize yourself with XML structures this way!)
• Help Authoring Tools like Madcap Flare allow you to manipulate content in an XML format. You can view your documents in simple text and also XML view. 
• You can also open a vector graphic in a text editor and manipulate the image, for example by adding colors or resizing the image.

So it turns out that technical writers are more technically inclined than you might think! There are plenty of tools to sink your teeth into. 

Transitioning to Docs-as-Code 

Swapnil also talked about transitioning into a Docs-as-Code methodology. Docs-as-Code processes are not that different from the normal tech documentation lifecycle. You still need to plan your documentation and contact subject matter experts. But switching to Docs-asCode can offer a better aligned review experience since you’ll be using the same tools and workflows as the technical team. 

Docs-as-code allows you to get familiar with tools like issue trackers, plain text, version control, code reviews, and automation. The work processes technical writers use can mimic those of the development team, and as he mentioned, you can even try adopting the same development methodology as your development team--if they're using scrum, you can too.

Swapnil noted that an added benefit of this approach is that when you’re working alongside agile teams, it helps team members have better visibility and accountability when it comes to documentation. 

Using Git

Swapnil also noted that many writers have never encountered Git, but it's worth learning it. His advice? Don't be intimidated by this tool – just get practicing. Swapnil recommended asking the development team for a walkthrough on how to use Git.

Using Git in your document workflow is a key part of Docs-as-Code. Here's a screenshot Swapnil provided of a typical workflow with GitHub: 

You can add commits and then ask for feedback from developers. Your documentation code might live on separate branches but you’re still using the same tools as the rest of your team. 

The importance of plain text 

Swapnil also suggested that you should use plain text formats like Markdown or reStructuredText. It’s easy to read and write, easy to learn, lightweight, no interruptions, and platform-agnostic so your content is not tied to what you’re using to create it. You can learn how to use it in a couple of hours. Many editors that support these formats allow you to preview your plain text before you publish it. It makes collaboration really easy. 

The criticisms of plain text include being limited in terms of style, and a loss of formatting compared to WYSIWYG tools.  

Working with toolchains

Swapnil argues that documentation reviews can be a major sticking point, especially if the review workflow involves multiple tools and workflows.

Swapnil sees Docs-as-Code as a solution to this problem. In a Docs-as-Code environment, you’re using the same toolchain as the product team, so that removes tool adoption friction and smooths out the entire process. You get to focus on the content rather than the tooling, and it’s quicker and more efficient. Automate it once, and get back to documenting. 

Swapnil noted that he's had to beg management to get the tech writing team a decent reviewing tool, and has had to ask permission to use similar tools to the development team but more customized for the tech writer. 

Whatever tools you use, you can tailor them to your needs for the documentation. And, of course, document your toolchain so you can hand off the project to another writer in the future.

Final remarks 

Swapnil offered a number of ways for tech writers to gain access to more technical tools and structures. Above all, he noted that it’s really important for technical writers to stay curious and learn more about technologies. Finding docs-as-code tools or different options within tools you already use to deepen your technical knowledge can be a great way to keep your education moving forward, so that your technical/coding skills become an argument in favor of hiring you, rather than not.

Watch the full talk here.