Effective practices for writing operation manuals

Introduction

When creating an application, operation manuals are extremely important. Especially in B2B cases, they are often provided as part of consulting for users, and the documents created follow the user's business flow. In this article, I will discuss how engineers can create documents on a per-function basis.

Things to Install

• VSCode: Code editor
  https://code.visualstudio.com/download

Extensions

• Live Server: Launches a local server to check HTML changes in real-time
  https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer
• Markdown PDF: Used to convert Markdown files to HTML
  https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf

Folder Structure

• Always make the folder structure the same tree structure as the screen transitions.
  This makes it easier to understand the flow of screen transitions.
• Divide folders by genre.
• Create a screenshots folder (image folder) in the same hierarchy.

Genre (project_management)
└── Display location (web)
    └── Images (screenshots)──project_list
    └── Project List (project_list)
        └── Project Detail (project_detail)

Example Content

Screen Operation Manual

# Screen Title

### Project Management Details

# Launch Path

### Main Menu (Project List) > Project Details

# Screen Layout

![Project Management Details](.\screenshots/project_detail.png)

1. **Save** - Saves the detailed information of the project. The entered content will be saved.
2. **Back** - Returns to the project list screen. Note that you can return even if you have made changes, so please be careful.
3. **Project Name** - Enter the project name. Please set a unique name.
4. **Description** - Enter a description for the project. While not a required field, it is good to describe it in detail.
5. **Add** - Adds one project member. They will be added at the very end.
6. **Delete** - Deletes a project member. No confirmation will appear, so please be careful.
7. **Status** - Sets the project status. You can select from Ongoing, Completed, On Hold, etc.
8. **Start Date** - Sets the project's start date.
9. **End Date** - Sets the project's end date.

# Operating Procedures

![Operating Procedure Description - Project Management Details](.\screenshots/project_detail.png)
## 1. **Add**
1. Click the "Add" button. A row will be added to the table below.
2. Enter the member name.
3. Select a role. (Optional)

## 2. **Save**
Saves the data within the screen when the "Save" button is pressed.  
Project name, status, and start date are required.

## 3. **Back**
Returns to the previous screen (Project List) when the "Back" button is pressed.

## **Delete**
Deletes the selected member in the table below when the "Delete" button is pressed.

# Notes

- Project names must be unique.
- Please set the status correctly.
- Be sure to set the start and end dates for the project.
- When the back button is pressed, you will return to the previous screen without any message even if there are unsaved changes.

# Related Information

## web
- [Project List](../../project_list/project_list.html)
  - [Project Details](../../project_list/project_list_details/project_detail.html)
- [Task Management](../../task_management/task_management.html)
- [Member Management](../../member_management/member_management.html)

## tablet
- [Project Implementation](../../../tablet/project_implementation/project_implementation.html)
  - [Project Progress](../../../tablet/project_implementation/project_progress/project_progress.html)
    - [Member Change](../../../tablet/project_implementation/project_progress/change_of_member/change_of_member.html)
  - [Project Start](../../../tablet/project_implementation/project_start/project_start.html)

Genre Manual

## [Back to Table of Contents](../../contents.html)

## Purpose

This project management system is designed so that companies can efficiently manage multiple projects and understand the progress of each project, resource allocation, and task completion status in real-time. Project managers clarify the roles and responsibilities of team members and support the project to proceed as scheduled. Additionally, the purpose is to increase project transparency and improve overall operational efficiency.

## Specifications

- **Project Name**: Each project is identified by a unique name. Project names should be concise and reflect the related content.
- **Start and End Dates**: Set a start date and an end date for each project, and manage the schedule based on these. Project progress is evaluated based on these dates.
- **Status Management**: Project progress is managed using statuses such as "Ongoing," "Completed," and "On Hold," allowing for a real-time understanding of the current project status.
- **Member Management**: Project members can be added or deleted, allowing for flexible responses to project needs. However, caution is required as no confirmation message is displayed during deletion.

## Notes

- **Importance of Saving Operations**: It is important to always perform a save operation because changes to project information may be lost if you navigate away from the screen without saving.
- **Status Management**: Do not neglect to update statuses to accurately reflect project progress. In particular, status changes from "Ongoing" to "Completed" are required at project milestones.
- **Date Management**: Please set the project start and end dates accurately, as they affect the team's work schedule. This prevents delays and misunderstandings.

## Related Information

### web
- [Project List](web/project_list/project_list.html)
  - [Project Details](web/project_list/project_list_details/project_detail.html)
- [Task Management](web/task_management/task_management.html)
- [Member Management](web/member_management/member_management.html)

### tablet
- [Project Implementation](tablet/project_implementation/project_implementation.html)
  - [Project Progress](tablet/project_implementation/project_progress/project_progress.html)
    - [Member Change](tablet/project_implementation/project_progress/change_of_member/change_of_member.html)
  - [Project Start](tablet/project_implementation/project_start/project_start.html)

Creation Steps

1. Creating the Markdown file
   The extension is .md. For the content, refer to other operation manuals or research online to check how to write it.

2. Converting the Markdown file to HTML
   Press Ctrl + Shift + P in VSCode and select Markdown PDF: Export HTML.

3. Previewing the HTML file
   Since an HTML file is created in the same directory as the Markdown file, open it.

4. Previewing with Live Server
   Click the Go Live button at the bottom right of VSCode to start the local server; changes to the HTML file will be reflected in real-time.

Workflow

1. Creating the Markdown file
2. Converting to an HTML file and previewing

Repeat these steps and proceed with creation while checking the content. Finally, once completed, commit and save both the Markdown and HTML files.

Releasing and Applying to the Production Environment

When reflecting HTML files in the production environment, set them up so they cannot be viewed without authentication as a security measure. Specifically, a common method is to place the document folder on the server and protect it by setting up an appropriate authentication mechanism.

Summary

Operation manuals can serve not only as a guide for users but also as design documents. Instead of tools like Excel or Word, where version tracking (diff management) is difficult, using Markdown allows engineers to create documents efficiently while enjoying the process.