Enviar búsqueda
Cargar
インフラエンジニアの綺麗で優しい手順書の書き方
•
311 recomendaciones
•
146,206 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
インフラエンジニアってなんでしたっけ(仮)
インフラエンジニアってなんでしたっけ(仮)
Akihiro Kuwano
マイクロにしすぎた結果がこれだよ!
マイクロにしすぎた結果がこれだよ!
mosa siru
[Aurora事例祭り]Amazon Aurora を使いこなすためのベストプラクティス
[Aurora事例祭り]Amazon Aurora を使いこなすためのベストプラクティス
Amazon Web Services Japan
インフラCICDの勘所
インフラCICDの勘所
Toru Makabe
DXとかDevOpsとかのなんかいい感じのやつ 富士通TechLive
DXとかDevOpsとかのなんかいい感じのやつ 富士通TechLive
Tokoroten Nakayama
Spring Boot の Web アプリケーションを Docker に載せて AWS ECS で動かしている話
Spring Boot の Web アプリケーションを Docker に載せて AWS ECS で動かしている話
JustSystems Corporation
エンジニアの個人ブランディングと技術組織
エンジニアの個人ブランディングと技術組織
Takafumi ONAKA
TIME_WAITに関する話
TIME_WAITに関する話
Takanori Sejima
Más contenido relacionado
La actualidad más candente
コンテナの作り方「Dockerは裏方で何をしているのか?」
コンテナの作り方「Dockerは裏方で何をしているのか?」
Masahito Zembutsu
PlaySQLAlchemy: SQLAlchemy入門
PlaySQLAlchemy: SQLAlchemy入門
泰 増田
分散トレーシング技術について(Open tracingやjaeger)
分散トレーシング技術について(Open tracingやjaeger)
NTT Communications Technology Development
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Atsushi Nakada
Guide To AGPL
Guide To AGPL
Mikiya Okuno
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Takeshi Mikami
KeycloakでAPI認可に入門する
KeycloakでAPI認可に入門する
Hitachi, Ltd. OSS Solution Center.
人生がときめくAPIテスト自動化 with Karate
人生がときめくAPIテスト自動化 with Karate
Takanori Suzuki
Kubernetesのしくみ やさしく学ぶ 内部構造とアーキテクチャー
Kubernetesのしくみ やさしく学ぶ 内部構造とアーキテクチャー
Toru Makabe
40歳過ぎてもエンジニアでいるためにやっていること
40歳過ぎてもエンジニアでいるためにやっていること
onozaty
Google Cloud で実践する SRE
Google Cloud で実践する SRE
Google Cloud Platform - Japan
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
Trainocate Japan, Ltd.
開発速度が速い #とは(LayerX社内資料)
開発速度が速い #とは(LayerX社内資料)
mosa siru
PostgreSQLのロール管理とその注意点(Open Source Conference 2022 Online/Osaka 発表資料)
PostgreSQLのロール管理とその注意点(Open Source Conference 2022 Online/Osaka 発表資料)
NTT DATA Technology & Innovation
backlogsでもCI/CDする夢を見る
backlogsでもCI/CDする夢を見る
Takeru Maehara
Azure Api Management 俺的マニュアル 2020年3月版
Azure Api Management 俺的マニュアル 2020年3月版
貴志 上坂
フロー効率性とリソース効率性について #xpjug
フロー効率性とリソース効率性について #xpjug
Itsuki Kuroda
PostgreSQLをKubernetes上で活用するためのOperator紹介!(Cloud Native Database Meetup #3 発表資料)
PostgreSQLをKubernetes上で活用するためのOperator紹介!(Cloud Native Database Meetup #3 発表資料)
NTT DATA Technology & Innovation
マルチテナント化で知っておきたいデータベースのこと
マルチテナント化で知っておきたいデータベースのこと
Amazon Web Services Japan
組織にテストを書く文化を根付かせる戦略と戦術
組織にテストを書く文化を根付かせる戦略と戦術
Takuto Wada
La actualidad más candente
(20)
コンテナの作り方「Dockerは裏方で何をしているのか?」
コンテナの作り方「Dockerは裏方で何をしているのか?」
PlaySQLAlchemy: SQLAlchemy入門
PlaySQLAlchemy: SQLAlchemy入門
分散トレーシング技術について(Open tracingやjaeger)
分散トレーシング技術について(Open tracingやjaeger)
シリコンバレーの「何が」凄いのか
シリコンバレーの「何が」凄いのか
Guide To AGPL
Guide To AGPL
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
Apache Airflow入門 (マーケティングデータ分析基盤技術勉強会)
KeycloakでAPI認可に入門する
KeycloakでAPI認可に入門する
人生がときめくAPIテスト自動化 with Karate
人生がときめくAPIテスト自動化 with Karate
Kubernetesのしくみ やさしく学ぶ 内部構造とアーキテクチャー
Kubernetesのしくみ やさしく学ぶ 内部構造とアーキテクチャー
40歳過ぎてもエンジニアでいるためにやっていること
40歳過ぎてもエンジニアでいるためにやっていること
Google Cloud で実践する SRE
Google Cloud で実践する SRE
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
AWSとオンプレミスを繋ぐときに知っておきたいルーティングの基礎知識(CCSI監修!)
開発速度が速い #とは(LayerX社内資料)
開発速度が速い #とは(LayerX社内資料)
PostgreSQLのロール管理とその注意点(Open Source Conference 2022 Online/Osaka 発表資料)
PostgreSQLのロール管理とその注意点(Open Source Conference 2022 Online/Osaka 発表資料)
backlogsでもCI/CDする夢を見る
backlogsでもCI/CDする夢を見る
Azure Api Management 俺的マニュアル 2020年3月版
Azure Api Management 俺的マニュアル 2020年3月版
フロー効率性とリソース効率性について #xpjug
フロー効率性とリソース効率性について #xpjug
PostgreSQLをKubernetes上で活用するためのOperator紹介!(Cloud Native Database Meetup #3 発表資料)
PostgreSQLをKubernetes上で活用するためのOperator紹介!(Cloud Native Database Meetup #3 発表資料)
マルチテナント化で知っておきたいデータベースのこと
マルチテナント化で知っておきたいデータベースのこと
組織にテストを書く文化を根付かせる戦略と戦術
組織にテストを書く文化を根付かせる戦略と戦術
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