What is Visual Studio Code (VSCode)? Explaining the Benefits, Methods, and Examples of Creating and Editing AsciiDoc Documents!

1. What is Visual Studio Code (VSCode)?

Visual Studio Code (Visual Studio Code) is a free source code editor developed and provided by Microsoft, as the name suggests. Commonly abbreviated as "VSCode," it is used by many developers around the world.
Its main use is programming, but due to its high customizability and rich features, it is also utilized in a wide range of scenarios such as technical documentation and manual creation.
Main uses:
• Programming
• Source code debugging
• Version control using Git
• Remote development

1-1. Main Features of VSCode

The reason VSCode is supported by many developers lies in its excellent features.
• Rich Extensions: The marketplace offers numerous extensions (plugins), allowing you to add necessary functions and customize it to your liking. Support for AsciiDoc is also realized through these extensions.
• Cross-Platform Support: It supports major operating systems such as Windows, macOS, and Linux, enabling consistent use across any environment.
• Git Integration: It integrates the version control system Git by default, allowing intuitive version control through GUI operations.
• Cloud Integration: Not only for local development, but with extensions, smooth integration with cloud environments is possible, enabling seamless work within a single editor.

 

2. Advantages of Creating and Editing AsciiDoc Documents with Visual Studio Code

Why is the combination of VSCode and AsciiDoc suitable for document creation?

2-1. What is AsciiDoc?

First, let me briefly introduce AsciiDoc. AsciiDoc is a lightweight markup language that can be written in plain text. It features a simple syntax that is easy for people to read and write, yet it has high flexibility that allows it to represent complex structured documents such as books and academic papers.

For the differences between AsciiDoc and Markdown, as well as more detailed usage methods, please also see this article.
[Related Link] What are AsciiDoc and Markdown? A thorough comparison of usage, benefits, and differences!

Until now, editors such as Atom (development ended in 2022) and AsciidocFX have been used for creating AsciiDoc, but currently, VSCode has become the mainstream choice.

2-2. Advantages of Handling AsciiDoc with VSCode

There are the following major advantages to creating and editing AsciiDoc documents with VSCode.

• Powerful extension with preview feature: By simply installing the "AsciiDoc" extension, you can display a real-time preview alongside the editor screen. This allows you to always check how the written content will be output while writing, making it very efficient.
• Easy integration with other tools like Git: VSCode has built-in standard integration with Git, so you can easily manage the change history of documents created with AsciiDoc. You can perform operations such as checking diffs, committing, and switching branches without leaving the editor.
• Lightweight and fast performance: Despite its high functionality, the editor itself runs very smoothly. You can focus on editing long documents without stress.
• Cross-platform support: Since it is OS-independent, teams with a mix of Windows and Mac users can create and manage documents in the same environment.

3. How to Create and Edit AsciiDoc Documents with Visual Studio Code

From here, we will explain the steps to actually create AsciiDoc documents using VSCode.

3-1. Environment Setup

First, let's check if your PC meets the system requirements for VSCode. In most cases, there is no problem if you have the latest OS. Please check the official website for details.
Official site: Visual Studio Code System Requirements

3-2. Download and Installation

Please download the installer suitable for your OS from the official website and follow the on-screen instructions to install it.
Official website: Visual Studio Code

3-3. Japanese Localization

Right after installation, the UI is displayed in English, so localizing it to Japanese makes it easier to use.
1. Click the Extensions icon (an icon with four squares) from the menu on the left.
2. Enter "Japanese Language Pack" in the search box.
3. Install the displayed extension.
4. When prompted to restart, restart to switch the UI to Japanese.

3-4. Add the "AsciiDoc" Extension

Next, install the extension for handling AsciiDoc.
1. As in the Japanese localization steps, enter "AsciiDoc" in the extension search box.
2. A popular extension provided by asciidoctor.asciidoctor-vscode will appear, so click Install.

3-5. Creating AsciiDoc Documents

1. Create a new file in VSCode and save it with the extension ".adoc". (e.g., document.adoc)
2. Write content in the file using AsciiDoc syntax.

3-6. Output (Preview and Export)

If you have installed the extension, you can display a real-time preview by clicking the preview icon (a document icon with a magnifying glass) at the top right of the editor.
Right-clicking on the preview screen will display a menu with options such as “Export as HTML” and “Export as PDF,” allowing you to easily convert and export to other formats.

4. Utilization Process: Learning from the Case of Yamaha Motor Co., Ltd.

What kind of actual effects does document management utilizing VSCode and AsciiDoc bring? Here, we introduce the case of Yamaha Motor Co., Ltd., which we supported. In this case, we built a document editing and management system combining AsciiDoc and the version control system GitHub.
* At that time, Atom was used as the editor, but now a similar environment is built with the more advanced VSCode.

• Issues:
◦ Consumer manuals were created with FrameMaker, while technical manuals were edited directly in HTML, resulting in a production workflow that depended heavily on individual expertise.
◦ Increased workload due to the use of different tools.
◦ Quality degradation caused by syntax errors.
◦ Inefficiency in version control.

• Measures:
◦ Built a document editing and management system using Asciidoc and GitHub.
◦ Replaced conventional dedicated tools with standard IT tools such as Git and various open-source software.

• Effects:
◦ The production process was standardized, achieving cost reductions of over 30%.
◦ The introduction of version control made it easier to maintain quality consistency and track change history.

In this way, a modern document production workflow centered on AsciiDoc greatly contributes to cost reduction and quality improvement.

[Details of the case study here] Achieved approximately 30% cost reduction by in-house manual production

5. Summary

This article explained how to create and edit AsciiDoc documents using Visual Studio Code (VSCode) and the benefits of doing so.
• VSCode is a free, high-performance editor with abundant extensions and Git integration
• Combining it with AsciiDoc enables efficient writing while viewing real-time previews
• Version control with Git improves document quality and consistency
• As demonstrated in the Yamaha Motor case, it is possible to improve the entire production workflow and achieve cost reductions

In-house production of manuals and technical documents, as well as streamlining the production process, are important challenges for many companies.
Human Science provides one-stop support from creating Japanese manuals to English and multilingual translations. Leveraging our extensive experience and expertise in handling numerous manuals since 1985, we contribute to solving our clients' challenges.
If you are struggling with manual construction and operation, please make use of Human Science's implementation support services. Through the utilization of GitHub and AsciiDoc, we support efficient and consistent document creation.
Please feel free to contact us.

GitHub/Markdown/Asciidoc Implementation Support Services
[Related Article] How to Convert Asciidoc｜HTML and PDF Output with Asciidoctor