[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, with paper manuals, reprinting and redistribution are necessary, which carries the risk of old information continuing to coexist. Online manuals can be updated in real-time when new information or corrections are available. This allows readers to always access 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, I believe you have recognized the benefits of web-based manuals. Now, let me introduce the methods for web-based manuals. Until now, our company has developed HTML conversion tools to support manual production and web publication.

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

As an example, we will introduce a case where Ryobi Systems Co., Ltd., which provides software development for the medical field, worked on web-based manuals.
(For more details, please see here: Building a HTML/PDF manual creation system using Markdown)

 

Challenges Before Implementation

① The content explains the screens and functions, but does not take the user's perspective into account.
② We manage manuals that differ in some content for each customer, which has taken a significant amount of time for updating the common parts of the manuals.
③ The formatting of the manuals varied depending on the creator.
④ Manuals were created in Word, but web manuals will be necessary in the future.

The manuals focused solely on screen and function descriptions, leading to a situation where inquiries were constant due to their lack of clarity. Therefore, we decided to revise the structure and content to create user-oriented manuals and 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 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 is now possible to change the order through intuitive operations.

 

How about that? I hope you have a little bit of an image of how to create web manuals that are user-friendly and efficient for engineers.
Currently, our company is researching methods to build web manuals using more modern techniques that align with 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.

 

HTML generated by static site generators will have data embedded in it. This brings significant benefits to the initial display performance during page access. Representative static site generators include Gatsby and Eleventy, and by utilizing these tools, you can efficiently manage the content of manuals 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 the evolution beyond the traditional way of creating web manuals? The webification of manuals using Jamstack certainly offers a "fast," "easy," and "secure" environment, providing significant benefits for both readers and creators. But that's not all. There are also substantial 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 1: Extensive manual production experience, primarily with large and global companies
Human Science has accumulated a wealth of manual production experience across various fields, particularly 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.

Case Studies of Manual Production | 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 the implementation of the manual through regular updates and manual creation seminars. Through a variety of measures, we will support 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 hints for creating user-friendly manuals. In the next column, I will discuss "Creating a System for Manual Development to Reduce the Burden on Engineers." Stay tuned!