What are the benefits of Markdown? An explanation of the reasons for its adoption and usage examples

1. Evolution of Document Creation

In recent years, many people seem to be using Markdown syntax to create internal documents, meeting minutes, and personal notes. I would like to first explain why Markdown has become in demand, the evolution of document creation, and the current challenges in document management.

1-1. Evolution of Document Creation

The introduction of Windows 95 led to the widespread use of PCs for business purposes around the world. Subsequently, the creation of business documents using PCs instead of word processors or typewriters became common in most companies. Various software for document creation, such as Lotus and Ichitaro, were tried, but eventually Microsoft Word became the standard for document creation software. As a result, many materials and documents began to be created in the .docx file format. The dolphin helper that appears when launching the software now feels nostalgic.

1-2. Introduction to Documentation: The Rise and Limits of Word

I would like to discuss the challenges I perceive regarding the use of Word from an engineer's perspective. As a programmer working in a startup company in web development, I have never been particularly fond of Word. I primarily used simple processing software like Notepad and WordPad, which came as extras with Windows. At that time, the specifications of personal computers were low, and I found it inconvenient that the memory required to launch Word was precious, and that documents saved in Word could only be read in Word. After all, we were using something as primitive as the vi text editor on a daily basis.

Eventually, managing documents centered around Word became an undeniable source of stress. Even if we wanted to implement version control, the binary format of Word became an obstacle, making it difficult to grasp differences. When team members had different versions of Word, the formatting would break and paragraphs would misalign. The file sizes kept getting larger, making even email attachments cumbersome. And the most frustrating part was the inability to manage the history of changes as neatly as code.

For example, if you try to update a functional specification by opening a Word file and just slightly rewriting some detailed bullet points, conflicts can arise if other members are editing the same document. In such cases, one of them will need to roll back the changes, and often the formatting information gets corrupted in the process. The time and effort spent on documentation work can become enormous, potentially jeopardizing the progress of the project.

Moreover, having to battle the question of "What has changed since the last time I opened this document?" every time a file is opened is a significant source of stress for developers. While it is clear at a glance when looking at the differences in a version control system for code (now Git, but back then we used a system called CVS), it is not the same for Word documents. It seems that the proliferation of files named things like "●●Project Document [Final Version].doc", "[Latest] ●●Project Document_01.doc", and "●●Project Document_fixed (PM Approved).doc" began around this time. This is something that many developers, not just myself, have felt similarly about.

Please take a look at this article.
[Column] From Word to Web Manual – Expanding Options with Jamstack | Jamstack Blog | Human Science Corporation

1-3. Difficulty of Processing

One of the disadvantages of using Word documents that many engineers face is the difficulty of processing them. There is no problem when opening and reading Word documents in Word. However, it became a significant issue when wanting to view them not with the human eye, but with a machine's eye. The demand to read and process the contents of those documents through a program, rather than through Word, has been increasing. For example, there is a need for a program to read amounts and payment dates from invoice files and reflect them in the system. In response to the need to mechanically process such uploaded documents, Word and Excel posed significant obstacles.

Due to the high demand for such needs, an open-source project called Apache POI was launched within the Apache project that was popular among Java developers at the time, and the HWPF library was developed to read Word documents. The Word 97-2003 format (.doc) is in binary format, and the HWPF (Horrible Word Processing Format) library provided by Apache POI carries the implication that it has to deal with a structure that is "horribly" complex, as the name suggests. Attempting to parse the formatting and object information embedded within the binary file requires an enormous amount of time and effort. Many developers at the time resonated with this naming.

In the world of programming, text-based change tracking is the norm. For example, Git is used for source code management, and by using diff, changes can be easily identified at a glance. Reviews are also easier, and it is clear who changed what and when. However, Word documents do not benefit from such advantages. Integrating them with automated testing or CI/CD pipelines is also a challenging task.

As a result, developers began to voice their opinions: "We want to manage documentation just like source code," "We're tired of binary files," "Isn't there a lighter format?" - These voices gradually grew louder, and the desire for change became stronger day by day.

1-4. The Emergence of Markdown Syntax

Many developers continued to create documents and materials in the simplest way possible, using .txt format, that is, text editors like Notepad. Many of you may have used editors like Hidemaru Editor or EmEditor, which can be downloaded from Windows Akiba.In my workplace, where there were many foreign staff, we were developing on Linux, and we were divided into emacs and vi factions. However, even though it was a text format, the writing styles varied from person to person. The symbols used to represent headings were not standardized either.

