【Column】From Word to Web Manual - 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:

In the past, manuals shared in Word/PDF format often caused problems with storage locations. Especially in today's world where remote work is becoming more common, companies that previously managed manuals in paper form have faced difficulties with accessing digital manuals.

 

On the other hand, manuals published on the web can be accessed anytime from smartphones or PCs. Being able to instantly retrieve necessary information without being bound by specific locations or times is extremely useful for dealing with sudden troubles and resolving uncertainties. However, setting access permissions and avoiding security risks are necessary.

 

2. Always Up-to-Date Information:

Many manuals created by IT companies require frequent updates. In such cases, with paper manuals, reprinting and redistribution are necessary, which poses a risk of outdated information remaining. Online manuals allow for real-time updates when new information or corrections are made. This reduces the risk of readers encountering incorrect operations or misunderstandings, as they always have access to accurate and up-to-date information.

 

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 related information.

 

4. Embedding Links and Videos:

You can easily embed hyperlinks to related pages and external resources in web documents. This allows readers to smoothly transition to related information. Additionally, embedding videos that demonstrate actual operations and product demonstrations can help deepen understanding intuitively, rather than just relying on text explanations.

 

"Benefits for Creators"

5. Maintainability:

Web manuals can quickly make changes or additions to content using a content management system (CMS). This allows for quick response to product updates and the addition of new features.

 

6. Collecting Feedback:

By incorporating comment sections and survey forms into web manuals, you can directly receive opinions and questions from readers. This allows you to quickly understand the shortcomings and areas for improvement in the manual, and update the content to better meet the needs of users.

 

7. Version Control:

Web manuals can be linked with version control tools such as Git, allowing for detailed tracking of manual update history. This makes it possible to clearly see when, who, and which parts were updated, and easily revert to previous versions if necessary.

 

From the above points, I hope you have felt the benefits of manual webization. Now, let us introduce the method of manual webization. Our company has developed an HTML conversion tool to support manual creation and web publication.

2. Benefits and Methods of Publishing Manuals on the Web: Case Studies from Software Development Companies

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

 

Challenges before implementation

①The content describes the screen and functions, but does not take into account the user's perspective.
②We were managing manuals with some different content for each customer, which took a lot of time to update the common parts of the manual.
③The format of the manual was different depending on the creator.
④We were creating manuals in Word, but now we need web manuals in the future.

The manual was focused solely on explaining the screen and functions, leading to confusion and constant inquiries. As a result, we have decided to review the structure and content to make it more user-friendly, and change the format to PDF/HTML.

 

Introduction Process

①Adoption of Markdown

At Ryobi Systems Co., Ltd., we have been using GitHub and Markdown to create specifications documents. By converting the manuscript data from Word to Markdown, we are able to maintain the manuals in the same environment as when creating the specifications, so we have decided to adopt Markdown for the manuals as well.

 

② Manual data creation for one-source multi-use

We have built an output system using the open source document creation tool GitBook to convert manuscript data created in Markdown to both HTML and PDF formats.

・HTML Manual

 

・PDF Manual

 

③ Development of auxiliary tools

After establishing a system for converting from Markdown to HTML/PDF, we have developed a GUI tool with several auxiliary functions to make manual maintenance easier. For example, in the basic specifications of this system, it was necessary to manually make changes to the Markdown file in order to change the order of chapters and sections in the manual. However, with the GUI tool, it is now possible to change the order intuitively.

 

How about it? I hope you have a little image of an efficient way to create web manuals that are compatible with engineers.
Currently, we are researching methods to build web manuals in a more modern way that is in line with the times. We will also introduce this method.

3. Options for Manual Webization using Jamstack

Jamstack started as an acronym for JavaScript, API, and Markup. However, it has evolved to encompass more than just these technologies. Some common approaches include:

 

1. Static Site Generator

A static site generator is a tool that generates completely static HTML websites based on raw data and templates. In other words, it is a concept that goes back to the origin of website creation, where pages that were previously displayed dynamically using content management systems (CMS) are first generated as HTML and then displayed as HTML. It has gained attention as one of the development methods called Jamstack.

 

