본문
WhaTap Monitoring
ソースコードのように文書を管理する
관련링크
WhaTapのモニタリングサービスは非常に迅速なサイクルで修正と更新されます。そして、この過程で関連情報と更新履歴を文書として反映して配布することはサービスプロバイダとして必須です。
現状と問題
多くの開発者はバグ修正や機能の追加を楽しんでいますが、このような変更履歴をドキュメントとして配布するのは面倒だと言ってます。これは開発者だけでなく、プリセールスとコンサルティングを担当する私も同じだと思います。そして、文書を作成する過程自体が面倒で不便であるため、顧客支援や開発に比べて優先順位を低くする傾向がありました。
従来使用していた手順です。
① 機能の追加またはバグ修正
② ホームページブログにリリースノート
③ MS Wordにコンテンツを追加する
④ MS Word文書をPDFに変換してホームページに開始するか、顧客に配信
履歴管理の欠如
" Wordで作成して共有ドライブにアップロードしましたが、最終反映ができませんでした。“
” 今回、お客様がお問い合わせいただいた内容を文書どこか見たようですが見つかりませんでした。”
欠漏
” 作業してドキュメントにはまだ更新していないものがあったようですが、忘れてしまいました”
” 文書の仕事は次に運転する必要があります。”
読みやすさの問題
文書の枠組みをしっかりと保持しているにもかかわらず、修正されるたびにフォント、文字サイズ、並べ替えがそれぞれです。 大々的に手を見ておくと数日でまたひねります。
修正の問題
” オプションのデフォルト値を変更しましたが、どこにどこの文書に反映するのかわかりません。”
希望
誰が、いつ、なぜ、何を変えたのか知りたかったです。誰も信じていないのではなく、毎回担当者を訪ねて聞いてみるのに時間がかかりすぎました。ソースコードはgit commitの履歴を見ると簡単にわかりましたが、ドキュメントはそうではありませんでした。
最新本を見つけるために共有ドライブを探して迷い、pdfに変換してホームページにアップロードし、顧客に添付して配信するなどの消耗的な作業を減らしたいと思いました。実際、コンテンツを作成するよりもこのような付随的なことにもっと時間がかかったので、ぜひ変えてみたいと思いました。
文書に反映する過程が煩わしいので、運転しようとし、この渦中にタイミングを逃すことになれば、しばらくしてから文書に反映されるか、さらには欠けてしまいます。実際、最新版なのか不愉快なそれぞれのワードファイルを開いて修正し、再び日付を変更して保存してアップロードする過程もとても消耗的でした。
トラブル解決の糸口：Docs as Code
ソースコードを管理するように文書を管理しようという概念としてDocs as Codeがあります。これに含まれるものは次のとおりです。
- 問題の追跡
- バージョン管理
- テキストベース
- コードレビュー
- 自動化されたテスト
文書化で発生する問題を解決するために、Docs as Codeという概念があることがわかりました。これで一本の光を見ましたが、WhaTapが必要なお客様に提供される「リリースノート」、「サービスガイド」などの文書に適用する事例を見つけるのは大変でした。
私たちが望むところはDocs as Codeの定義と若干の違いがありますが、それでも必要な機能を組み合わせれば十分に実装できると思いました。
最終的には、次の内容を適用することにしました。
- コラボレーション
- バージョン管理
- テキストベース
- OSMU(One source multi-use)
- CI(Continuous Integration)
適用プロセス
ツールの選択
コードを書くような文書を書くためには、WYSIWYG 以外のテキストベースの編集ツールが必要でした。WIKIもありMarkDownもありますが、次の理由でAsciidoctorを選択しました。
① MarkDown より多様な文法がある。
② Gitのようなリポジトリを使用することができ、共同作業が可能です。
③ 結果物を HTML、PDF など、さまざまな形に変換することができる。
④ 結果物のテーマを編集し、希望の形で出力物のデザインが可能。
⑤ 文書内で他の文書を呼び出すことができるインクルードタグをサポートします。
⑥ maven、gradleなどを使ってビルドできるプラグインを提供する。
文書変換
最も時間のかかる部分は、既存のワード文書をAsciidoctor文書に変換するプロセスでした。
pandoc を使って一次変換しましたが、表、イメージのように仕方なく人の手を経なければならない部分が生じるしかありませんでした。さまざまな方法をテストしてみましたが、事実上完全な自動変換は難しいことを認識し、文法に慣れるために使用ガイドを参照して既存の文書を大々的に変換しました。
https://asciidoctor.org/docs/user-manual/
ストレージの設定と環境設定
TextベースのAsciidoctorを選択すると、形状管理が非常に単純になりました。単にGitにドキュメント用のリポジトリを1つ構成し、変換した初期ドキュメントをCommitしました。 後で作成するために、使用しているIDEにpreviewプラグインをインストールしました。
Asciidoctorは、Eclipse、VSCODE、IntelliJなど、使用している開発環境でPreviewを見ることができるプラグインをサポートしているため、ワードで書くときなど、別々のアプリケーションを実行する必要がなくなりました。
https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
ビルドスクリプトの作成
作成した文書をhtml、pdfにするためのmavenビルドスクリプトを作成しました。これにより、展開まで自動化できる環境が用意されました。
AsciidoctorにはGradle、Maven、さらにはANTで結果を自動ビルドできるプラグインを提供します。
https://asciidoctor.org/docs/asciidoctor-gradle-plugin/
https://asciidoctor.org/docs/asciidoctor-maven-plugin/
https://github.com/asciidoctor/asciidoctor-ant
デザイン
html, pdf 文書の見た目をデザインしました。WhaTapの能力あるデザイナーが見事に作ってくれました。
https://asciidoctor.org/docsproduce-custom-themes-using-asciidoctor-stylesheet-factory/
https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc
展開の自動化
信頼できるJenkinsさんなんといっても配布と言えば、Jenkinsです。
文書をhtml、pdfでビルドし、共有ドライブにコピーし、ホームページに配布する一連の作業はJenkinsに任せておきます。Jenkinsのビルドプロセスで社内共有ドライブにアップロードすることは、rcloneを使用して簡単に実装しました。
変更された外観
Asciidoctor文法に適応するいくつかの手間をしたら、ワードで作業するときに経験した問題が消えました。
一括修正
探して修正してCommit文書が100 個でも1000 個でも内容を探すことはエディタが代わりにしてくれます。日付を追加したり、タイトルを変更して再保存することはありません。
変更履歴管理
さて、リリースノートだけを見たら製品がどのように変わったかがわかります。ブログ、共有ドライブを行き来して作業する必要がないため、ドキュメントは着実に更新されます。
どのドキュメントが追加され、何が変更され、いつ配布されたかは、Jenkinsのビルド履歴を見ると出てきます。
どのような内容がどのように変更されたかは、Git Commit履歴でdiffと比較できます。
文書配布の自動化
作成/修正した文書をCommitすると、共有ドライブのアップロード、ホームページの配布などの一連のプロセスはJenkinsが行います。
心配することなく、共有ドライブにある文書が最新のビルドされた最新版です。
ホームページも常に最近配布された最新本です。
文書の読みやすさ
ドキュメントテンプレートはプロのデザイナーによって作成されました。書く人はコンテンツだけ悩んでください。もはや文書の見た目のために心配しません。
htmlで提供されるオンライン文書はcss、javascriptまで適用でき、デザイナーの方がナビゲーションバーとレスポンシブUIまで適用してくれました。
PDFもデザイナー作品です。フォントに非常に気を遣いました。デザイナーに真剣に「イタリックでもハングルは傾けるのは良くありませんよ」と教えていただきました。
まとめ
Docs as Codeの概念を活用して文書作成プロセスを変えた後、不便だった点を解消し、望む姿を成し遂げることができました。
おかげで、WhaTapモニタリングサービスを開始または使用する過程で、お客様にお問い合わせいただいた内容は、従来と比較できないほど迅速に文書に反映されています。 WhaTap使用ガイドがそのように管理されています。
お客様から[email protected]にいただいたご質問は、以前と同様に大切に管理しています。そして、プリセールスコンサルタントとして最も気に入っていることは、顧客の質問に文書を補完し、追加して説明リンクと一緒に答えることができるということです。
