Enviar búsqueda
Cargar
インフラエンジニアの綺麗で優しい手順書の書き方
•
311 recomendaciones
•
146,427 vistas
Shohei Koyama
Seguir
インフラエンジニアの綺麗で優しい手順書の書き方
Leer menos
Leer más
Ingeniería
Denunciar
Compartir
Denunciar
Compartir
1 de 34
Descargar ahora
Descargar para leer sin conexión
Recomendados
フロー効率性とリソース効率性について #xpjug
フロー効率性とリソース効率性について #xpjug
Itsuki Kuroda
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Takafumi ONAKA
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
Takuto Wada
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
Tokoroten Nakayama
本当は恐ろしい分散システムの話
本当は恐ろしい分散システムの話
Kumazaki Hiroki
分散トレーシング技術について(Open tracingやjaeger)
分散トレーシング技術について(Open tracingやjaeger)
NTT Communications Technology Development
初心者向けMongoDBのキホン!
初心者向けMongoDBのキホン!
Tetsutaro Watanabe
ソーシャルゲームのためのデータベース設計
ソーシャルゲームのためのデータベース設計
Yoshinori Matsunobu
Recomendados
フロー効率性とリソース効率性について #xpjug
フロー効率性とリソース効率性について #xpjug
Itsuki Kuroda
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Takafumi ONAKA
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
SQLアンチパターン 幻の第26章「とりあえず削除フラグ」
Takuto Wada
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
チャットコミュニケーションの問題と心理的安全性の課題 #EOF2019
Tokoroten Nakayama
本当は恐ろしい分散システムの話
本当は恐ろしい分散システムの話
Kumazaki Hiroki
分散トレーシング技術について(Open tracingやjaeger)
分散トレーシング技術について(Open tracingやjaeger)
NTT Communications Technology Development
初心者向けMongoDBのキホン!
初心者向けMongoDBのキホン!
Tetsutaro Watanabe
ソーシャルゲームのためのデータベース設計
ソーシャルゲームのためのデータベース設計
Yoshinori Matsunobu
45分間で「ユーザー中心のものづくり」ができるまで詰め込む
45分間で「ユーザー中心のものづくり」ができるまで詰め込む
Yoshiki Hayama
インフラエンジニアってなんでしたっけ(仮)
インフラエンジニアってなんでしたっけ(仮)
Akihiro Kuwano
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
NTT DATA Technology & Innovation
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
mosa siru
Redisの特徴と活用方法について
Redisの特徴と活用方法について
Yuji Otani
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Akihiro Suda
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Shin Ohno
Linux女子部 systemd徹底入門
Linux女子部 systemd徹底入門
Etsuji Nakai
BuildKitによる高速でセキュアなイメージビルド
BuildKitによる高速でセキュアなイメージビルド
Akihiro Suda
「速」を落とさないコードレビュー
「速」を落とさないコードレビュー
Takafumi ONAKA
SQLアンチパターン - 開発者を待ち受ける25の落とし穴 (拡大版)
SQLアンチパターン - 開発者を待ち受ける25の落とし穴 (拡大版)
Takuto Wada
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
Yoshiki Hayama
KeycloakでAPI認可に入門する
KeycloakでAPI認可に入門する
Hitachi, Ltd. OSS Solution Center.
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Takeshi Mikami
今こそ知りたいSpring Batch(Spring Fest 2020講演資料)
今こそ知りたいSpring Batch(Spring Fest 2020講演資料)
NTT DATA Technology & Innovation
それはYAGNIか? それとも思考停止か?
それはYAGNIか? それとも思考停止か?
Yoshitaka Kawashima
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
Yahoo!デベロッパーネットワーク
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Kohei Tokunaga
イミュータブルデータモデルの極意
イミュータブルデータモデルの極意
Yoshitaka Kawashima
これからはじめるインフラエンジニア
これからはじめるインフラエンジニア
外道 父
インフラエンジニアがUnityをやるべきたった一つの理由
インフラエンジニアがUnityをやるべきたった一つの理由
axsh co., LTD.
Más contenido relacionado
La actualidad más candente
45分間で「ユーザー中心のものづくり」ができるまで詰め込む
45分間で「ユーザー中心のものづくり」ができるまで詰め込む
Yoshiki Hayama
インフラエンジニアってなんでしたっけ(仮)
インフラエンジニアってなんでしたっけ(仮)
Akihiro Kuwano
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
NTT DATA Technology & Innovation
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
mosa siru
Redisの特徴と活用方法について
Redisの特徴と活用方法について
Yuji Otani
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Akihiro Suda
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Shin Ohno
Linux女子部 systemd徹底入門
Linux女子部 systemd徹底入門
Etsuji Nakai
BuildKitによる高速でセキュアなイメージビルド
BuildKitによる高速でセキュアなイメージビルド
Akihiro Suda
「速」を落とさないコードレビュー
「速」を落とさないコードレビュー
Takafumi ONAKA
SQLアンチパターン - 開発者を待ち受ける25の落とし穴 (拡大版)
SQLアンチパターン - 開発者を待ち受ける25の落とし穴 (拡大版)
Takuto Wada
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
Yoshiki Hayama
KeycloakでAPI認可に入門する
KeycloakでAPI認可に入門する
Hitachi, Ltd. OSS Solution Center.
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Takeshi Mikami
今こそ知りたいSpring Batch(Spring Fest 2020講演資料)
今こそ知りたいSpring Batch(Spring Fest 2020講演資料)
NTT DATA Technology & Innovation
それはYAGNIか? それとも思考停止か?
それはYAGNIか? それとも思考停止か?
Yoshitaka Kawashima
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
Yahoo!デベロッパーネットワーク
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Kohei Tokunaga
イミュータブルデータモデルの極意
イミュータブルデータモデルの極意
Yoshitaka Kawashima
La actualidad más candente
(20)
45分間で「ユーザー中心のものづくり」ができるまで詰め込む
45分間で「ユーザー中心のものづくり」ができるまで詰め込む
インフラエンジニアってなんでしたっけ(仮)
インフラエンジニアってなんでしたっけ(仮)
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
モノリスからマイクロサービスへの移行 ~ストラングラーパターンの検証~(Spring Fest 2020講演資料)
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
Redisの特徴と活用方法について
Redisの特徴と活用方法について
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Linux女子部 systemd徹底入門
Linux女子部 systemd徹底入門
BuildKitによる高速でセキュアなイメージビルド
BuildKitによる高速でセキュアなイメージビルド
「速」を落とさないコードレビュー
「速」を落とさないコードレビュー
SQLアンチパターン - 開発者を待ち受ける25の落とし穴 (拡大版)
SQLアンチパターン - 開発者を待ち受ける25の落とし穴 (拡大版)
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
KeycloakでAPI認可に入門する
KeycloakでAPI認可に入門する
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
今こそ知りたいSpring Batch(Spring Fest 2020講演資料)
今こそ知りたいSpring Batch(Spring Fest 2020講演資料)
それはYAGNIか? それとも思考停止か?
それはYAGNIか? それとも思考停止か?
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
イミュータブルデータモデルの極意
イミュータブルデータモデルの極意
Destacado
これからはじめるインフラエンジニア
これからはじめるインフラエンジニア
外道 父
インフラエンジニアがUnityをやるべきたった一つの理由
インフラエンジニアがUnityをやるべきたった一つの理由
axsh co., LTD.
プログラムを高速化する話
プログラムを高速化する話
京大 マイコンクラブ
テスト駆動インフラ構築-Chefとserverspecを使ったインフラ自動化のすすめ-
テスト駆動インフラ構築-Chefとserverspecを使ったインフラ自動化のすすめ-
賢 秋穂
⼤企業で実現するイマドキの内製開発
⼤企業で実現するイマドキの内製開発
NTT Communications Technology Development
アプリエンジニアからクラウド専用のインフラエンジニアになってみて
アプリエンジニアからクラウド専用のインフラエンジニアになってみて
Sato Shun
インフラ構築とテストについて(ITインフラ業務自動化現状確認会)
インフラ構築とテストについて(ITインフラ業務自動化現状確認会)
Yosuke Hiraishi
2015-05-23 クラウドの運用になって インフラエンジニアは何が変わるのか?
2015-05-23 クラウドの運用になって インフラエンジニアは何が変わるのか?
Operation Lab, LLC.
(Beta)clean release manual
(Beta)clean release manual
Takao Oyobe
ルータでルータのプレゼンをした話。 ~# 技術解説
ルータでルータのプレゼンをした話。 ~# 技術解説
Takumi Sueda
5分で出来る!イケてるconfluenceページ
5分で出来る!イケてるconfluenceページ
CLARA ONLINE, Inc.
Configuration As Code - Adoption of the Job DSL Plugin at Netflix
Configuration As Code - Adoption of the Job DSL Plugin at Netflix
Justin Ryan
DevOps Practices:Configuration as Code
DevOps Practices:Configuration as Code
Doug Seven
偶然にも500万個のSSH公開鍵を手に入れた俺たちは
偶然にも500万個のSSH公開鍵を手に入れた俺たちは
Yoshio Hanawa
技術選択とアーキテクトの役割
技術選択とアーキテクトの役割
Toru Yamaguchi
プログラム組んだら負け!実はHTML/CSSだけでできること2015夏
プログラム組んだら負け!実はHTML/CSSだけでできること2015夏
Yusuke Hirao
運用に自動化を求めるのは間違っているだろうか
運用に自動化を求めるのは間違っているだろうか
Masahito Zembutsu
「内積が見えると統計学も見える」第5回 プログラマのための数学勉強会 発表資料
「内積が見えると統計学も見える」第5回 プログラマのための数学勉強会 発表資料
Ken'ichi Matsui
実践イカパケット解析
実践イカパケット解析
Yuki Mizuno
プログラマのための線形代数再入門
プログラマのための線形代数再入門
Taketo Sano
Destacado
(20)
これからはじめるインフラエンジニア
これからはじめるインフラエンジニア
インフラエンジニアがUnityをやるべきたった一つの理由
インフラエンジニアがUnityをやるべきたった一つの理由
プログラムを高速化する話
プログラムを高速化する話
テスト駆動インフラ構築-Chefとserverspecを使ったインフラ自動化のすすめ-
テスト駆動インフラ構築-Chefとserverspecを使ったインフラ自動化のすすめ-
⼤企業で実現するイマドキの内製開発
⼤企業で実現するイマドキの内製開発
アプリエンジニアからクラウド専用のインフラエンジニアになってみて
アプリエンジニアからクラウド専用のインフラエンジニアになってみて
インフラ構築とテストについて(ITインフラ業務自動化現状確認会)
インフラ構築とテストについて(ITインフラ業務自動化現状確認会)
2015-05-23 クラウドの運用になって インフラエンジニアは何が変わるのか?
2015-05-23 クラウドの運用になって インフラエンジニアは何が変わるのか?
(Beta)clean release manual
(Beta)clean release manual
ルータでルータのプレゼンをした話。 ~# 技術解説
ルータでルータのプレゼンをした話。 ~# 技術解説
5分で出来る!イケてるconfluenceページ
5分で出来る!イケてるconfluenceページ
Configuration As Code - Adoption of the Job DSL Plugin at Netflix
Configuration As Code - Adoption of the Job DSL Plugin at Netflix
DevOps Practices:Configuration as Code
DevOps Practices:Configuration as Code
偶然にも500万個のSSH公開鍵を手に入れた俺たちは
偶然にも500万個のSSH公開鍵を手に入れた俺たちは
技術選択とアーキテクトの役割
技術選択とアーキテクトの役割
プログラム組んだら負け!実はHTML/CSSだけでできること2015夏
プログラム組んだら負け!実はHTML/CSSだけでできること2015夏
運用に自動化を求めるのは間違っているだろうか
運用に自動化を求めるのは間違っているだろうか
「内積が見えると統計学も見える」第5回 プログラマのための数学勉強会 発表資料
「内積が見えると統計学も見える」第5回 プログラマのための数学勉強会 発表資料
実践イカパケット解析
実践イカパケット解析
プログラマのための線形代数再入門
プログラマのための線形代数再入門
Similar a インフラエンジニアの綺麗で優しい手順書の書き方
わかると楽しいInfrastructure as code
わかると楽しいInfrastructure as code
Shohei Kobayashi
俺とSe(自己紹介)
俺とSe(自己紹介)
Masayuki KaToH
インフラエンジニアとして普段心がけていること
インフラエンジニアとして普段心がけていること
Shohei Koyama
鹿駆動
鹿駆動
Shinichi Kozake
シナリオレビューという手法の提案
シナリオレビューという手法の提案
tuna cook
PHPアプリの品質を(ある程度)保つために出来る事 〜組織編〜
PHPアプリの品質を(ある程度)保つために出来る事 〜組織編〜
Katsuhiro Miura
パフォーマンステストいつやる??
パフォーマンステストいつやる??
Shuichi Takaku
○○したら受託開発が180°変わった
○○したら受託開発が180°変わった
Atsushi Harada
2014-10-27 #ssmjp 腹を割って話そう (運用xセキュリティ)
2014-10-27 #ssmjp 腹を割って話そう (運用xセキュリティ)
Operation Lab, LLC.
Ciecleci
Ciecleci
YosukeHojo
20100520 【qpstudy01】 チームでトライ!インフラ構築のススメ
20100520 【qpstudy01】 チームでトライ!インフラ構築のススメ
Yukitaka Ohmura
Roo
Roo
terahide
Rubyの会社でPythonistaが3ヶ月生き延びた話
Rubyの会社でPythonistaが3ヶ月生き延びた話
Tokoroten Nakayama
Rubyの会社でPythonistaが三ヶ月生き延びた話
Rubyの会社でPythonistaが三ヶ月生き延びた話
Drecom Co., Ltd.
RPAを快適に使いたい
RPAを快適に使いたい
Hiroyuki Eguchi
本の紹介
本の紹介
t w
Aizu.LT16 社会人1年目の失敗とContinuous Integration
Aizu.LT16 社会人1年目の失敗とContinuous Integration
Tomoaki Tamura
オンプレエンジニアがクラウドエンジニアを夢見て。じっと手を見る。
オンプレエンジニアがクラウドエンジニアを夢見て。じっと手を見る。
Akihiro Kuwano
connpass特徴と開発の流れ
connpass特徴と開発の流れ
Ikeda Yosuke
Startup react lt
Startup react lt
Yusuke Mori
Similar a インフラエンジニアの綺麗で優しい手順書の書き方
(20)
わかると楽しいInfrastructure as code
わかると楽しいInfrastructure as code
俺とSe(自己紹介)
俺とSe(自己紹介)
インフラエンジニアとして普段心がけていること
インフラエンジニアとして普段心がけていること
鹿駆動
鹿駆動
シナリオレビューという手法の提案
シナリオレビューという手法の提案
PHPアプリの品質を(ある程度)保つために出来る事 〜組織編〜
PHPアプリの品質を(ある程度)保つために出来る事 〜組織編〜
パフォーマンステストいつやる??
パフォーマンステストいつやる??
○○したら受託開発が180°変わった
○○したら受託開発が180°変わった
2014-10-27 #ssmjp 腹を割って話そう (運用xセキュリティ)
2014-10-27 #ssmjp 腹を割って話そう (運用xセキュリティ)
Ciecleci
Ciecleci
20100520 【qpstudy01】 チームでトライ!インフラ構築のススメ
20100520 【qpstudy01】 チームでトライ!インフラ構築のススメ
Roo
Roo
Rubyの会社でPythonistaが3ヶ月生き延びた話
Rubyの会社でPythonistaが3ヶ月生き延びた話
Rubyの会社でPythonistaが三ヶ月生き延びた話
Rubyの会社でPythonistaが三ヶ月生き延びた話
RPAを快適に使いたい
RPAを快適に使いたい
本の紹介
本の紹介
Aizu.LT16 社会人1年目の失敗とContinuous Integration
Aizu.LT16 社会人1年目の失敗とContinuous Integration
オンプレエンジニアがクラウドエンジニアを夢見て。じっと手を見る。
オンプレエンジニアがクラウドエンジニアを夢見て。じっと手を見る。
connpass特徴と開発の流れ
connpass特徴と開発の流れ
Startup react lt
Startup react lt
インフラエンジニアの綺麗で優しい手順書の書き方
1.
インフラエンジニアの 綺麗で優しい手順書の書き方 湖山 翔平 /
Shohei.Koyama @sion_cojp
2.
自己紹介 湖山 翔平 /
@sion_cojp 元FPSプロゲーマーでアジアチャンピオン qiitaをよく書いてます (http://qiita.com/sion_cojp) インフラエンジニアとしてよく使うコマンド集 インフラエンジニア 株式会社リブセンス
3.
Infrastructure as Codeが流行ってる中、 どうしても手順書じゃないといけない場面 ってありますよね
4.
やっぱり手順書って大事
5.
でも読みにく手順書では意味がありません (最悪、障害時に混乱を招く DeathNote
に。) ①レビュー➡修正➡レビュー・・・の繰り返しで工数がかかる ②レビューする方も大変だし工数がかかる ③お互いに疲れる
6.
良い手順を書くと、そりゃもう良い事尽くしです ・信頼確保 ・レビューワーの負荷軽減 ・レビュー後の修正も減る ・新入社員、新卒の方が喜ぶ ・汎用手順を書きやすい ・障害対応のとき焦らない ・障害対応のときの安心感 ・情報が後者に残る ・qiitaにもそのまま載せやすい ・評価もあがる・・・はず!!
7.
手順書は優しさです 如何に他人に気を遣えるかです 後者のためになるので頑張りましょう きれいな手順書をいっぱい書く人はもっと評価されてもいいと思う!!
8.
今回は自分なりに手順書を書くときやレビューするときに 注意してることを実際の経験談をもとにお話しします ちなみに 弊社で手順書を書いてるツールは Confluenceです
9.
1. 書き方を統一しよう 手順書のフォーマットを作る 主題は4つ ① 概要 ②
事前準備 ③ 作業内容 ④ 事後確認&作業 目次も忘れずにつけましょう
10.
また、同じ手順を踏んでるのであれば、 目次や内容がそっくりになるようにします
11.
実際にあった話だと、 同じデプロイツールで、社内アプリをデプロイする手順なのに、 作業内容の見出しが全くが違う。。 Bアプリのデプロイ手順Aアプリのデプロイ手順 違うデプロイツールなのかな?
12.
修正後、同じ見出しに統一。 これで直感的に同じデプロイツールを使ってそうなのがわかりますね Aアプリのデプロイ手順 Bアプリのデプロイ手順
13.
2. コードブロックにはsyntaxハイライトをつけよう syntaxハイライトを付けると、 文字が強調され見やすくなります。 一つ一つ付けるのは面倒くさいかもしれませんが、 ちゃんと付けましょう ばっしゅハイライトしんたっくすあり 見やすい!
14.
個人的には特定の言語こだわりがなければ bashを使います。 #(コメントアウト)が緑色に強調されるので使いやすいからです。 ごく稀にDiffも使います。 私はコメントアウトの使い方を下記に統一してます ① 作業の説明は ###
と3つつける ② オプションや行の説明を加えるときは# 1つを使う こんな感じでオプション説明 作業説明は# 3つ!
15.
3. プロンプトは$で統一 rootだと#だったりしますよね。 でもコメントアウトと見誤ってしまうので、 [root] $ service
httpd restart とかで統一してあげると、親切です コマンド入力忘れも減るでしょう。
16.
4. 何をやってるか、コマンド毎に説明を書く 簡単なコマンドならまだ良いとして、 「この設定値なんだろう?」 「このオプションなんだろう?」 など、手順書はググらなくてもいいように書いてあげましょう その手順書内で完結がベスト また、「この人ちゃんと理解してやってるな」と レビューワーに安心感も与えれます
17.
上からなぞっていくのが手順書なので、 コードブロックは少ない方が、 「あれ?今このブロックだっけ?」みたいなことにならないです ssh先を変える毎にコードブロックを作るのもありです わかりやすい!
18.
5. 手順書内完結を目指す 「この手順でドメイン移管よろしく」 概要を見ると・・・ こんなこと書かれてても新卒さん達はさっぱりですよね。 結局ぐぐって。。でもあまり分からなくて。。 手順も同じです。 概要に書いてることは、wikiから引用せず、 新卒でも分かりやすいサイトや、 なければ理解しやすいように図や比較表に落とし込んで リンクを貼ってあげましょう 基本ググらせない 手順内で完結がモットー!
19.
遠い言い回しはNG。簡潔に。 なるべく言葉数は最小限になるように考えましょう。 行数は1∼3行に収まるようにしましょう。(ベストは1行) 例をあげると、 のほうが言葉が短いので見易いです。 「そのまま打ったコマンド貼り付けたほうが楽」 と編集が億劫になるかもしれませんが、めげずに! 6. 文字数、行数、見出しの数は最小限に こっちより こっち!
20.
7. ルー語禁止 誰でも伝わる日本語で書きましょう。 個人的には意識高い系用語も避けてます。
21.
8. 手順外、内で行ったり来たりしないようにする 行ったり来たりすると、読みにくくなります。 手順書は縦になぞっていくので、 縦はもちろん、横の行ったり来たりの動きは あまり入れないほうがいいです。 それは表や図の挿入でも起こります。 なるべく表や図は概要などのトップに持って行って、 あとはコードさえ読めばいい形にすると 読みやすい手順になるでしょう
22.
一見よさそうだが・・・ 見出しにも 値を入れた方が 戻らなくていいので親切 わかりやすい!
23.
読みづらくなるので。 9. 分岐が多いなら別の手順書に書きましょう
24.
10. 自分の感想や、昧な表現はさけましょう 「私は⚪⚪だと思うけど、今回はこうします」 「⚪⚪とか、xxなど」 「手順書なのに・・・なんか検証内容が微妙に書いてるんだけど・・・」 読書感想文ではありません。 本当に必要な情報なら、別の場所に書きましょう。
25.
11. 図は線は太く少なく、文字も太く見やすく 拡大しないと見えない図なんて、あまり見られないでしょう。 大きく、太く。そして簡潔に。 色も統一性を考えてあげると、見やすくなるでしょう 図の製作はCacooがおすすめです。 わかりやすい!
26.
ここからは 出来上がった手順書のチェック関連!!
27.
12. 主題と内容に相違がないかチェック 「移行手順しかないけど、これ新しくサーバ構築してるよね?」 「デプロイ設定って書いてるけど、普通に本番でデプロイ実行してるよね?」 レビューワーが困っちゃいます。 ちゃんとチェックしましょう
28.
13. 手順書が置かれてるディレクトリをチェック 構築手順なのに、障害対応のところにあったり スポット手順なのに、汎用手順類にあったり ちゃんと置いてあげましょう ちなみに弊社のトップ階層はこんな感じです
29.
14. 新卒でも分かるように書いてあるかチェック 手順書を一番見るのは新卒さんや、新入社員さんなんですよね。 ここは新卒に合わせておけば大丈夫!
30.
15. 誤字脱字がないかチェック レビューワーの負荷軽減のために、軽くチェック
31.
16. 脳内でシミュレーションをして動作チェック 検証環境でやるのもいいんですが、 脳内シミュレーションは絶対やりましょう。 障害訓練の一環にもなります。
32.
まとめると 1. 書き方を統一しよう 2. コードブロックにはsyntaxハイライトをつけよう 3.
プロンプトは$で統一 4. 何をやってるか、コマンド毎に説明を書く 5. 手順書内完結を目指す 6. 文字数、行数、見出しの数は最小限に 7. ルー語禁止 8. 手順外、内で行ったり来たりしないようにする 9. 分岐が多いなら別の手順書に書きましょう 10.自分の感想や、昧な表現はさけましょう 11. 図は線は太く少なく、文字も太く見やすく [チェック編] 12. 主題と内容に相違がないかチェック 13. 手順書が置かれてるディレクトリをチェック 14. 新卒でも分かるように書いてあるかチェック 15. 誤字脱字がないかチェック 16. 脳内でシミュレーションをして動作チェック
33.
以上です!
34.
最後に 皆さんも優しい手順書を書きましょう!
Descargar ahora