[Cost reduction of over 30%] Centralized management of PDF and HTML manuals data across departments using AsciiDoc and GitHub

Yamaha Corporation Group Overview

・Established: October 1897

・Capital：28.534 billion yen

Number of Employees：

　Linked 20,175 people

Business Activities：

　Musical Instruments Business, Audio Equipment Business, Parts and Devices Business

 Services Utilized

- Manual Creation

・Translation

・Building a document editing and management system using Asciidoc and GitHub

Implemented Manual Creation Flow

We have replaced the systems and tools used in the standard document production workflow with various open-source software (ATOM/RedPen) and tools familiar in the IT field, such as GitHub and SourceTree.

Demo videos for each process

1. This is the procedure for editing AsciiDoc with the text editor ATOM and managing data on GitHub.

2. This is the procedure for outputting HTML and PDF using Asciidoctor-PDF from AsciiDoc.

3. This is the procedure for converting AsciiDoc to XML and translating it using Trados.

* What is AsciiDoc?

It is one of the lightweight markup languages. You can write it in a text editor and convert it to file formats such as HTML, PDF, and EPUB.

*What is GitHub?

This is a version control tool used in software development. It is utilized not only for source code management but also as a document management and sharing tool for specifications and other documents. In manual creation, it allows for change history recording and simultaneous work by multiple users. It is available from $25/month for 5 users.

Background

The Manual Production Group of the Development Division of the Acoustic Business Headquarters produces manuals for network products such as routers, switches, and wireless LAN access points.

 

Each product has two types of manuals, one for consumers and one for engineers, each consisting of 300 pages. These are written by development engineers and compiled and released by the manual production group. The consumer manual is edited in FrameMaker and converted to PDF, while the engineer manual is edited directly in HTML.

 

[Background 1] We want to eliminate the issues caused by direct HTML writing without compromising on appearance.

The background for this improvement is that there have been requests and challenges arising from traditional production methods, such as those mentioned above, and issues related to direct HTML coding.

• I want to reduce man-hours.
• ・I want to eliminate quality degradation caused by grammatical errors.
• ・I want to eliminate version control in areas unrelated to the text, such as changes in indentation and tags.
• I want to convert not only HTML but also to formats like PDF.

The HTML manual before this initiative looked like the following page.

Goal 1: Adopt Asciidoc (lightweight markup language) and create HTML manuals

In advancing this initiative, we have set our first goal as "To adopt Asciidoc (a lightweight markup language) and produce HTML manuals."

We implemented the following two specific measures.

• Adopt Asciidoc suitable for technical documentation and complete HTML manuals that actively incorporate tables and other elements.
• ・Enhance the appearance of layouts using CSS and JavaScript.
• As a result of implementing these, we were able to create a page like the following.

[Background ②] We want to solve the challenges of manual production using conventional DTP tools.

Another background was the desire to solve the challenges faced in manual production using traditional DTP tools. The challenges were unique to the internal processes of the client ordering such tasks.

• ・Typically, since it is produced externally, it is challenging for our in-house members to master complex DTP tools.
• Whenever simple additional modifications occur, extra costs for external DTP work and acceptance will be required.
• Since DTP tools and paid fonts incur licensing fees, it is necessary to provide sufficient production environments on the PCs of in-house employees.
• It is necessary to standardize the production environment of PCs, such as the version of DTP tools.
• ・Additional work is required to adjust the layout of DTP data, which is based on paper manuals, for HTML manuals.
• Producing both PDF and HTML manuals for paper manuals usually incurs separate costs.

[Goal 2] Build a new manual production system aimed at efficiency and cost reduction

Therefore, the second goal is to establish a new manual production system aimed at improving efficiency and reducing costs.

We have also implemented the following two specific measures.

• Adopt a lightweight markup language (Asciidoc) designed for easy input with simple grammar, without using standard DTP tools or website creation tools.
• Switch from conventional production methods (separate PDF/HTML) to one-source multi-use (automatic simultaneous generation of PDF/HTML manuals) to achieve cost reduction.

The goal of implementing these is to reduce the usual production costs by approximately 30% or more.

Implementation Process

After a period of consideration and proposal, we started the project in January 2018 as a trial with the API reference manual for engineers.

[Process 1] Adoption of Lightweight Markup Language (Asciidoc)

First of all, we removed traditional DTP tools from the process. This was due to the difficulty in preparing the work environment and the high barriers to mastering them. Instead, we decided to use a simple text editor and adopted a lightweight markup language (Asciidoc) with easy input and concise grammar to create manuscript data.

[Process ②] Manual data production using one source, multiple uses

We have established a system that automatically generates HTML/PDF data simultaneously from manuscript data written in a lightweight markup language using a data conversion converter (Asciidoctor, Asciidoctor-PDF).

[Process ②] Enhancement of Layout Design

As mentioned in the first issue, we did not want to compromise on layout design (appearance). Therefore, to enhance the layout design of the generated HTML and PDF, we decided to create a template in advance for the HTML using CSS and for the PDF using a style file (YAML format) to customize the formatting, which would be automatically applied using a batch file.

Results from Adopting a Lightweight Markup Language

Achieve cost reductions of over 30%

Through the effects of process improvements from this initiative, we have achieved cost reductions in several steps of the traditional production process.

The biggest advantage is that DTP editing work has become completely unnecessary. We have reduced the time and cost associated with using DTP tools to zero, allowing us to complete the work solely with a text editor and lightweight markup language.

We were able to reduce costs by approximately 30% throughout the entire process.

By building an advanced document creation system with one source, multi-use, we have achieved efficiency in the production process and cost reduction.

This is the first time we are undertaking this initiative, so there were initial implementation costs involved.

I believe that by using this system in the future, it will be possible to recover the initial implementation costs.

Evaluation of Human Science Co., Ltd.

A company that can provide consultation not only for production but also for tools and systems

Originally, we had a relationship through translation and manuals, but we recognize that the person in charge of the actual production of the manuals is knowledgeable and skilled in programming and systems, and is a partner with whom we can exchange information on the latest technologies, not just in actual production.

 

Even when discussing AsciiDoc and GitHub, we were able to smoothly solidify the requirements design, achieving the implementation of tools that are still not common in the manual industry.

 

Since we are at the stage after the trial, we will now verify the initial goal of reducing the engineering workload.

In the future, we plan to implement access analysis using Google Tag Manager and Google Analytics, as well as app integration. We look forward to support for expansion.

Free Download of OSS System

We have published a simplified version of the OSS system for this case on GitHub.

A system equipped with template, HTML conversion, and PDF conversion functions, allowing you to utilize templates to create manuscripts and generate HTML and PDF.

It is available for free download to anyone with a GitHub account, as it is open source.

https://github.com/human-science/adpy/blob/master/README-ja.adoc

You can check the samples (HTML, PDF) generated using the OSS system from the adoc, html, and pdf folders.

* PDFs can be viewed in the browsers below. Please download the HTML to view it.

https://github.com/human-science/adpy/blob/master/pdf/en/toc_en.pdf

Related Services

Manual creation using GitHub and others

Creation of Manuals and User Guides

Localization