[Column] From Word to Web Manuals – Expanding Options with Jamstack

1. Benefits of Web-based Manuals

What are the benefits of publishing manuals on the web in the first place? Below, I have summarized seven benefits from the perspectives of both the "reader" and the "creator".

Benefits for the Reader

1. Ease of Access:

Manuals shared in traditional formats like Word/PDF often led to concerns about file storage locations. Especially with the rise of remote work, companies that previously managed manuals on paper have been working on digitizing their manuals, resulting in cases where we received inquiries about poor access to these manuals.

On the other hand, manuals published on the web are accessible anytime from smartphones or PCs. Being able to obtain necessary information instantly without being tied to a specific location or time is extremely helpful for dealing with sudden troubles or clarifying uncertainties. However, it is necessary to set access rights and mitigate security risks.

2. Always up-to-date information:

Many manuals created by IT companies are frequently updated. In such cases, paper manuals require reprinting and redistribution, which carries the risk of outdated information continuing to coexist. Web-based manuals can be updated in real time when new information or corrections occur. Readers can always obtain accurate and up-to-date information, reducing the risk of incorrect operations or misunderstandings.

3. Use of Search Function:

In printed manuals, you need to rely on the table of contents and index to find information. However, in web manuals, you can simply enter keywords into the search bar to instantly display relevant information.

4. Embedding Links and Videos:

Documents on the web can easily embed hyperlinks to related pages and external resources. This allows readers to smoothly transition to relevant information. Additionally, by embedding videos that demonstrate actual operations or product demonstrations, understanding can be deepened more intuitively than with text-only explanations.

Benefits for the Creator

5. Maintainability:

Web manuals can be updated or added to quickly using a Content Management System (CMS). This allows for rapid response to product updates and the addition of new features.

6. Collection of Feedback:

By incorporating comment sections and survey forms into web manuals, you can receive feedback and questions directly from readers. This allows for a quick understanding of the manual's shortcomings and areas for improvement, making it possible to update the content to better meet user needs.

7. Version Control:

Web manuals can be integrated with version control tools like Git, allowing for detailed tracking of the manual's update history. This makes it clear when, who, and which parts were updated, and it is also easy to revert to previous versions if necessary.

From the above points, we believe you have recognized the benefits of converting manuals to web format. Now, we will introduce the actual method for web-based manuals. Up until now, our company has developed HTML conversion tools to support both manual creation and web publication.

2. Benefits and Methods of Publishing Manuals on the Web: Case Study of a Software Development Company

As an example, we introduce a case where Ryobi Systems Co., Ltd., which provides medical software development, worked on web-enabling their manuals.
(For more details, please see Building an HTML/PDF Manual Creation System Using Markdown)

Challenges Before Implementation

1. The content consisted of explanations about screens and functions, and did not take the user's perspective into account.
2. Manuals with some differing content were managed for each customer, causing a significant amount of time to be spent updating the common parts of the manuals.
3. The format of the manuals varied depending on the creator.
4. Manuals were created in Word, but Web manuals are needed going forward.

The manuals were focused solely on explaining screens and functions, making them difficult to understand and resulting in constant inquiries. Therefore, we reviewed the structure and content to create user-oriented manuals and decided to change the format to PDF/HTML.

Implementation Process

1. 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.

② 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.

- HTML Manual

・PDF Manual

③ Development of Auxiliary Tools

After establishing the system for converting Markdown to HTML/PDF, we developed a GUI tool equipped with several auxiliary functions to make manual maintenance easier. For example, in the basic specifications of this system, changing the order of chapters and sections in the manual required manually editing the Markdown files, but with the GUI tool, the order can be changed through intuitive operations.

How is it? I hope you were able to get a brief image of a web manual creation method that is compatible with engineers and efficient.
Currently, our company is researching methods to build web manuals using more modern approaches suited to the times. We will also introduce those methods.

3. Options for Web-based Manuals Using Jamstack

Jamstack started as an acronym for JavaScript, APIs, and Markup. It has since evolved and is not limited to the technologies represented by these initials. Some representative methods include the following.

1. Static Site Generator

A static site generator is a tool that generates a completely static HTML website based on raw data and templates. In other words, it is a concept that returns to the origins of website creation, where pages that were previously displayed dynamically using a content management system (CMS) are generated as HTML in advance and then displayed. It has gained attention as one of the development methodologies known as Jamstack.