The HTML generated by the static site generator contains embedded data, which greatly improves the initial performance of page access. Some popular static site generators include Gatsby and Eleventy, which can be used to efficiently manage manual content and generate fast web pages.

 

(If you would like to learn more about static site generators, please click here. What is a Static Site Generator?)

 

2. Headless CMS

By using a headless CMS, it is possible to easily create and manage manual content. Our company has introduced Storyblok to flexibly update and edit manual content.

 

・Storyblok Editing Screen

 

3. CDN（Content Delivery Network）

CDN stands for Content Delivery Network, which refers to a distributed service that delivers web content quickly and efficiently. By placing servers in various locations around the world and providing content from the server closest to the user, CDN greatly speeds up the loading time of web pages. In the Jamstack approach, CDN plays a central role in delivering static content.

 

By using CDN, it is 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 the content quickly from anywhere, providing significant benefits for manual operations.

 

Have you been able to feel the evolution from the traditional way of creating web manuals? Webization of manuals using Jamstack is indeed in a "fast", "easy", and "secure" environment, which brings great benefits to both readers and creators. But that's not all. There are also significant benefits for administrators.

4. Manual Document Management with GitHub

GitHub can be useful not only for source code, but also for document management. This is the method used by Ryobi Systems Co., Ltd., which was introduced earlier. While common CMS such as WordPress have article data in databases, many static file generators prepare article data as text files such as Markdown (notation) files and save them in Git repositories.

 

With this method, during the build process, you can retrieve the necessary files just by reading them, and the file history is also managed by Git. Even if any issues arise, there is the benefit of being able to easily revert back since it is managed by Git.

 

For example, creating and updating manuals may involve multiple people. However, when multiple people work simultaneously, there is a possibility of conflicts and problems such as incorrect changes being integrated. It is also difficult to track changes and revert to a specific version.

 

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

 

In addition, by using branches in Git, you can make modifications to specific parts without affecting other work. Once the modifications are complete, you can merge and integrate the changes. This makes it easier to manage versions and track changes in the manual.

 

By using Git, it is possible to manage versions of manuals, track changes, and improve teamwork and collaboration. In environments where engineers are involved in manual creation, Git will be particularly helpful in improving maintainability.

5. From manual creation to modern front-end web development, Human Science Co., Ltd. can handle everything consistently.

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

 

If you would like to know more about the contents of this column, please do not hesitate to contact our company. Human Science Co., Ltd. has a proven track record of creating numerous manuals since 1985. We are truly a group of professionals when it comes to creating business manuals. If you have any concerns about creating business manuals, please feel free to consult with us.

 

Features ①: Extensive track record of manual creation for large and global companies
Human Science has accumulated a wealth of experience in manual creation in various fields, mainly in the manufacturing and IT industries. We have worked with renowned companies such as DOCOMO Technology, Inc., Yahoo Japan Corporation, and Yamaha Corporation.

Manual Creation Case Study Introduction | Human Science Co., Ltd.

 

Feature ②: From Investigation and Analysis by Experienced Consultants to Output
The creation of operation manuals will be handled by the experienced consultants of Human Science. Skilled consultants will propose more understandable and effective manuals based on their extensive experience and provided materials. In addition, manual creation from the stage where information is not organized is also possible. The assigned consultant will conduct a hearing and create the most suitable manual.

Manual Evaluation, Analysis, and Improvement Proposal Service | Human Science Co., Ltd.

 

Feature 3: Not only manual creation, but also emphasis on establishment support
Human Science Co., Ltd. not only creates manuals, but also focuses on the important stage of "establishment". Even after manual creation, we support the establishment of manuals through regular updates and manual creation seminars. Through various measures, we support the effective use of manuals in the field.

Manual Creation Seminar | Human Science Co., Ltd.

 

Thank you for reading until the end. I hope this blog can be a helpful guide for creating easy-to-read manuals. In the next column, we will discuss "Creating a System for Reducing the Burden on Engineers in Manual Creation". Stay tuned!