Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
文書作成ソフトからの脱却 ~Markdownによるアラート対応手順書CI/CD~
Search
Kei Terui
June 23, 2022
Business
0
2.4k
文書作成ソフトからの脱却 ~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
『Policy Fund』採択団体 政策提言集/Policy Fund Report
polipoli
0
460
DMM.com アルファ室採用案内資料
dmmcom2025
0
350
c-slide_サービス紹介資料テンプレート
coneinc
0
630
Cursor活用ガイド(非エンジニア向け)
satoyusuke
0
180
アッテル会社紹介資料/culture deck
attelu
10
15k
ChillStack会社紹介資料
chillstack
0
400
AIUX is Agentic UX
kan
0
280
【2025年度】大会協賛提案書
jusdl
0
310
株式会社D2C ID 会社案内 / recruit
d2cid
2
4.4k
LW_brochure_business
lincwellhr
1
59k
AWS Summit Japan 2025 社内コミュニティによる企業文化創り ~MAWS-UGの挑戦とこれから~
yukiogawa
2
840
ラクスパートナーズ採用ピッチ資料_エンジニア部門.pdf
rakuspartners_recruit
0
24k
Featured
See All Featured
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
35
2.4k
Making the Leap to Tech Lead
cromwellryan
134
9.4k
Thoughts on Productivity
jonyablonski
69
4.7k
[RailsConf 2023 Opening Keynote] The Magic of Rails
eileencodes
29
9.5k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
357
30k
Six Lessons from altMBA
skipperchong
28
3.9k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
138
34k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.7k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3.3k
A Modern Web Designer's Workflow
chriscoyier
694
190k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
PRO
181
53k
Visualization
eitanlees
146
16k
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 ご清聴頂きありがとうございました🙇