The HTML generated by static site generators contains embedded data. This provides a significant advantage in improving the initial display performance when accessing pages. Representative static site generators include Gatsby and Eleventy, and by utilizing these tools, you can efficiently manage manual content and generate fast web pages.

(If you want to know more about static site generators, please see this. What is a static site generator)

2. Headless CMS

By using a headless CMS, you can easily create and manage the content of manuals. Our company utilizes Storyblok to flexibly update and edit the content of manuals.

・Storyblok Editing Screen

3. CDN (Content Delivery Network)

A CDN refers to a distributed service that delivers web content quickly and efficiently. Many servers are located in different regions around the world, providing content from the server closest to the user, significantly speeding up the loading time of web pages. In the Jamstack approach, CDNs play a central role in the delivery of static content.

By utilizing a CDN, it becomes possible to quickly deliver static HTML generated by static site generators and content obtained from headless CMS to global users. This allows users to access content quickly from anywhere, providing significant benefits for manual operations.

Have you felt how this method has further evolved from the traditional way of creating web manuals? The web conversion of manuals using Jamstack certainly provides a "fast," "simple," and "secure" environment, offering great benefits both for readers and creators. But that's not all. There are also significant advantages for administrators.

4. Manual Document Management with GitHub

GitHub is useful not only for source code but also for document management. This is a method utilized by Ryobi Systems Co., Ltd., which we introduced earlier. General CMSs like WordPress have article data in a database, but many static site generators prepare article data as text files such as Markdown files and store them in a Git repository.

With this method, you can obtain data simply by reading the necessary files during the build process, and the file history is also managed with Git. Even if a problem occurs, there is the advantage of being able to easily revert back since it is managed with Git.

For example, creating or updating manuals may involve multiple people. However, when several people work simultaneously, issues such as conflicting changes and the integration of incorrect modifications can arise. Additionally, tracking change history and reverting to specific versions can also be challenging.

By using Git, you can solve these challenges. Even when multiple people are working simultaneously, each person can make changes in their local repository and integrate those changes. Additionally, the change history is saved as commits, making the purpose and content of the changes clear. It is also easy to revert to a specific version and to undo incorrect changes.

Furthermore, by using branches in Git, you can work on specific modifications without affecting other tasks. Once the modifications are complete, you perform a merge to integrate the changes. This makes version control and tracking of changes in manuals easier.

By using Git, it becomes possible to manage versions of manuals, track changes, and improve collaboration and teamwork. In environments where engineers are involved in manual creation, Git will be a significant aid in enhancing maintainability.

5. With Human Science, we can consistently handle everything from manual creation to web development using modern front-end technologies.

How was it? This time, we introduced how to create a web manual. Producing manuals using modern methods will bring significant benefits not only to the readers but also to the administrators and creators.

If you would like to know more about the content of this column, please feel free to contact us. Human Science has a proven track record of creating numerous manuals since 1985. We are truly a team of professionals in the creation of business manuals. If you have any concerns regarding the creation of business manuals, please do not hesitate to consult us.

Feature ①: Extensive Manual Production Experience Mainly for Large and Global Companies
Human Science has accumulated extensive experience in manual production across a wide range of fields, mainly in the manufacturing and IT industries. We have served prestigious companies such as DOCOMO Technology, Inc., Yahoo Japan Corporation, and Yamaha Corporation as our clients.

Case Studies of Manual Production | Human Science

Feature ②: From Research and Analysis to Output by Experienced Consultants
The creation of business manuals is handled by Human Science's proud, experienced consultants. Skilled consultants propose clearer and more effective manuals based on their extensive experience and the materials provided. Additionally, it is possible to create manuals even from stages where information is not yet organized. The assigned consultant will conduct hearings and create the most suitable manual.

Manual Evaluation, Analysis, and Improvement Proposal Services | Human Science

Feature ③: Emphasis Not Only on Manual Creation but Also on Support for Adoption
Human Science focuses not only on creating manuals but also on the important stage of “adoption.” Even after manual creation, we support the adoption of manuals through regular updates and manual creation seminars. Through a variety of measures, we assist in the effective utilization of manuals in the field.

Manual Creation Seminar | Human Science

Thank you for reading until the end. I hope this blog provides you with some hints for creating easy-to-understand manuals. In the next column, we will cover "Creating a Manual Production System to Reduce the Burden on Engineers." Please look forward to it!