Suche senden
Hochladen
インフラエンジニアの綺麗で優しい手順書の書き方
•
311 gefällt mir
•
146,437 views
Shohei Koyama
Folgen
インフラエンジニアの綺麗で優しい手順書の書き方
Weniger lesen
Mehr lesen
Ingenieurwesen
Melden
Teilen
Melden
Teilen
1 von 34
Jetzt herunterladen
Downloaden Sie, um offline zu lesen
Empfohlen
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Kohei Tokunaga
Redisの特徴と活用方法について
Redisの特徴と活用方法について
Yuji Otani
開発速度が速い #とは(LayerX社内資料)
開発速度が速い #とは(LayerX社内資料)
mosa siru
フロー効率性とリソース効率性について #xpjug
フロー効率性とリソース効率性について #xpjug
Itsuki Kuroda
BuildKitによる高速でセキュアなイメージビルド
BuildKitによる高速でセキュアなイメージビルド
Akihiro Suda
インフラエンジニアってなんでしたっけ(仮)
インフラエンジニアってなんでしたっけ(仮)
Akihiro Kuwano
Kubernetesでの性能解析 ~なんとなく遅いからの脱却~(Kubernetes Meetup Tokyo #33 発表資料)
Kubernetesでの性能解析 ~なんとなく遅いからの脱却~(Kubernetes Meetup Tokyo #33 発表資料)
NTT DATA Technology & Innovation
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
Yoshiki Hayama
Empfohlen
Dockerからcontainerdへの移行
Dockerからcontainerdへの移行
Kohei Tokunaga
Redisの特徴と活用方法について
Redisの特徴と活用方法について
Yuji Otani
開発速度が速い #とは(LayerX社内資料)
開発速度が速い #とは(LayerX社内資料)
mosa siru
フロー効率性とリソース効率性について #xpjug
フロー効率性とリソース効率性について #xpjug
Itsuki Kuroda
BuildKitによる高速でセキュアなイメージビルド
BuildKitによる高速でセキュアなイメージビルド
Akihiro Suda
インフラエンジニアってなんでしたっけ(仮)
インフラエンジニアってなんでしたっけ(仮)
Akihiro Kuwano
Kubernetesでの性能解析 ~なんとなく遅いからの脱却~(Kubernetes Meetup Tokyo #33 発表資料)
Kubernetesでの性能解析 ~なんとなく遅いからの脱却~(Kubernetes Meetup Tokyo #33 発表資料)
NTT DATA Technology & Innovation
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
「のどが渇いた」というユーザーに何を出す? ユーザーの「欲しい」に惑わされない、本当のインサイトを見つけるUXデザイン・UXリサーチ
Yoshiki Hayama
Keycloak拡張入門
Keycloak拡張入門
Hiroyuki Wada
Kongの概要と導入事例
Kongの概要と導入事例
briscola-tokyo
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
mosa siru
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
マイクロサービスにおける 結果整合性との戦い
マイクロサービスにおける 結果整合性との戦い
ota42y
IT系エンジニアのためのプレゼンテーション入門
IT系エンジニアのためのプレゼンテーション入門
Masahito Zembutsu
Istioサービスメッシュ入門
Istioサービスメッシュ入門
Yoichi Kawasaki
分散トレーシング技術について(Open tracingやjaeger)
分散トレーシング技術について(Open tracingやjaeger)
NTT Communications Technology Development
40歳過ぎてもエンジニアでいるためにやっていること
40歳過ぎてもエンジニアでいるためにやっていること
onozaty
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
Yahoo!デベロッパーネットワーク
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Shin Ohno
ユーザーインタビューするときは、どうやらゾンビのおでましさ
ユーザーインタビューするときは、どうやらゾンビのおでましさ
Yoshiki Hayama
トランザクションスクリプトのすすめ
トランザクションスクリプトのすすめ
pospome
分散システムについて語らせてくれ
分散システムについて語らせてくれ
Kumazaki Hiroki
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
Tokoroten Nakayama
モノタロウの1900万商品を検索する Elasticsearch構築運用事例(2022-10-26 第50回Elasticsearch 勉強会発表資料)
モノタロウの1900万商品を検索する Elasticsearch構築運用事例(2022-10-26 第50回Elasticsearch 勉強会発表資料)
株式会社MonotaRO Tech Team
Oss貢献超入門
Oss貢献超入門
Michihito Shigemura
こわくない Git
こわくない Git
Kota Saito
webエンジニアのためのはじめてのredis
webエンジニアのためのはじめてのredis
nasa9084
これからはじめるインフラエンジニア
これからはじめるインフラエンジニア
外道 父
インフラエンジニアがUnityをやるべきたった一つの理由
インフラエンジニアがUnityをやるべきたった一つの理由
axsh co., LTD.
Weitere ähnliche Inhalte
Was ist angesagt?
Keycloak拡張入門
Keycloak拡張入門
Hiroyuki Wada
Kongの概要と導入事例
Kongの概要と導入事例
briscola-tokyo
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
mosa siru
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
マイクロサービスにおける 結果整合性との戦い
マイクロサービスにおける 結果整合性との戦い
ota42y
IT系エンジニアのためのプレゼンテーション入門
IT系エンジニアのためのプレゼンテーション入門
Masahito Zembutsu
Istioサービスメッシュ入門
Istioサービスメッシュ入門
Yoichi Kawasaki
分散トレーシング技術について(Open tracingやjaeger)
分散トレーシング技術について(Open tracingやjaeger)
NTT Communications Technology Development
40歳過ぎてもエンジニアでいるためにやっていること
40歳過ぎてもエンジニアでいるためにやっていること
onozaty
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
Yahoo!デベロッパーネットワーク
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Shin Ohno
ユーザーインタビューするときは、どうやらゾンビのおでましさ
ユーザーインタビューするときは、どうやらゾンビのおでましさ
Yoshiki Hayama
トランザクションスクリプトのすすめ
トランザクションスクリプトのすすめ
pospome
分散システムについて語らせてくれ
分散システムについて語らせてくれ
Kumazaki Hiroki
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
Kentaro Matsui
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
Tokoroten Nakayama
モノタロウの1900万商品を検索する Elasticsearch構築運用事例(2022-10-26 第50回Elasticsearch 勉強会発表資料)
モノタロウの1900万商品を検索する Elasticsearch構築運用事例(2022-10-26 第50回Elasticsearch 勉強会発表資料)
株式会社MonotaRO Tech Team
Oss貢献超入門
Oss貢献超入門
Michihito Shigemura
こわくない Git
こわくない Git
Kota Saito
webエンジニアのためのはじめてのredis
webエンジニアのためのはじめてのredis
nasa9084
Was ist angesagt?
(20)
Keycloak拡張入門
Keycloak拡張入門
Kongの概要と導入事例
Kongの概要と導入事例
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
マイクロサービスにおける 結果整合性との戦い
マイクロサービスにおける 結果整合性との戦い
IT系エンジニアのためのプレゼンテーション入門
IT系エンジニアのためのプレゼンテーション入門
Istioサービスメッシュ入門
Istioサービスメッシュ入門
分散トレーシング技術について(Open tracingやjaeger)
分散トレーシング技術について(Open tracingやjaeger)
40歳過ぎてもエンジニアでいるためにやっていること
40歳過ぎてもエンジニアでいるためにやっていること
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
実運用して分かったRabbit MQの良いところ・気をつけること #jjug
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
Mercari JPのモノリスサービスをKubernetesに移行した話 PHP Conference 2022 9/24
ユーザーインタビューするときは、どうやらゾンビのおでましさ
ユーザーインタビューするときは、どうやらゾンビのおでましさ
トランザクションスクリプトのすすめ
トランザクションスクリプトのすすめ
分散システムについて語らせてくれ
分散システムについて語らせてくれ
テスト文字列に「うんこ」と入れるな
テスト文字列に「うんこ」と入れるな
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
心理的安全性の構造 デブサミ2019夏 structure of psychological safety
モノタロウの1900万商品を検索する Elasticsearch構築運用事例(2022-10-26 第50回Elasticsearch 勉強会発表資料)
モノタロウの1900万商品を検索する Elasticsearch構築運用事例(2022-10-26 第50回Elasticsearch 勉強会発表資料)
Oss貢献超入門
Oss貢献超入門
こわくない Git
こわくない Git
webエンジニアのためのはじめてのredis
webエンジニアのためのはじめてのredis
Andere mochten auch
これからはじめるインフラエンジニア
これからはじめるインフラエンジニア
外道 父
インフラエンジニアが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
Andere mochten auch
(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回 プログラマのための数学勉強会 発表資料
実践イカパケット解析
実践イカパケット解析
プログラマのための線形代数再入門
プログラマのための線形代数再入門
Ähnlich wie インフラエンジニアの綺麗で優しい手順書の書き方
わかると楽しい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
Ähnlich wie インフラエンジニアの綺麗で優しい手順書の書き方
(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.
最後に 皆さんも優しい手順書を書きましょう!
Jetzt herunterladen