Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~
Kei Terui
June 23, 2022
Business
0
150
文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~
Cloud Operator Days Tokyo 2022
文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~
Kei Terui
June 23, 2022
Tweet
Share
Other Decks in Business
See All in Business
キュエル株式会社 採用説明資料
yosukeito
0
130
kaonavi Future Deck
kaonavi
6
54k
会社説明資料_Srush
kaihiguchi
1
270
アジャイルを支える心理的安全性の守破離 / Psychological safety for Agile
radiocat
0
170
AniCure動物病院/株式会社 紹介資料
anicure
0
290
【トランスミット】会社紹介/about transmit
transmit
1
370
culture deck(2022)
sixtypercent
0
640
リンクアンドモチベーション 営業コンサルタント向け紹介資料 / Introduction to Link and Motivation for Sales and Consultants
lmi
0
1.7k
Think Bic. for Social
takayuki_emura
0
220
アッテル会社紹介資料/culture deck
attelu
6
2.6k
Business Introduction
genialtech
0
130
teamLab Saiyo Deck
teamlab
PRO
2
390
Featured
See All Featured
Happy Clients
brianwarren
89
5.6k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
655
120k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
19
1.4k
The Invisible Customer
myddelton
110
11k
The Web Native Designer (August 2011)
paulrobertlloyd
74
1.9k
VelocityConf: Rendering Performance Case Studies
addyosmani
316
22k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
226
15k
What’s in a name? Adding method to the madness
productmarketing
11
1.6k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
349
27k
Raft: Consensus for Rubyists
vanstee
126
5.4k
Code Reviewing Like a Champion
maltzj
506
37k
GitHub's CSS Performance
jonrohan
1020
420k
Transcript
1 1 文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~ 株式会社ハートビーツ MSP事業部 照井 渓(@teru_kei) 2022/05
@ CODT2022
2 2 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
3 3 自己紹介 • Terui Kei / 照井 渓 –
@teru_kei • 株式会社ハートビーツ – 2020年11月 入社 – MSP事業部 エンジニアリンググループ
4 4 株式会社ハートビーツ • 2005年創業 • 80名規模、エンジニア率80%以上 – MSP事業 •
インフラ運用のアウトソーサー • 監視、設計、構築 • クラウド導入支援、コンサルティング – 開発事業
5 5 ご紹介:MSP事業 提供サービス ★ 監視一次対応サービス ★ マネージドサービス
6 6 ご紹介:MSP事業 提供サービス ★ 監視一次対応サービス ★ マネージドサービス 「監視仕様書」
を作成・提供
7 7 ご紹介:監視仕様書って? ❖ 下記のような内容の文書 ▪ アラート対応手順 ▪ アラート発生時の対応フロー ▪
監視対象のサーバ・リソースの一覧 ▪ 監視項目の一覧 ▪ 弊社・お客様の連絡窓口情報 ▪ ネットワーク・アプリケーションの構成図 などなど
8 8 お詫び:本セッションの題名について 文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~ と題名をつけておりますが…… 実際には「アラート対応手順書」を内包している、 「監視仕様書」の CI/CD についてお話します🙇
9 9 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
10 10 監視仕様書が 自動生成されるようになって 最高 結論
11 11 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
12 12 動機1 • 以前は、監視仕様書をWordで作成していた – 全て手作業で対応する為、作成・更新が大変 • 新規作成の際はテンプレートから手入力で作成 •
Wordはコード化が難しく、自動化しづらい
13 13 動機2 • 以前は、監視仕様書をWordで作成していた – OSに依存なく編集可能にしたい • ハートビーツでは、社員の端末OS選択が自由 •
WordはWindowsに最適化されている • Mac/Linux環境でフォーマットが崩れる問題
14 14 動機3 • 以前は、監視仕様書をWordで作成していた – バックアップ運用をやめ、バージョン管理したい • バックアップファイルが共有ドライブを圧迫 •
更新履歴を目で追うのが大変 – diff でチェックできるようにしたい
15 15 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
16 16 実現に向けた動き • 社内GitLab上にあるプロジェクト「hb-zatsu」 – みんなで「雑なアイデアを共有する場」として存在 – Issueに仕様書手書き作成の辛さが書き込まれる –
30環境同時受注が発生、手作業での限界感強まる • 有志6名によるタスクフォースチーム結成
17 17 実現に向けた動き • 目標:手作業によるWord文書更新から脱却する! – Markdown で書いて Git で管理したい
– Word仕様書に遜色ない内容で PDF 出力したい • 2ヶ月程でMarkdown仕様書生成システムを作成 • 半年ほどかけて半自動生成の機能が追加され完成
18 18 Markdown仕様書生成システム名 Kinjiro
19 19 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
20 20 使用ツール ➔ Markdown ➔ Gitlab ◆ Gitlab CI/CD
➔ Docker ➔ Mkdocs ◆ HEARTBEATS Flavored Markdown extension(hbfm) ➔ wkhtmltopdf ➔ Jenkins
21 21 CI/CD ワークフロー図
22 22 CI/CD ワークフロー図 HTMLライブプレビューを 見ながら Markdownを書く GitにpushされるとGitLab CIが発動 Docker上でビルドが実行され
PDFが生成される JenkinsをKick PDFを Google Driveにデプロイ
23 23 再掲:監視仕様書って? ❖ 下記のような内容の文書 ▪ アラート対応手順 ▪ アラート発生時の対応フロー ▪
監視対象のサーバ・リソースの一覧 ▪ 監視項目の一覧 ▪ 弊社・お客様の連絡窓口情報 ▪ ネットワーク・アプリケーションの構成図 などなど
24 24 再掲:監視仕様書って? ❖ 下記のような内容の文書 ▪ アラート対応手順 ▪ アラート発生時の対応フロー ▪
監視対象のサーバ・リソースの一覧 ▪ 監視項目の一覧 ▪ 弊社・お客様の連絡窓口情報 ▪ ネットワーク・アプリケーションの構成図 などなど 脱Wordしたけど Markdownの 手書きも大変! 自動生成したい!
25 25 仕様書自動生成システム名 Kinjiro Generator
26 26 Kinjiro Generator のざっくりした仕組み 1. 案件コードをフォームに入力 2. 必要なアラート対応手順をチェックボックスで選択 3.
生成ボタンを押下 4. 案件データベースと監視ツールAPIから情報取得 5. 監視対象サーバと監視項目の一覧を取得 6. 監視仕様書全体のMarkdownが生成される
27 27 Kinjiro Generator の WebUI の様子 OSやミドルウェアを選択するだけでMarkdownが生 成できる!!
28 28 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
29 29 ビフォーアフター Before After フォーマット Word Markdown 新規作成
テンプレートを複製 大半を自動生成 更新方法 共有ドライブ上で更新 gitにpush 更新管理 バックアップ堆積 gitでバージョン管理 書面のPDF化 保存時にPDFを選択 CI/CDで自動生成 つらい 最高
30 30 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
31 31 苦労話 ★ 当初のPDFは、かなり寂しい見た目をしていた ◦ Wordに遜色ない表現力を持たせるのに苦労した ◦ 「Markdown文書」と「出力されるPDF」の乖離 ◦
Wordの偉大さも改めて感じた
32 32 苦労話 ★ 地道な調整によって見た目を整えていった ◦ Mkdocsを使用してhtmlの表現力を借りる ▪ css調整、改ページのルール作成 etc…
▪ その中で hbfm が産まれた
33 33 表現力アップのために ★ HEARTBEATS Flavored Markdown extension(hbfm) ◦ 弊社ハートビーツにて作成
◦ Markdown 側で使用可能な記法を追加 ◦ Mkdocs に組み込んで使用 ◦ GitHub、PyPI で公開
34 34 表現力アップのために ★ HEARTBEATS Flavored Markdown extension(hbfm) ◦
文字色指定 機能 ◦ 相互参照 機能 ◦ 表内リスト 機能
35 35 表現力アップのために ★ hbfmは何故必要だったか? ◦ お客様にとっての可読性向上 ◦ 運用チームにとっての可読性向上 ▪
運用チームは監視仕様書を手順書として使う ▪ 作業ミスを起こさない為にも可読性は大切
36 36 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
37 37 監視仕様書が 自動生成されるようになって 最高 結論
38 38 あらゆるドキュメントが 自動生成されるようになれば いいのに 結論
39 39 文書作成ソフトからの脱却 アジェンダ 1. 自己紹介 2. 結論 3. 動機
4. 実現に向けた動き 5. 仕組み 6. ビフォーアフター 7. 苦労話 8. 再度結論 9. おわりに
40 40 おわりに 紹介した事例についてご興味ある方は 弊社ハートビーツまでお問い合わせください🤝 ★ HEARTBEATS Flavored Markdown
extension 公開中 ◦ https://github.com/heartbeatsjp/markdown-extension-hbfm
41 41 ご清聴頂きありがとうございました🙇