Building a HTML/PDF manual creation system using Markdown

Ryobi Systems Co., Ltd. Overview

Established: December 1969

・Capital: 300 million yen

Number of Employees: Consolidated 1,556 (as of December 2019)

・Business Overview: Provision of information services for public, medical, and social security sectors as well as private enterprises, system construction, outsourcing business, software development, and more

 Services Utilized

- Manual Creation

・Construction of a HTML/PDF manual creation system using Markdown

Background

Ryobi Systems Co., Ltd. has expanded its business since its establishment, focusing on the fields of administration, medical care, and health and welfare, as well as education, transportation, and distribution, and has developed its own brand systems nationwide. It boasts a strong brand power and market share.
In relation to the release of one of its products, the "General Affairs Management System," we have been considering outsourcing the creation of manuals that have been produced in-house.

General Affairs Administration System

Challenges Before Implementation

I want to create user-centric manuals

The existing manuals had the following issues.

1. The content explains the screen and features, but does not take the user's perspective into account.

② We manage manuals with some content that differs for each customer, and updating the common parts of the manuals has taken a significant amount of time.

③ The format of the manual varied by the creator

④Although manuals were created in Word, a web manual will be necessary in the future.

The manual focused solely on screen and function descriptions, leading to a situation where inquiries were constant due to its lack of clarity.

Public Business Division Internal Information Services Department
General Affairs Office Group Mr. Kanazawa

Therefore, we have decided to review the structure and content to create a user-oriented manual and change the format to PDF/HTML.

We received an inquiry on the Human Science website in April 2019.

Reasons for Choosing Human Science

Technical skills for creating manuals in Markdown

At Ryobi Systems, GitHub has been introduced, and specifications were created in Markdown. We were considering revising the manuals in-house using Markdown after they were created by the production company.

"In considering outsourcing, we approached three or four companies, but whenever we inquired about production in Markdown, the response was always that they could do it in Word. The only company that could produce in Markdown was Human Science."
(Kanazawa and Manabe, Internal Information Services Department, Public Business Division)

* What is Markdown
Markdown is a lightweight markup language that has features such as the ability to create highly readable documents with a simple syntax and easy editing in text editors. It is widely used in the IT industry, especially among engineers, and has been adopted by prominent web services like GitHub and Qiita.

Implementation Process

Adoption of Markdown

At Ryobi Systems, we have been using GitHub for some time and creating specifications in Markdown. By converting the manuscript data of the manuals from Word to Markdown, we can maintain the manuals in the same environment as when creating the specifications, so we decided to adopt Markdown for the manuals as well.

In addition, by adopting Markdown using GitHub, it is easy to revise manuals for each customer simply by merging the common parts of the manuals. Furthermore, there is the advantage of being able to achieve design consistency, such as font size and color, through simple procedures.

Manual data production with one source, multiple uses

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.

HTML Manual

PDF Manual

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 now, with the GUI tool, it is possible to change the order through intuitive operations.

Evaluation of Human Science Co., Ltd.

I am satisfied with the user-oriented manual that was completed on my behalf.

Developers have their original development tasks.

When creating manuals, I wanted to completely outsource the work to an external production company.

By sharing specifications, development demo environments, etc., we were able to create user-oriented manuals without investing our own man-hours.

Public Business Division Internal Information Services Department
General Affairs Office Group Mr. Manabe

As a company that can create Markdown manuals, there was no choice but to select Human Science.

Not only does it support Markdown, but I am also satisfied with the manual that has been completed without the need for us to invest additional effort in verification, as it reflects our intentions.