The Markdown syntax emerged after such a long history. Markdown is a lightweight markup language developed by John Gruber and Aaron Swartz in 2004, and its syntax is very simple. For headings, you use `#`, for lists `-`, and for links `[name](URL)`, making it intuitive and easy to remember. Since it is plain text rather than a complex binary format like Word documents, differences are clearly identifiable when managed with Git. There is also very little concern about formatting issues.

People in the team who are sensitive to such technologies quickly started using it. I also immediately realized its benefits and decided to try rewriting the specifications of my project in Markdown. As a result, the documentation progressed surprisingly smoothly. Without being troubled by unnecessary formatting, I could focus on the content of the text itself. "I never thought writing documents could be this effortless!" It was an eye-opening experience.

2. Benefits of Markdown

There are two main advantages of Markdown: "elimination of complexity" and "focus on writing." In the case of Word documents, many elements such as text, surrounding design, layout, and font styles are intricately intertwined. Of course, formatting these elements is important for business documents, but in the fields of software development and technical writing, the content is constantly changing and frequently updated. Maintaining detailed formatting in documents that are updated often is more labor-intensive than one might imagine.
Let's take a look at more specific advantages.

2-1. The simplicity of Markdown syntax and its low learning cost

Markdown uses a simple and intuitive syntax like the one below.

・Headings: # Heading 1, ## Heading 2, etc.
・Emphasis: **Bold**, *Italic*
・Lists: Represented with - or *
・Links: [Link Name](URL)

All of them are structured in a way that is easy to understand as natural sentences when read by humans, and also easy for machines to process. Therefore, it does not take much time to learn, and even if all team members transition at once, it is unlikely to cause significant confusion. If you post a cheat sheet summarizing the notation on the office wall, anyone can start writing immediately.

2-2. Reasons Why Markdown Works Well with Git

Markdown files are plain text, making them highly compatible with version control systems like Git. By comparing differences, it is clear which lines have been modified, and reviews are easy. Additionally, even when multiple people edit a document simultaneously, conflicts are easy to resolve.
The fact that it has become the official syntax used on Github is also a major factor in its widespread adoption.

2-3. Diverse Output Formats and Utilization Methods of Markdown

Markdown makes it very easy to convert to formats like HTML. By using static site generators such as VitePress and Astro, you can automatically generate documentation sites from Markdown files as the source.
Previously, it required a multi-step process to write documents in Word, convert them to PDF, and then upload them to a website. However, with Markdown, you can create a site in one go. When you want to update the site, you simply modify the Markdown file and rebuild it.
Such a convenient workflow was difficult to achieve with traditional methods. This is how we have become able to expand and disseminate various formats using Markdown files as the source.

If you would like to learn more about the key points of document solutions required by IT companies and a document creation environment that is highly compatible for developers, please download and view the materials below.

3. Case Study of Web Manuals Using Markdown

We would like to introduce a case where our company implemented Markdown.

●Ryobi Systems Co., Ltd.

<Background/Needs>
Originally, Ryobi Systems created manuals in Word and felt the need for web manuals, leading to their inquiry.
Having already implemented GitHub and created specifications in Markdown, they decided to convert the manual draft data from Word to Markdown. This allowed them to maintain the manuals in the same environment as when creating the specifications.

<Introduction Process>
Manual Writing in Markdown
We received the specification document for the manual and the development demo environment, and a technical writer from Human Science wrote the manual using Markdown syntax.
Nowadays, methods for converting Word files to Markdown using Markitdown are also gaining attention.

One Source Multi-Use Manual Data Production
We have built an output system using the open-source documentation tool GitBook to convert manuscript data created in Markdown into both HTML and PDF formats.

Development of Auxiliary Tools
After establishing a system for converting Markdown to HTML/PDF, we developed a GUI tool equipped with several auxiliary functions to facilitate easier maintenance of manuals.
For example, in the basic specifications of this system, it was necessary to manually modify the Markdown file to change the order of chapters and sections in the manual, but with the GUI tool, it has become possible to change the order through intuitive operations.

