🦁

良いと思った操作説明書の書き方

2024/08/09に公開

Markdown

ドキュメント

tech

はじめに

アプリケーションを作成する際、操作説明書は非常に重要です。特にB2Bのケースでは、ユーザーに対するコンサルティングの一環として提供されることが多く、作成されるドキュメントはユーザーの業務フローに沿ったものになります。本記事では、エンジニアが機能単位でドキュメントを作成する方法について考察します。

インストールするもの

VSCode: コードエディタ
https://code.visualstudio.com/download

拡張機能

Live Server: ローカルサーバーを立ち上げ、HTMLの変更をリアルタイムで確認する
https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer
Markdown PDF: MarkdownファイルをHTMLに変換するために使用する
https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf

フォルダ構成

フォルダ構成は必ず画面遷移と同じツリー構造にします。
これにより、画面遷移の流れが把握しやすくなります。
ジャンルごとにフォルダを分けます。
screenshots フォルダ（画像フォルダ）は、同じ階層に作成します。

ジャンル(project_management)
└── 表示場所(web)
    └── 画像(screenshots)──project_list
    └── プロジェクト一覧(project_list)
        └── プロジェクト詳細(project_detail)

記載内容例

画面操作説明書

# 画面タイトル

### プロジェクト管理詳細

# 起動経路

### メインメニュー(プロジェクト一覧) > プロジェクト詳細

# 画面構成

![プロジェクト管理詳細](.\screenshots/project_detail.png)

1. **保存** - プロジェクトの詳細情報を保存します。入力された内容が保存されます。
2. **戻る** - プロジェクト一覧画面に戻ります。変更していてもそのまま戻ることができますので注意してください。
3. **プロジェクト名** - プロジェクト名を入力します。ユニークな名前を設定してください。
4. **説明** - プロジェクトの説明を入力します。必須項目ではありませんが、詳細に記載すると良いです。
5. **追加** - プロジェクトメンバーを一人追加します。一番最後に追加されます。
6. **削除** - プロジェクトメンバーを削除します。確認が出ませんので注意してください。
7. **ステータス** - プロジェクトのステータスを設定します。進行中、完了、保留などから選択可能です。
8. **開始日** - プロジェクトの開始日を設定します。
9. **終了日** - プロジェクトの終了日を設定します。

# 操作手順

![操作手順の説明 プロジェクト管理詳細](.\screenshots/project_detail.png)
## 1. **追加する**
1. 「追加」ボタンをクリックします。下の表に一行追加されます。
2. メンバー名を入力します。
3. 役割を選択します。(任意)

## 2. **保存する**
「保存」ボタンを押したときに画面内のデータを保存します。  
プロジェクト名、ステータス、開始日は必須です。

## 3. **戻る**
「戻る」ボタンを押したときに前の画面(プロジェクト一覧)に戻ります。

## **削除する**
「削除する」ボタンを押したときに下の表で選択されているメンバーを削除します。

# 注意事項

- プロジェクト名はユニークである必要があります。
- ステータスを正しく設定してください。
- プロジェクトの開始日と終了日は必ず設定してください。
- 戻るボタンを押したときに未保存でもメッセージは出ずに前の画面に戻ります。

# 関連情報

## web
- [プロジェクト一覧](../../project_list/project_list.html)
  - [プロジェクト詳細](../../project_list/project_list_details/project_detail.html)
- [タスク管理](../../task_management/task_management.html)
- [メンバー管理](../../member_management/member_management.html)

## tablet
- [プロジェクト実施](../../../tablet/project_implementation/project_implementation.html)
  - [プロジェクト進捗](../../../tablet/project_implementation/project_progress/project_progress.html)
    - [メンバー変更](../../../tablet/project_implementation/project_progress/change_of_member/change_of_member.html)
  - [プロジェクト開始](../../../tablet/project_implementation/project_start/project_start.html)

ジャンルの説明書

## [目次に戻る](../../contents.html)

## 目的

このプロジェクト管理システムは、企業が複数のプロジェクトを効率的に管理し、各プロジェクトの進捗、リソース割り当て、タスクの完了状況をリアルタイムで把握できるように設計されています。プロジェクト管理者は、チームメンバーの役割と責任を明確にし、プロジェクトが予定通り進行するようサポートします。また、プロジェクトの透明性を高め、全体の業務効率を向上させることが目的です。

## 仕様

- **プロジェクト名**: 各プロジェクトは一意の名前で識別されます。プロジェクト名は、簡潔で関連する内容を反映したものにします。
- **開始日と終了日**: 各プロジェクトには開始日と終了日を設定し、これを基にスケジュールを管理します。プロジェクトの進行状況は、これらの日時に基づいて評価されます。
- **ステータス管理**: プロジェクトの進捗状況は「進行中」、「完了」、「保留」などのステータスで管理され、プロジェクトの現状をリアルタイムで把握することができます。
- **メンバー管理**: プロジェクトメンバーの追加や削除が可能であり、プロジェクトのニーズに応じて柔軟に対応できます。ただし、削除時には確認メッセージが表示されないため、注意が必要です。

## 注意事項

- **保存操作の重要性**: プロジェクト情報の変更を保存しないまま画面を移動すると、変更が失われる可能性があるため、常に保存操作を行うことが重要です。
- **ステータス管理**: プロジェクトの進捗を正確に反映させるため、ステータスの更新を怠らないようにしてください。特に、プロジェクトの節目ごとに「進行中」から「完了」へのステータス変更を行うことが求められます。
- **日付管理**: プロジェクトの開始日と終了日は、チームの作業スケジュールに影響を与えるため、正確に設定してください。これにより、遅延や誤解を防ぎます。

## 関連情報

### web
- [プロジェクト一覧](web/project_list/project_list.html)
  - [プロジェクト詳細](web/project_list/project_list_details/project_detail.html)
- [タスク管理](web/task_management/task_management.html)
- [メンバー管理](web/member_management/member_management.html)

### tablet
- [プロジェクト実施](tablet/project_implementation/project_implementation.html)
  - [プロジェクト進捗](tablet/project_implementation/project_progress/project_progress.html)
    - [メンバー変更](tablet/project_implementation/project_progress/change_of_member/change_of_member.html)
  - [プロジェクト開始](tablet/project_implementation/project_start/project_start.html)

作成手順

Markdownファイルの作成
拡張子は.md。内容は他の操作説明書を参考にするか、ネットで調査して書き方を確認してください。
MarkdownファイルをHTMLに変換
VSCodeでCtrl + Shift + Pを押し、Markdown PDF: Export HTMLを選択します。
HTMLファイルのプレビュー
Markdownファイルと同じディレクトリにHTMLファイルが作成されるので、それを開きます。
Live Serverでプレビュー
VSCodeの右下にあるGo Liveボタンをクリックすると、ローカルサーバーが起動し、HTMLファイルの変更がリアルタイムで反映されます。

作業の進め方

Markdownファイルの作成
HTMLファイルへの変換とプレビュー

これらの手順を繰り返して、内容を確認しながら作成を進めてください。最終的に完成したら、MarkdownファイルとHTMLファイルをコミットして保存します。

本番環境へのリリースと適用方法

本番環境にHTMLファイルを反映する際は、セキュリティ対策として認証が通らない限り閲覧できない設定にします。具体的には、ドキュメントフォルダをサーバーに配置し、適切な認証機構を設定して保護する方法が一般的です。

まとめ

操作説明書は、ユーザーのガイドとしてだけでなく、設計書としても活用できます。エクセルやワードのように差分管理が難しいツールではなく、Markdownを使うことで、エンジニアが楽しみながら効率的に文書を作成できるようになるでしょう。