VS Code as a Documentation tool? Sounds interesting? Unusual even…
As a technical writer myself, having spent over a decade in this field – I found it awkward when I first learnt from a colleague that Razorpay Documentation uses VS Code for authoring. It was the second day at work, and I was still undergoing the Induction and Training sessions. My first thought was, “Did I make the right decision? How did I miss asking about the authoring tool we use during my interviews?”
Perplexed and yet, curious about what was in store, I embarked on this journey. My very skilled colleague trained me on VS Code and how it can be used as an authoring tool. I was awed at both its simplicities as well as complexities at the same time.
The ‘Docs-as-code’ approach
Before we talk about VS Code, let us understand what ‘Docs as Code’ is.
Documentation as Code or more popularly known as ‘Docs as Code’, refers to an ideology that you should treat documentation in the same way as you would treat coding, including using the same tools as code. Some examples include:
- Issue Trackers such as Jira, Asana
- Plain Text Markup such as VS Code
- Version Control such as Helix, GitHub
- Code Reviews such as GitHub
- Automated Tests such as Selenium, Postman
This methodology presses upon following the same workflows as development teams to ensure there is total synchronization with the Product Teams. Unlike in a regular framework, the Docs-as-Code approach lays emphasis on giving equal responsibility to Technical Writers and Developers for maintaining Technical Documentation.
VS Code as an Authoring Tool
Yes, it is not uncommon anymore to come across Technical Writers who use Visual Studio Code (VS Code) as their preferred text editor for writing technical documentation. VS Code is a popular and powerful code editor developed by Microsoft that offers a wide range of features and extensions that can enhance the writing process.
It is comparable to most WYSIWYG editors in terms of the features offered:
- Rich text editing: VS Code provides a robust text editing experience with features like syntax highlighting, code completion, and automatic formatting, which can be beneficial for writing technical documentation with code snippets or formatting requirements.
- Markdown support: Markdown is a lightweight markup language commonly used by technical writers for creating documentation. VS Code has excellent Markdown support, including previewing and rendering Markdown files, making it a convenient choice for creating and editing Markdown-based documents.
- Extensions and plugins: VS Code has a vast ecosystem of extensions and plugins that can be installed to customize the editor according to specific needs. Technical writers can find extensions for spell-checking, word count, table formatting, version control integration, and more to enhance their productivity.
- Integration with Git: Technical writers often collaborate with developers and use version control systems like Git to manage document revisions. VS Code has built-in Git integration, allowing writers to manage their documentation repositories, track changes, and collaborate seamlessly with developers.
- Cross-platform compatibility: VS Code is available for Windows, macOS, and Linux operating systems, making it a versatile choice for technical writers working on different platforms.
- Snippets: Another useful feature for writers in VSC is Snippets. Snippets are pieces of code authored and saved as templates for quick use. Writers can create snippets for codes used repeatedly for creating tables, inserting images and videos, and so on.
Collaboration
Another major advantage of using VS Code is the ease and flexibility it offers to collaborate with development teams. With most traditional WYSIWYG editors, which come with limited licenses, reviews become challenging. Technical Writers mostly generate PDFs or Word Documents and share them with the Product Teams or Developers to review the document for technical or functional accuracy. Comments are entered in the PDFs; Technical Writers address these comments on their systems and generate PDFs again for the next iteration.
With VS Code, this problem is almost eliminated since Developers already use the tool and can be given access to the files themselves; they can review documents directly from the writer’s repo. There is no question of generating PDFs and going back and forth multiple times just to close the review cycle. The time and effort thus saved is enormous, considering review cycles take more time than the authoring itself.
Empathising with the Developer Community
As an API-centric company, it is absolutely critical that we writers understand and empathise with the Developer community who consume our content day in, day out. A major chunk of our documentation is about APIs, and it helps immensely if we can understand the nuances of coding if we are to tailor our content for the Developer community. It has also sensitised us towards the issues faced by developers and how we can help them in mitigating them.
Conclusion
While WYSIWYG Editors have their own fan base, Markdown Editors, such as VS Code, are increasingly gaining popularity. It is a rare combination of simplicity and complexity going hand-in-hand and a preferred choice for writers who have a keen interest in coding. The choice ultimately depends on many factors such as the content complexity, variety of use cases, number of tech writers, level of customization needed and how much the organization is ready to invest in deciding the best writing tool for the Tech Writers. While VS Code is a versatile authoring and publishing tool, it also comes with its set of challenges. Evaluate all the factors before zeroing in on the best one that meets your requirements.