In this way, we can also respond to requests for manual creation using Markdown. Please see the following page for a case study from Ryobi Systems Co., Ltd.
Building an HTML/PDF Manual Creation System Using Markdown | Case Study | Human Science Co., Ltd.

Recently, we have also been working on the development of web manuals using Markdown and Jamstack.
Key Points for Selecting Document Solutions for IT Companies | Human Science

4. The Expansion of Markdown

Markdown continues to have various applications today. Communities and companies are at the forefront, continuously creating extensions and plugins, which provide greater flexibility in expression. Below, we introduce a part of this.

GitHub Flavored Markdown (GFM)
GFM, which allows for easy writing of tables, task lists, inline code blocks, and more, has already become the de facto standard on GitHub. It is rich in features specialized for software documentation and is utilized in various places, including READMEs and Wikis.

Extension of Formulas and Diagrams
Features that engineers desire are being continuously added, such as writing formulas using KaTeX or MathJax, and creating flowcharts and sequence diagrams with Mermaid or PlantUML. This has made it possible to complete research reports, academic documents, and system design materials in Markdown.

Integration with AI
Recently, there has been an active movement to automate proofreading and translation of Markdown documents using AI. By combining it with natural language processing technology, it has become possible to perform advanced bidirectional translation between Japanese and English, as well as summary generation, which will bring significant benefits to global companies and projects.

In this way, it can be said that Markdown has evolved from a mere text formatting syntax to a platform for efficiently sharing information. It presents greater possibilities for everyone involved in document creation, not just developers.

5. Finally

If you are currently struggling with document management using Word documents, why not consider transitioning to Markdown? Of course, depending on your corporate culture and the nature of your projects, a complete transition may be difficult at once. However, why not try starting from a small area?

Migrating to Markdown is not just a change in file format, but a means to enhance productivity and creativity. Managing documents like writing code, free from binary formats, provides significant benefits as a clear and simple environment for not only developers but also technical writers and stakeholders from other departments.

As a result of adopting Markdown in our team, the complaints of "updating documents is a hassle" have decreased, and a sense of reassurance has spread that "necessary information can be shared quickly" and "the latest information is always maintained," significantly reducing communication costs within the company.

In your daily operations, do you ever feel that "document creation is cumbersome and inefficient"? It might be time to adopt a new method. By introducing Markdown, you can reduce your workload and enable more flexible and speedy document management. Companies that have actually implemented it often express, "Why didn't we switch to Markdown sooner?"

Now is the time to review your team's document management and take the first step towards new possibilities. In the next blog, we will introduce the basic syntax of Markdown and how to express the elements required for web manuals.

6. For inquiries about manual creation and improvement, contact Human Science

Human Science provides one-stop support from the creation of Japanese manuals to English and multilingual translations. We have a long track record of handling numerous manuals since 1985. If you have any needs like the following, please feel free to contact us.

・I want to improve existing Japanese and English manuals to make them easier to understand.
・I am considering creating an English manual and would like to proceed step by step from the Japanese manual.
・I want to translate (multilingual translation) the Japanese manuals created in-house into English for use.

Feature 1: Extensive Manual Production Experience Focused on Large and Global Companies
Human Science has accumulated a wealth of manual production experience across various fields, primarily in the manufacturing and IT industries. We have worked with renowned companies such as "Docomo Technology Inc.", "Yahoo Inc.", and "Yamaha Corporation" as our clients.
Manual Production Case Studies | Human Science

Feature 2: From Research and Analysis by Experienced Consultants to Output
The creation of business manuals is handled by our experienced consultants at Human Science. Our skilled consultants will propose clearer and more effective manuals based on their extensive experience and the provided materials. Additionally, we can create manuals even from the stage where information is not yet organized. The assigned consultant will conduct interviews to create the optimal manual.
Manual Evaluation, Analysis, and Improvement Proposal Services | Human Science

Feature ③: Emphasis on not only manual creation but also support for implementation
Human Science focuses not only on manual creation but also on the important stage of "implementation." Even after the manual is created, we will support its implementation through regular updates and manual creation seminars. Through a variety of measures, we will assist in the effective use of manuals in the field.
Manual Creation Seminar | Human Science
Thank you for reading until the end.
I hope this blog provides helpful tips for creating easy-to-understand manuals.

If you would like to learn more about the key points of document solutions required by IT companies and a document creation environment that is highly compatible for developers, please download and view the materials below.