{"id":8659,"date":"2023-08-22T16:27:01","date_gmt":"2023-08-22T10:57:01","guid":{"rendered":"https:\/\/razorpay.com\/learn\/?p=8659"},"modified":"2023-08-22T16:27:01","modified_gmt":"2023-08-22T10:57:01","slug":"vs-code-as-a-documentation-tool","status":"publish","type":"post","link":"https:\/\/razorpay.com\/learn\/vs-code-as-a-documentation-tool\/","title":{"rendered":"VS Code as a Documentation Tool"},"content":{"rendered":"<p><span style=\"font-weight: 400;\">VS Code as a Documentation tool? Sounds interesting? Unusual even\u2026<\/span><\/p>\n<p><span style=\"font-weight: 400;\">As a technical writer myself, having spent over a decade in this field &#8211; I found it awkward when I first learnt from a colleague that <a href=\"https:\/\/razorpay.com\/docs\/#home-payments\">Razorpay Documentation<\/a> 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, \u201cDid I make the right decision? How did I miss asking about the authoring tool we use during my interviews?\u201d<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">The \u2018Docs-as-code\u2019 approach<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">Before we talk about <a href=\"https:\/\/code.visualstudio.com\/\" target=\"_blank\" rel=\"noopener\">VS Code<\/a>, let us understand what \u2018Docs as Code\u2019 is.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Documentation as Code or more popularly known as \u2018Docs as Code\u2019, 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:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Issue Trackers such as <a href=\"https:\/\/www.atlassian.com\/software\/jira?&amp;aceid=&amp;adposition=&amp;adgroup=143485223644&amp;campaign=18442427757&amp;creative=666244286838&amp;device=c&amp;keyword=jira&amp;matchtype=e&amp;network=g&amp;placement=&amp;ds_kids=p73345677068&amp;ds_e=GOOGLE&amp;ds_eid=700000001558501&amp;ds_e1=GOOGLE&amp;gclid=Cj0KCQjwrfymBhCTARIsADXTabmaOh0jn9Ii_X5pKxMKTZgll9ctWTdev_OarWLHDW2dOnKzJDJbkAcaApwrEALw_wcB&amp;gclsrc=aw.ds\" target=\"_blank\" rel=\"noopener\">Jira<\/a>, <a href=\"https:\/\/asana.com\/?noredirect\" target=\"_blank\" rel=\"noopener\">Asana<\/a><\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Plain Text Markup such as VS Code<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Version Control such as <a href=\"https:\/\/www.perforce.com\/products\/helix-core\" target=\"_blank\" rel=\"noopener\">Helix<\/a>, <a href=\"https:\/\/github.com\/razorpay\" target=\"_blank\" rel=\"noopener\">GitHub<\/a><\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Code Reviews such as GitHub<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Automated Tests such as <a href=\"https:\/\/www.selenium.dev\/\" target=\"_blank\" rel=\"noopener\">Selenium<\/a>, <a href=\"https:\/\/www.postman.com\/\" target=\"_blank\" rel=\"noopener\">Postman<\/a><\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">VS Code as an Authoring Tool<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">It is comparable to most WYSIWYG editors in terms of the features offered:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Rich text editing<\/b><span style=\"font-weight: 400;\">: 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.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Markdown support<\/b><span style=\"font-weight: 400;\">: 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.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Extensions and plugins<\/b><span style=\"font-weight: 400;\">: 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.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Integration with Git<\/b><span style=\"font-weight: 400;\">: 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.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Cross-platform compatibility<\/b><span style=\"font-weight: 400;\">: VS Code is available for Windows, macOS, and Linux operating systems, making it a versatile choice for technical writers working on different platforms.<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><b>Snippets<\/b><span style=\"font-weight: 400;\">: 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.<\/span><\/li>\n<\/ul>\n<h3><span style=\"font-weight: 400;\"><img decoding=\"async\" class=\"alignnone size-full wp-image-8660\" src=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-18-at-3.48.06-PM.png\" alt=\"\" width=\"2282\" height=\"1302\" srcset=\"https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-18-at-3.48.06-PM.png 2282w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-18-at-3.48.06-PM-300x171.png 300w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-18-at-3.48.06-PM-1024x584.png 1024w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-18-at-3.48.06-PM-1536x876.png 1536w, https:\/\/d6xcmfyh68wv8.cloudfront.net\/learn-content\/uploads\/2023\/08\/Screenshot-2023-08-18-at-3.48.06-PM-2048x1168.png 2048w\" sizes=\"(max-width: 2282px) 100vw, 2282px\" \/>Collaboration<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">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\u2019s 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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Empathising with the Developer Community\u00a0<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n<h3><span style=\"font-weight: 400;\">Conclusion<\/span><\/h3>\n<p><span style=\"font-weight: 400;\">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.<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"<p>VS Code as a Documentation tool? Sounds interesting? Unusual even\u2026 As a technical writer myself, having spent over a decade in this field &#8211; 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<\/p>\n","protected":false},"author":151156541,"featured_media":8661,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3606],"tags":[3613],"class_list":{"0":"post-8659","1":"post","2":"type-post","3":"status-publish","4":"format-standard","5":"has-post-thumbnail","7":"category-tech-writing","8":"tag-technical-writing"},"_links":{"self":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts\/8659","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/users\/151156541"}],"replies":[{"embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/comments?post=8659"}],"version-history":[{"count":2,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts\/8659\/revisions"}],"predecessor-version":[{"id":8663,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/posts\/8659\/revisions\/8663"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/media\/8661"}],"wp:attachment":[{"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/media?parent=8659"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/categories?post=8659"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/learn.razorpay.in\/learn\/wp-json\/wp\/v2\/tags?post=8659"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}