こんにちは、CRE部 技術支援チームです。
今回は幣チームが企画/運用しているニフクラのSEハンドブックをGitLabなどのツールを駆使してWebコンテンツ化し、運用している様子をレポートします。
DevOpsとかGitLabってコード開発するエンジニアさんの話でしょ？と思われた方
弊チームは開発業務をメインとしているチームではないため、開発エンジニアではない営業などのビジネス部門の方でも、ドキュメントの更新管理の効率化に応用可能と思います。
背景
私たちCRE部 技術支援チームは、普段ニフクラ商談の技術支援(顧客要件に対して構成をどうしたらよいか？等)や、ニフクラのご利用者様(主にSE様)向けにSEハンドブック、クラウドデザインパターンなどの情報提供を行っております。
その中で、SEハンドブックは、ニフクラでシステムを構築する方向けに構築時のポイントを解説したハンドブックです。SEハンドブックは以下のような特性があります。
- 自動的に生成されるものではなく、手動による更新が必要
- サービス仕様の改変が頻繁にあるため、常時更新する必要がある
- チーム内で同一ファイルへの共同編集作業が発生する
- 読者がより読みやすく、誤解しづらい内容になっているかを確認するために、複数人のレビュー/承認が必要
みなさんにもこれらの特性をもったドキュメント(マニュアルやホワイトペーパーなど)の更新/運用/管理で苦労しているということはないでしょうか。
SEハンドブックの運用でも、更新作業に多大な工数がかかるためタイムリーな更新ができていない、属人化している作業があるなど多くの問題を抱えていました。課題の改善に向けて活動を始めて、無事2022年4月にまずはWebコンテンツとしてリリースすることができました。
本プロジェクト実施にあたっての苦労点や、運用がどう効率化されたかをご覧いただくことで、非開発エンジニアの方でもGitLabを活用できることを理解していただければ幸いです。
はじめに
突然ですが、ソフトウェア開発手法のDevOpsはご存じでしょうか。
開発担当と運用担当が緊密に連携して、柔軟かつスピーディーにシステム開発を行う手法です。
ただ、コードを利用するエンジニア以外は、何が具体的によくなるのか不明瞭な部分も多々あるかと思います。(今執筆している私がそうでした。)
弊社でもGitLabが導入されており、全社員アカウントが付与されていますが、チームタスクの管理としてissue、boardなどを利用してはいたものの、他の機能はあまり使っていない状況でした。
チームとして限定的な活用にとどまっている状況ながらも、DevOps with GitLabも弊チームのミッションとして商談支援の対象となっていましたが、コードを利用してサービスを開発/運用するようなエンジニアではないこともあり、商談時にその有用性を自身の言葉で語るには至りませんでした。
そんな中、背景で述べたSEハンドブックのWeb化/運用効率化について様々な下調べを実施する中で、Gitlabの機能を活用することでこれまでの課題を改善出来る可能性が見えてきました。
そこで、SEハンドブックの更新運用をGitLabで実施する仕組みを整えることで、SEハンドブックの運用効率を向上しつつ、DevOpsへの知見を高めることができないかと考え、実施することになりました。
従来の運用と問題
従来の運用では問題が発生する要因が大きく3つありました。
- A エンハンス情報の管理方法により発生する問題
- B パワーポイントで運用することにより発生する問題
- C PDFで公開していることによる問題
A エンハンス情報の管理方法により発生する問題
エンハンス情報をとりまとめたエクセルシートを作っており、各エンハンス情報(別途エンハンス情報の詳細を用意)を確認して修正対応していました。
この方式では、以下のような問題がありました。
- 問題A-①. エンハンス情報がわかりづらい
- エンハンス情報をエクセルシートに一覧化しているのですが、エンハンス内容へのリンク集となってしまっており、実際の修正内容は別途確認する必要がありました。また、修正予定内容のレビューができていませんでした。
- 問題A-②. 修正、レビューの状況/対応関係がわかりにくい
- 修正について進捗状況の確認ができず、また、どのエンハンス内容に紐付いたSEハンドブックの修正レビューなのかがわかりませんでした。
- 問題A-③. SEハンドブックへの反映要/不要がとりまとめ者の判断に依存しており、承認の形跡が残せていない
- エンハンス内容内容によってはSEハンドブックへの反映が不要なものがあるが、属人的なスキルに依存しており、チームとして判断ができていませんでした。
B パワーポイントで運用することにより発生する問題
エンハンス情報を把握し、それぞれ直接パワーポイントのファイルを修正して、パワーポイントのコメント機能で修正履歴を残す形で運用していました。
この方式では、以下のような問題がありました。
- 問題B-①. 修正個所の特定にかかる工数が大きい
- パワーポイントが17ファイル、合計850スライドもあり、修正個所の特定に非常に工数がかかっていました。
- 問題B-②. 修正内容の確認に非常に手間がかかる
- 修正前後で比較するのに2つのドキュメントを並べる等の工夫が必要であり、大きな手間となっていました。
- 問題B-③. 修正内容を残す方法がコメント機能程度しかない
- 修正内容の確認をコメント機能に依存しているため、修正担当とレビュアーにて相互に確認、指摘することに手間がかかっていました。
- 問題B-④. 他に修正が必要な個所がないかの横展開確認が大変
- パワーポイント内部を横断的に検索する仕組みが整っておらず、一つの修正が与える他の修正個所の特定に非常に工数がかかっていました。
- 問題B-⑤. 時折発生するパワーポイントテンプレート変更への追従対応
- 2015年にSEハンドブックをリリースしてから4回、全体のフォーマット変更が入り、都度修正の手間がかかっていました。
- 課題B-⑥. 作業が直列にしか実施できない
- 一つの修正対応中は、デザイン変更などの内容としては並行で実施できるような内容でも作業ができず、前の修正が完了するまで別の作業が滞留してしまうことが多々ありました。
また、並行して実施している修正について、マージ漏れなどが発生し、記載内容がデグレードすることもありました。
- 一つの修正対応中は、デザイン変更などの内容としては並行で実施できるような内容でも作業ができず、前の修正が完了するまで別の作業が滞留してしまうことが多々ありました。
C PDFで公開していることによる問題
Web化前にもPDFにて一般公開を実施していました。
この方式では、以下のような問題がありました。
- 問題C-①. 検索性が悪い
- Web検索でSEハンドブックにたどり着いても、PDFファイルが開いてしまうため、目的の情報にたどり着くまでに何ページもめくる必要がありました。
- 問題C-②. 商談対応での利用時に、ドキュメント中の場所を指しにくい
- 上記問題と同じ理由により、ドキュメント中の特定の個所に記載してある内容を案内することが難しい状況でした。
新しい運用の紹介
新しい運用方法の紹介と先にあげた問題をどう改善できているのかをご紹介します。
本ブログ記事ではGitLabについて、ブランチ、マージ、コンフリクトなどの用語がでてきます。
本ブログ記事内でそれぞれについて詳細を解説しておりません。
GitLabについてはブログ：【レポート】第21回ニフクラ エンジニア ミートアップ「今さら聞けない人のためのgit超入門」も参考にしてください。
エンハンス情報の管理方法の改善
エンハンス内容および、修正、レビューの状況/対応関係を明確化するために、エンハンスごとにissueを作成することにし、記載する内容を決めました。(問題A-①、A-②の改善)
issueに記載するべき内容は以下と定義しました。（問題A-①、③の改善）
- 修正対象のサービス
- エンハンス情報へのリンク
- エンハンス情報の詳細
- 修正対象となるページ名(後ほどのレビューで実施)
SEハンドブックへの反映要/不要の改善
SEハンドブックへの反映要/不要について、チームレビューのフローを取り入れました。(問題A-③の改善)
- SEハンドブックへの反映作業開始時期が来たら、issueの整理を開始
- SEハンドブックへ反映する必要があるか無いかの確認作業を分散して実施
- 上記判断について、チームとしてレビューを実施し、最終判定。判断結果をissueへ証跡として残す
修正フローの整備/改善
修正作業を下記フローすることで、個別の修正内容の明確化、修正漏れの防止および作業内容の反映の証跡確保を実施しました。
(問題B-①、③の一部改善)
また、CI/CDを取り入れることで、コンテンツの自動更新を実現しました！
- 各issueに修正作業者を割り振る
- 割り振られた担当者は修正ページ、修正内容を整理、検討
- 修正内容を相互チェックし、より適切な範囲、内容にブラッシュアップ。修正対象ページをissueに追記する
- レビュー結果を受けて、個別に修正用ブランチを作成し、修正作業を実施
- 修正作業の結果をレビュー用ブランチへのマージリクエストの形で承認依頼
- 承認されると、自動的にWebページが自動生成され、開発用環境に反映を実施
- 一通りの修正が完了したら、レビュー用ブランチから公開確認用ブランチへのマージリクエストを発行
- 承認されると、自動的にチェック用Webページが自動生成され、チェック用環境に反映を実施
- チェック用環境レビュー者は、マージリクエストとチェック用Webページを参考に最終チェックし、本番環境用ブランチへのマージリクエストを発行
- 最終レビュー者が承認すると、自動的に本番環境 へ公開作業を実施！！
ドキュメントレビュー方法の改善
ドキュメントレビューを、レビュー用ブランチへのマージリクエストとして運用することで、修正前後の差分確認、修正内容の確認が容易となりました。(問題B-②～④の改善)
- 修正完了次第、マージリクエストにてレビュー依頼を出す
マージリクエスト例 - レビュアーは以下の通りレビューを実施
- マージリクエストから修正前後の差分を確認
GitLabでの修正差分確認 - GitLabの機能を用いて指摘個所に直接コメントを記載
GitLab上でレビュー/指摘 - 他に修正が必要な個所がないか横展開確認の実施
- チェック用環境にデプロイされたWebページを用いて、Webページの表記確認
- マージリクエストから修正前後の差分を確認
- 担当者は指摘を確認し、修正を実施。その際指摘に対して絵文字などで対応済みを示すことで修正漏れの確認を実施
並列作業性の向上
GitLabで運用することにより、エンハンス修正と並行してその他の改版作業を行うことが容易となりました。(問題B-⑥の改善)
- 修正個所が必ず一カ所に集まることにより、マージ作業によるマージ漏れの防止
- 修正の競合が発生した際のルールを策定しておくことにより、デグレードを抑止
GitLab上コンフリクト発生例
幣チームでは後からマージリクエストを発行した修正にてコンフリクトを解消するルールとしました。対応方針は以下の通りです。
- レビュアーがコンフリクトを確認したら、担当者にコンフリクトが発生している旨を通知
コンフリクト発生 - 担当者が必要個所の修正個所を反映しコンフリクトを解消
コンフリクト解消イメージ
実際パワーポイント運用時にはデグレードが結構な頻度で発生していたのですが、本運用にしてからはデグレードの発生がおさえられています！
【余談】パワーポイントファイルをasciidocに変換した方法
(本筋から外れますが、かなり苦労したので書かせてください。)
パワーポイントからasciidocへの変換は、以下のように実施しました。
(もっとうまいやり方もあるかもしれませんが、一例として参考までに)
- フッターの削除や構成図として作成したものを画像化するなどの前作業を実施
下記で利用するツールは、パワーポイント上でのオブジェクトを個別に画像化してしまうため、1枚の画像にしたいものを画像に変換しました。 - pptx2mdを利用して、パワーポイントから一度markdownファイルに変換
ツールの特性として、インデントを無視する、数字の箇条書きが反映されない等があります。
その中でも、表がすべて無視されてしまうのは一番大きな困りポイントでした。
SEハンドブックは表が主といっていいくらい表が多いドキュメントだったため、この特性は後の作業量に大きな影響を与えました。 - pandocを利用してmarkdownからasciidocに変換
このツールも、困った特性があり、参照していた画像が無視されてしました。 - 出来上がったasciidocファイルを各自の地道な作業とツールを駆使して、元のSEハンドブックと同じように仕立てる
人海戦術で実施せざるを得ない状況で、ここが一番大変でした- pptx2mdにより消えてしまったtableの作成、インデントの調整を実施
- pandocにより消えてしまった画像の復元を実施
asciidocで運用することにより網羅的に検索することが可能となり問題B-④を改善、また、パワーポイントのフォーマットに依存することがなくなったため問題B-⑤が改善できました。
- 補足情報
最終的に運用するドキュメントとしてasciidocを選択した理由ですが、tableを柔軟に操作できたためです。 SEハンドブックは表がかなり多く、表を正確に表現するのにasciidocが最良と判断しました。
今回の対応の効果
利用者数向上
PV数が約3倍と大幅に向上しました！！
- 従来のPDF公開期間 2021/7～2021/9：約1,800PV
- 新規Webページ 2022/4～6：約7,000PV
以下のような理由にて、PV数が向上していると考えています！
- Webページかつ目次対応ができたので、検索後目的のページにたどり着きやすくなった (問題C-①の改善)
- 商談対応や問い合わせ対応時など必要個所、章のURLを共有することができるようになり、開いてもらえやすくなった(問題C-②の改善)
- 単純にPDFよりも視覚的に見やすく、閲覧しやすくなった
運用負荷の軽減
運用負荷が大きく下がりました！！
- 修正内容のマージ漏れがなくなり、再編集作業が0に！
- 修正内容レビュー時に、変更個所を探す作業が0に！！
- 修正対象個所を探す時間が、約1/3に！！
- 公開作業が自動化されたために、他部署にしていた依頼作業が0に！！
チームメンバーの知識向上
GitLab、バージョン管理システムに関してチームメンバーの知識が向上しました！！
- メンバーのGitLabへの慣れ
幣チームのミッションでもある商談支援対象の「DevOps with GitLab」への理解促進が進んだと考えています！！ - バージョン管理システムの理解
ブランチ、マージなどの単語が指す意味、行為が実体験を通じて理解できるようになりました！
商談技術支援というチームにいるため、パワーポイントで説明資料を作ることが多く、執筆者自身は開発者の苦労等に疎かった部分がありました。
ただ体験してみると(まだ序の口ですが)、コード開発者は確かにGitLab等ツールが導入できれば楽になるのだと体感することができました。
今後の展望
修正工数、レビュー工数が削減されたため、より鮮度の高い情報を提供できるよう更新サイクルの短縮化を考えています。最終的には月1更新を目指しています！！
また、現状はパワーポイントコンテンツをWebページとして変換しただけになっており、Webページに合わせた形になっていないと考えています（特定のページだけ異常にページが長く読みにくいなど）。更に見やすく・欲しい情報にたどり着きやすく（検索性の向上）するようブラッシュアップを実施します！！
今回の経験を生かし、 クラウドデザインパターンなど幣チームで運用している他のドキュメントについても、SEハンドブックの運用を横展開していきます！！
さいごに
いかがでしょうか。
本ブログで紹介させていただいたようにGitLab等のツールはドキュメントの効率的な更新/運用管理にも利用できます。
開発エンジニアではない営業などのビジネス部門の方でドキュメントの更新管理に悩まれている方や、開発エンジニアの方ですでに利用されていて社内にGitLabを流布したい方、今回の記事を参考にしていただければ幸いです。
また、そこのGitLabのご利用を検討されている方！！ニフクラからご利用いただけますよ！！！
- DevOps with GitLab
DevOps with GitLabはプライベートなAll-in-one DevOps環境（GitLab）が簡単に構築・利用いただけるサービスです。 - GitLab Enterprise Edition サブスクリプションの利用
ニフクラ上でご利用の GitLab Enterprise Edition(GitLab EE) のセルフホスト型のPremiumライセンス、Ultimateライセンスをご提供します。DevOps with GitLab との組合せが可能です｡ - GitLab Enterprise Edition ライセンスの利用
汎用的な GitLab Enterprise Edition(GitLab EE) のセルフホスト型のPremiumライセンス、Ultimateライセンスをご提供します。お客様のオンプレ環境にも､ご利用いただけます。
注意事項
- 本記事に記載されている会社名、製品名等の固有名詞は各社の商号、登録商標または商標です。
- 本記事の他社サイトへのリンクにつきまして、リンク切れの際はご容赦ください。
- 本記事は、2022年6月時点の情報です。
