[Column] Creating a System for Manual Development to Reduce the Burden on Engineers

1. Why do engineers struggle with manual creation?

The work of engineers involves not only coding but also creating documentation to communicate their results to other team members and subsequent engineers, which means they are also engaged in manual creation. However, this manual creation requires a significant amount of time and effort, which can take away from the engineers' primary task of coding. Therefore, creating systems to alleviate the burden of manual creation has become very important for engineers.

 

So, why do engineers spend so much time and effort on manual creation? I will explain three challenges that engineers face during the creation process.

 

Effort for Visualizing Information

It takes a significant amount of time and effort to rephrase and document what is expressed in code. Additionally, when inserting diagrams or screenshots for parts that cannot be conveyed through text alone, it takes even more time to create and edit these materials.

 

The Necessity of Specialized Knowledge

Engineers possess technical expertise, but when communicating the details of the systems or software they have developed to others who do not have that technical knowledge, they need to start by explaining that expertise in the manual. However, explaining that specialized knowledge in a way that others can understand requires different manual writing skills than those used for creating specifications, which increases the burden on engineers.

 

Update Load

Technology is evolving rapidly, and manuals need to be updated frequently to keep up with it. As a result, manuals must be updated as soon as they are created, further taking away engineers' time.

 

To solve these issues, it is necessary to review the manual creation process itself and reduce the burden on engineers.

2. Methods to Reduce the Burden of Manual Creation

So, what kind of systems can be created to reduce the burden of manual creation for engineers? As a manual professional with experience in creating manuals for IT companies, I recommend the following approaches.

 

Manual template creation

The most immediate solution is to create templates. By creating a manual template and defining the basic structure and format, engineers can easily add and modify content based on the template instead of starting from scratch, significantly reducing the effort required for creation.

 

Introduction of Tools

By implementing documentation tools, you can significantly improve the efficiency of manual creation. For example, by using lightweight markup languages such as Markdown or reStructuredText to create manuals, you can easily create documents and publish them on the web. Furthermore, since Markdown is easy to manage alongside code repositories, version control for manuals can also be done easily.

 

Utilization of Collaboration Platforms

Let's build an environment where multiple engineers can collaboratively edit manuals using an online collaboration platform. This will help avoid concentrating the manual creation work on a single engineer, thereby improving efficiency.

 

By implementing these systems, it becomes possible to create manuals more efficiently and reduce the burden of manual creation on engineers.

3. Compatibility of Manual Creation and Modern Front-End

The recommended load reduction mechanism can be easily realized by using modern front-end technologies. Modern front-end refers to the latest technologies that allow a site to be displayed quickly and stably, even when the server is under heavy load. This can be achieved by freely combining various systems. From here, I will discuss how to use this modern front-end to create manuals.

 

Introduction of Static Site Generators

We use Static Site Generators (SSG) to generate content for manuals. SSG automatically creates static HTML pages based on content such as text, images, and diagrams. Notable SSGs include Gatsby, Next.js, and Hugo.

 

Generate manuals from code comments

Add appropriate comments to the codebase and automatically convert these comments into documentation pages using SSG. This allows you to maintain documentation in sync with code changes.

 

API Integration with Data Sources

The manual may also include dynamic data and information from APIs. With a modern frontend approach, data can be retrieved through API integration and combined with static content to generate pages.

 

Utilization of CI/CD

Let's implement CI/CD (Continuous Integration/Continuous Delivery) tools to support the automatic generation and updating of manuals. This will automate the process of generating and publishing new versions of the manuals automatically when changes are detected in the code repository.

 

Creation of Automation Scripts

Create scripts for manual generation to minimize manual work. The scripts integrate with the codebase, retrieve necessary information, and serve the role of generating and deploying manuals.

 

By using these modern front-end technologies, the automation and updating of manuals become easier, reducing the burden on engineers!

 

4. Improving the Manual Creation Process - Example of APRESIA Systems' Initiatives

I have talked about ways to reduce the burden of manual creation for engineers. What do you think? Few people might have imagined that the challenges of manuals could be resolved with modern front-end technologies. However, the implementation can be complex, and there may be those who cannot secure enough time to carry out such extensive tasks. In such cases, outsourcing may be one option to consider. I would like to introduce a case study from APRESIA Systems, where Human Science improved the manual creation process so that engineers could focus on their core tasks.

 

APRESIA Systems provides added value to information system infrastructure as a specialized company in information systems, supporting the development of our lives and society through social infrastructure solutions, security solutions, and information system operation management solutions.
Human Science has been assisting APRESIA Systems with the manual creation for their Ethernet switch "ApresiaNP Series" since 2015.

 

At APRESIA Systems, we were producing product manuals in-house, but we felt challenged by balancing product development and manual creation. Therefore, we reviewed the manual production process and outsourced the manual creation to external specialists, allowing us to focus on product development.

 

The success factors of this improvement are the following three points.

 

1. By outsourcing to external vendors with expertise in manual production, we have been able to create high-quality manuals.
2. By outsourcing the manual production tasks, we have been able to concentrate internal resources on product development.
3. Through collaboration with external vendors, we have reviewed the manual production process and aimed for greater efficiency.

By making it a 'simple navigation', we can clarify the hierarchical structure of information, allowing users to quickly access the information they need.

 

Through this process, we were able to successfully improve the manual creation. Please see below for more details.

Manual Production Case Studies | APRESIA Systems Inc. | Human Science

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

This time, we introduced a system for creating manuals that allows engineers to focus on their core tasks. By reducing the burden of manual creation, it can also lead to increased productivity for engineers!

 

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 operational manuals. If you have any concerns regarding the creation of operational 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 easy-to-read manuals. Look forward to the next column!