📂

ドキュメント管理をGitHubに変更したお話

2023/12/18に公開

GitHub

この記事について

この記事は SUPER STUDIO Advent Calendar 2023 の18日目の記事です。

弊社のアドベントカレンダーは開発・運用職のメンバーが中心となって書いていますが、私の場合は職種が異なり「他社カートから弊社カートへお引越しいただくEC事業者さまの移行プロジェクトを円滑に進めるためのお仕事（いわゆるプロジェクトマネージャー）」を担当しています。
そのためちょっぴり毛色が違う話題になるかもしれませんが、よろしければお付き合いください。

そもそものはじまり

私が所属している SUPER STUDIOでは統合ECプラットフォーム「ecforce」を運営し、約1200ショップ以上のEC事業者さまに導入いただいています。(2023年11月現在)

ecforce に限らず、ECカートシステムはそれなりに複雑です。
なぜならばEC、とりわけD2Cと呼ばれる領域は「購入者さんに自社の製品を届ける」という目的のために、さまざまな流れで幅広い作業を実施する必要があるからです。

EC事業者さまの作業例（一部抜粋）長くなるのでたたみます。

自社の製品を知ってもらう（ブランディング・広告など）
訪れた方に購入してもらう
- 商品ページ/ランディングページの制作
- 購入フォームやチャットボットなどストレスなく購入いただくための設計
- 決済手段の提供
- ＋αの引き上げ施策（クロスセル・アップセル施策）の検討
- 分析や広告の成果通知のためのタグ（JSなど）の設計や挿入
注文内容をもとに、倉庫さんや自社倉庫から商品を出荷する。
- 注文した商品だけではなく、一緒に発送する商品以外のモノも出荷担当者が正確にピッキングできるようにする。よくある事例として以下があげられます。
  - ブランディングの一貫として初回のお客様にはブランドブックを同梱する。
  - 顧客や（サブスクリプション商品の場合）購入回数に応じたプレゼントなどを同梱する。
  - 最近は環境負荷を考えサブスクリプション商品の場合、通常は詰替え用のパウチで提供する事例が多いです。その場合、初回の配送をボトルにする、5回ごとに空の新しいボトルを同梱する。
  - 新製品のチラシを同梱する、など。
- 出荷の際には納品書を同梱する。
  - 決済手段が後払いの場合は、納品書と一緒に後払い請求書を同梱する。（プレゼントなど「注文者」と「お届け先」が異なる場合は、商品と同梱せずに、後日決済会社から後払い請求書を送ることもできます）
出荷完了後、以下のような処理を行う。
- 出荷日・配送伝票番号・配送方法などの情報をECカートシステムに登録する。
- 出荷完了メールを購入者に送信する。※お届け予定日・出荷日・配送方法・配送伝票番号（問い合わせ番号）などをお知らせすることが多い。
- 商品の出荷が終わったので、決済会社に対して売上請求処理を行う。（売上請求処理を実施する際に出荷日・配送方法・配送伝票番号の情報がセットで必要な決済事業者もあります）
商品が手元に届いてからの顧客とのコネクションを構築する。
さらにブランドを愛してもらえるような施策を計画・実施する。
お客様からの問い合わせのチャネルを設計し、お客様へ十分な対応ができるようにする。
- 電話・メール、最近はLINEでお問い合わせができる事業者さまも増えている印象です。
- コールセンターを外部に委託する場合、対応件数に応じた費用が必要になります。次回のお届け予定日やお届け商品の追加・変更を顧客自身でも実施できるよう整えたり、チャットボットなどの自動応対システムを入れるなどの併用される事業者さまもいらっしゃいます
広告流入元や販売チャネルごとに分析をおこない、分析結果より販売戦略のブラッシュアップをおこなう
- 1注文獲得にかかる費用と、購入金額
- 来訪者が購入完了まで至る率（または実際に出荷・売上まで至る率）
- 1注文につき何回購入継続しどこで離脱するか（サブスクリプション購入の場合）

上記は私がこれまでに接してきた中で多くお聞きしてきたことを一部抜粋しただけにすぎません。
めちゃめちゃ多くないですか？
これら多岐に渡る業務を、メンバーが多い事業者さまは分担して、1人EC事業者さまはひとりで実施されています（もちろん部分的に外部に委託したり……はありますが、委託先のコントロールをしなくてはならないので業務に対して無知でいい、というわけにもいかず）

以下は弊社のCOO,CMOの共著（のAmazon ページ）なのですが、この本の説明を眺めるだけでも「ええええ、まだまだあるやん」となるかも。（クリックしてもどこにもお金は入りません）

https://www.amazon.co.jp/dp/B0CK8FX1NG/

ブランドのコンセプトやターゲットユーザー、商材によっても異なりますし、販売開始直後のショップさまと10年続けてきたショップさまとでは、これまでの知見や構築してきた業務フローなども異なります。つまり、ショップさまごとにやりたいことは異なってきます。

共通していることは「（どんなカートシステムを利用するにしても）やりたいことを実現するためには、カートシステムでさまざまな設定を実施する必要がある」ということです。
とはいえ業務範囲は広大で、かつ運用方法が多岐にわたるため、やりたいことをベースにショップさま自身で設定を実施いただくことが多いです。
そのため「不明点があればFAQから探したり、担当PMにお問い合わせいただく（場合によってはWeb会議で疑問を解消）」といった流れをショップさまにお願いしていました。

とはいえ、ありがたいことに移行プロジェクトの案件数が増え、そうなると今までのやり方だとさまざまな問題が出てきます。

その中で以下のつらみを解決することを最終的な目的として「移行用のマニュアルのドキュメントを作ろうか」という流れになりました。

PM :
担当案件数が多く、担当プロジェクトの移行日前後は移行作業中のプロジェクトに業務の大半を割くことになる。
移行作業対応中の場合、移行日が先の担当プロジェクトへのお問い合わせに対しては回答リソースを割きにくい。
そのため夜にまとめて回答するなど、業務時間が長くなってしまうつらみ。

ショップさま:
知りたいことがなかなか解決できない。（FAQ記事は多いのですが、どこから探せばよいのかわからないあるある）
すんなり解決できないので、設定や運用設計のための待ち時間が発生してしまうつらみ

とりあえず上記解決のための第一歩として「どこのFAQを確認すればよいのかへのサジェストを含んだマニュアル」の初版を2022年春につくりました。
当時はPDF形式で配布することを想定し、以下の流れで作成しました。

社内Wiki的なもの（Confluence）で大雑把な流れを書く→関係者でレビュー
Confluence / Google Document でPDF化を試したものの、そのまま配布できるような品質にできなかったため、Microsoft Word で清書
WordからPDF化

ecforceは毎月の機能リリースがあり、それまでできなかったことが突然できるようになったり、新機能が追加になったり……が多く発生するため、ページ単位で編集の必要があるGoogleスライドやPowerPointは最初から採用しませんでした。

その後の運用については「実際に運用開始してみて検討しましょう」くらいのノリではじめました。

Wordでのドキュメント運用をはじめて感じた問題

実際にWordで運用をはじめてみたところ、以下の問題点に気づきました。

問題1: 更新時のレビューが困難

Wordの変更履歴や版管理の機能をきちんと利用・利用の周知がしていない環境では、いつ・どこに・なんの変更をなんの目的で入れたのかを把握するのが難しいと感じました。
きちんとルール化できていればこの点は問題にならなかったかもしれませんが、うっかり「今あるファイルを上書き編集できちゃう」みたいなことができるので……。
これに関してはきちんと運用ルールまで考えていなかったから、ということはあるとは思います。

（でもWord の変更履歴、見にくいよ）

問題2: 複数人で手分けして編集をかけていくのが難しい

Office365 + OneDrive を使っていれば、複数ユーザによるファイルの同時編集は可能だったかも。
弊社は OneDrive をルール上で利用できず、Wordファイル自体は Googleの共有ドライブにおいて運用していました。

また、Wordでは「うっかりその辺からコピペすると同一ファイル内でフォントや文字サイズが統一されない（設定違いがぱっと見でわかりにくいからこそ、修正面倒）」という問題もありました。

問題3: Mac版のWordからPDF化する場合、紙印刷と同じものになる

Windows版のWordからPDF化すると「外部リンクがある場合、PDFファイルの該当箇所をポチッとすると、ブラウザが立ち上がりリンク先のコンテンツが表示される」という当たり前の動作をします。
が、Mac版のWordだとなぜかそれができませんでした。紙印刷と同じ状態のPDFが出来上がりました。

これに関してはいろいろと設定などを頑張ったのですがどうしてもうまくいかず、結局「必要なときは出力担当者の個人PC(Windows機)からPDF出力する」という力技かつ個人に依存するかたちで運用していました。

※弊社では従業員に社用端末としてMacを配布しています。

問題4: 管理番号の埋め込みが手作業

ドキュメントの性質上、配布先に応じた個別の管理番号を埋め込んでいるのですが、管理番号の埋め込みが手作業になるため、出力が必要な場合は

最新版のドキュメントをWindowsで開く
フッターに管理番号を設定する
PDF出力する
2-3 を出力する必要があるショップさま分繰り返す。（つらい）

このことにより、出力担当者はおのずと固定され、担当者が多忙な時期はPDF出力ができない状況でした。

結果と反省: 運用を見据えた初期設計が大事

共同編集が難しかったこともあり最初のWordファイルを作った担当者がひとりで各種メンテナンスをかけていくなかなかつらい流れになりました。
結果、初版リリース後は最低限の更新に限られ、本来やりたかった「ドキュメントをブラッシュアップし、よりよいものにしていく」流れにはなかなかたどり着けませんでした。

また、ツール的な問題もあり更新箇所のレビューが困難だったことも相まって、十分なレビューができないままに時間が経過していました。

「ドキュメント」とひとくちにくくるのは難しいのですが、長期間に渡っての運用を想定したドキュメントを作成する場合、あらかじめそれを想定したルールや環境・ツールの選定といった初期設計はとても大事だったと痛感しました。

見切り発車いくない。

チーム運用できる仕組みに変えたい

そんなこんなで「とりあえず最低限の更新をしつつも、本当にこのままでいいのか……」という状況が続いていた2023年のはじめ、突然「ドキュメントの性質上、いっそGitHubで管理したほうが楽じゃね？」と思い至りました。

とはいえ、Word ファイルはバイナリなので、GitHubでの管理には向いていません。
テキストベースで文書を作成し、それをもとにPDF化するツールがあればそれに乗り換える方向で自然と考えはじめました。

テキストで印刷に耐えられるドキュメントを作成する、ということで最初に思いついたのは TeX を使うことなのですが、以下の理由で難しいかもという感触でした。

学習コストが高い（TeXを知らないメンバーが多そう。そもそもTeXで論文書きましたって人、どれくらいいるんだろ）
私も思い出すまでに時間がかかりそう。というか、私が主に使っていたのはピー（自粛）年前なので多分いろいろ変わってる。

ちょうど、このタイミングでひまにまかせて（別件で） Hugo や MkDocsといった静的サイトジェネレーターで Markdown から HTMLへの変換遊びをしていました。
この流れで「Markdown をHTML化できるのであれば、PDFもできるじゃろ」という発想になりました。（安易）

で、いろいろ検討しました。

VS Code の Markdown 拡張 => PDF化は可能だが、改ページコントロールや目次作成、ページ数が多くなるマニュアルのPDF化だとちょっと物足りない。ささっと作ったMarkdownファイルをPDF化するのにはよきなんですが。（ときどき使ってる）
Sphinx => 私には難しかった…
MkDocs (+Material theme) => 結構よいところまでいったけど、ネストされた箇条書きと番号付きリスト、Admonition が私の能力ではいい感じに出力させられず。
Vivliostyle => 最終的にこれを採用。theme-techbook をベースに調整しました。
Re:VIEW => 私ひとりならまだしも、チーム運用することを鑑みると学習コストが高そうと判断

検討するにあたっての要件は主に以下でした。

Windows/Mac で利用可能。
- 軽い気持ちで調べたり検証したりするのは、個人の趣味半分で実施していたため。私、個人持ちのMacを持ってないんです。
いい感じの出力が得られるまでの調整が、私（非エンジニア）のスキルレベルでなんとかなる。
フッターへの管理番号の埋め込みについても、出力時に調整することでなんとかできる。
導入手順さえ整えれば、特別な調整なしにメンバーが利用できる。（業務の関係で Homebrew は導入しているのでパッケージマネージャーさえ利用できればなんとかなると踏みました）

運用方法を変更するための前準備

前準備1: 事前検証後に相談

ツール選定とある程度の検証をプライベートのWindows環境で実施し「これでいけそう」という感触を得た後、チームメンバーに「かくかくしかじかで、こういうつらみを感じてるからこういう方向で運用変更を考えてるんだけどどうだろう」と相談しました。

GitHub管理に変えてみることについては「GitHubってエンジニアが開発でつかってるやつだよね。見たことはあるけど、使ったことない。まぁ、試してみるか」という感じで、まずは一部メンバーで試験運用してみることになりました。

前準備2: WordファイルをMarkdown形式に変換

タイミング的にもちょうどよく、Wordで主に更新作業をしていた担当者の本業がちょうど佳境に入っていたこともあり、Wordでのドキュメント更新が難しい時期でした。
更新が止まる時期だからこそ、運用を変更するにはよい時期と判断し、空き時間で追加検証を含めて作業開始しました。

移行を実施するときに大事なのは「二重運用をする期間をいかに短くするか」です。
可能な限り以下で調整するのがよいでしょう。

移行作業をはじめたら切り替えるまでは移行元は追加・変更しない。
移行元作業での追加・変更作業が発生するとしても最低限とし、移行先へも同様の追加・更新作業をすぐに実施する。
上記をできるだけ短期間で実施するため、移行先へ切り替えるための最低条件（ミニマムゴール）を設けておく。
- 移行元がきちんと動いている場合は、完璧を求めて移行期間を長々ととるのは経験上よくないことが多いです。上記理由により、移行期間中の更新作業は普段より工数が増加すると認識すべきです。
- 多少完璧でなくても「あとで修正すればよい」ものは、優先度を下げてよいです。移行後に修正を忘れないようにメモしましょう。今回の場合は後述する GitHub Issues が大活躍しました。

元ファイルは全部で100ページを超えるボリューム（運用と出力の関係で3ファイルに分割していました）で、かつ画面キャプチャが入っていたりFAQサイトへのリンクもあります。そのため記載しているテキストを手動でコピペし、そこから Markdown 形式に書き換えていくのは物量的にも現実的ではありませんでした。（それにめんどくさいし、ミスしそう）

いろいろ調べた結果、Pandocでざっくり変換をかけ、その後、手で修正をかけていく方針にしました。

Pandocのわかりやすい説明

参考にしました

変換ほやほやのMarkdownファイルは以下の印象でした。

変換元で見出し設定を利用し、きちんと構造化できていればMarkdownにも引き継がれている。
画像キャプチャの張り込みなどはいい感じで移行できていた。（画像も別途ファイルとして抽出してくれた）
単純な表は Markdown形式に変換されていましたが、変換できないものはHTMLのtableとして変換されてました。とはいえ、Markdown ファイルとしてプレビューしてみたら見た目的には許容範囲と感じました。
Wordドキュメント内に設置されていたリンクは「うわぁ…」でした。うまく説明できないので以下実例。

出力例.md

（本文部分）
[定期受注情報の一括処理][]

(ファイルの末尾はこんな感じ)
  [定期受注管理]: https://support.ec-force.com/hc/ja/articles/900004859586
  [定期受注情報の一括処理]: https://support.ec-force.com/hc/ja/articles/900005809423
  [【定期受注管理】基本設定]: https://support.ec-force.com/hc/ja/articles/900005808763

Vivliostyle の自動生成の目次は「markdownファイルの見出しごと」になるのと、Markdownファイルが3分割は却って作業しにくいかな、と思い、脳死でリンク部分の修正をしながら手作業で分割していきました。
分割作業は業務時間外に実施していたこともあり、若干アルコールを入れながら作業してたかも。

ここまで終わった時点で、私が利用している GitHubアカウントのプライベートリポジトリに関連ファイルをすべて突っ込みました。
当時の記録を見てみると、最初のコミットが 2023/2/19 でした。ということで、おそらく最初に思い立ってから1ヶ月弱くらいでここまで辿り着いたようです。

前準備3: Markdownファイル修正＆テーマの調整

HTMLフォーマットが残った箇所を少しずつMarkdown形式に手変更
- 致命的なところを最優先で、ひたすら脳死で「とりあえずmarkdownとして見られるもの」にしてました。
- 例えば HTMLの aタグ（リンク）が結構残っていたのですが、この時点では放置してました。ひとまずPDF出力してもリンクはされますし。
利用していた Vivliostyle のテーマが技術同人誌向けのテーマだったこともあり、右ページと左ページで左右のマージンが異なっていました。
- 印刷物の場合、内側は広めに取ります。ページ数が多い場合はさらに広めに取ります。じゃないと内側が読みにくくなるため
- 今回は製本を想定していないため、左右ページのマージンは揃える設計にしたり、柱の調整やヘッダー・フッターの調整などを実施しています。
- 特にフッターに配布先ごとの管理番号を入れることを想定していたため、その部分も調整しました。
ある程度の調整が完了した時点で、弊社のデザインチームに色や見出しのCSSの調整をしていただきました。
- 当時、弊社では開発中のデザインシステムの話が社内共有されていたので、早い段階で相談・調整していました。

前準備4: 導入ドキュメントの整備

試験運用に向けて導入ドキュメントの整備をしました。
具体的には以下のドキュメントを準備しています。

リポジトリに置くREADME.md
- 必要なツールのインストール方法
- VS Code とGitHubを接続する方法。gitコマンドのインストールが必要な場合もある。
- Markdown でドキュメントを書くための簡単なリファレンス。改ページや各章扉など、Markdownだけで制御できない部分は独自でスタイルを作成していました。
- Vivliostyle cli を利用したプレビュー方法
- 成果物（PDF）の出力方法
VS Code 上でのリポジトリ切り替え方法・pull・作業用ブランチの作成方法・pull request の出し方など

また、この時点でMarkdownファイルの中身の掃除をしながら、気になるところを修正・加筆したり、CSS(scss)の調整をしたりも実施しています。

前準備5: 試験運用するメンバーに試してもらう

準備した導入用のドキュメントを利用して、メンバーが自身のMacに環境構築できるか、詰まるところがないかの確認を実施しました。
手順等はほぼ問題なかったのですが、少し伝わりにくいことなどもあったので導入ドキュメントをアップデート。

あわせて「他人のプルリク承認→リポジトリへマージ」「作業用のブランチを作成→変更をcommit→プルリクエスト作成」の流れを練習を兼ねて、何度か実施してもらいました。

GitHubのcommitのログを見ている感じではここまでが2023/4/14 だったようです。

最初のリリースまでに実施したこと

全体的にドキュメントを見直し、「書き換えや追記が必要なこと」「Word版ドキュメント作成後から2023年4月までにリリースされた新機能」など気づいたことを GitHub Issues に登録しました。
少なくとも最初のリリースまでに実施したいタスクは、すべてMilestoneに紐づけ、Issueをメンバーに割り当てたり、担当者が未定なIssueに関しては自身でピックアップして分担作業してもらうようにしました。

最初のIssue登録が2023/4/16だったのですが、だらだらと作業を進めても仕方がないため「とりあえず4月中に最低限終わらせて、連休明けに正式バージョンとしてリリースしようZE」とゴールを決めて、黙々と頑張りました。

4/28にいろんなブランチがようやくひとつに…

祝 Milestone 100%

4/28 にここまで辿り着いたのですが、「慣れの問題が一番大きいが、WordだとMicrosoftのおせっかい機能が働くので、それがない分慣れれば楽かも。この運用に変更していけそう」という判断になりました。

そしてこの時点でようやく残っていた <a>タグの掃除をしました。

正規表現が苦手なのでChatGPT先生に頼りました。ChatGPT先生ありがとう。

Vivliostyle カスタマイズについて

さて、Vivliostyle の導入についてですがtheme-techbook をベースにして、さほどカスタマイズはしていないと記憶してます。が、用途にあわせて以下の調整をしています。

管理番号の挿入

私が利用したテーマでは scss/_media.scss で左右ページのマージンや、各ページのヘッダー・フッターへの埋め込む内容などを定義するようになっていました。

Vivliostyle CLI の build コマンドで利用できるオプションとにらめっこしたのですが、フリーテキストで定義できそうなオプションは以下だったので、

  --title <title>                    title
  --author <author>                  author

vivliostyle build --title 管理番号 と指定することで、管理番号を埋め込むことにしました。

ついでに配布ドキュメントにバージョン番号を埋め込むことで、配布ドキュメントのバージョン確認を容易にできるようにしました。

scss/_doc-title.scss

/*
 * ヘッダ・フッタのテキスト定義
 * ロゴなどは含まない。
 * ヘッダ・フッタのデザインは _media.scss で定義してます。
 * pub-title に配布先別の管理番号を入れることを想定。
 * 管理上、定義ファイルを作成してます。別途、読み込みの定義（ `@import '_doc-title';`）が必要です。
 */
/* フッタ */
$bottom-text: env(pub-title);

/* バージョン番号 */
$version: '202311-01';

scss/_media.scss (一部抜粋)

  @bottom-left {
    //@include page-bottom-style();
    z-index: 1000;

    content: $bottom-text;
    font-size: 80%;
    color: $gray-100;
    margin-top: 15mm;
    margin-bottom: -$page-bleed;
    padding: 2mm 2mm 15mm 2mm;
  }

  @bottom-center {
    @include page-bottom-style();
    z-index: 1000;
    content: 'SUPER STUDIO Inc. All Rights Reserved. Doc ver.' + $version ;
    font-size:80%;
    text-align: center;
    margin-top: 15mm;
    margin-bottom: -$page-bleed;
    padding: 2mm 2mm 15mm 2mm;
  }

上記により vivliostyle build --title 管理番号 コマンドを実行することによりで出力するPDFファイルのフッタ部分への管理番号の埋め込みが可能になりました。

とはいえ、常に同時並行で複数プロジェクトが動いている関係で、1ファイルずつ出力するのもめんどくさいので、以下のような CSVファイル（shoplist.csv ）をあらかじめ準備しておき、

shoplist.csv

出力対象,procjectid,ランダム値,ショップ名
はい,projectA,No.XXXXXXXX,ショップ名A
いいえ,projectB,No.YYYYYYYY,ショップ名B
はい,projectC,No.ZZZZZZZZ,ショップ名C

コマンド一発で pdf/ ディレクトリ配下に管理番号を埋め込んだPDFファイルを出力するための、簡単なShell scriptを準備しました。

publish_doc.sh

#!/bin/bash

# shoplist.csv(utf-8) のヘッダ => 出力対象,procjectid,ランダム値,ショップ名
# col1 に projectid , col2 にランダム値, col3にショップ名が入る

awk -F, 'NR > 1 && $1=="はい" {print $2,$3,$4}' shoplist.csv | while read col1 col2 col3
do
    echo "ショップ個別マニュアル出力=> $col3"
    vivliostyle build --title $col2 -o pdf/$col1.pdf
done

echo "出力終了"

publish_doc.sh は以下を実行しているとても簡単なスクリプトです。

ヘッダー行（1行目）を飛ばし、2行目以降のみ実行
1カラム目（出力対象）が「はい」のときのみ、3カラム目（ランダム値）を --title に格納して vivliostyle build を実行
出力ファイル名は pdf/2カラム目(projectid).pdf
出力前に「ショップ個別マニュアル出力 => 4カラム目（ショップ名）」を表示させ、進捗状況を表示する

これで、10ショップ分でも20ショップ分でも、コマンド一発で出力が可能になりました。
バックグラウンドでの作業になりますので、正直とっても楽です。

運用開始後に実施したこと

ブランチの運用ルールを決める

このあたりでようやくブランチの運用ルールも決めました。
（このひと、さっき「見切り発車いくない」って言ってたような🤔）

master: ショップさまに提供可能なドキュメントとなるブランチ。ここに直接 commitしない。（release からの PR->mergeのみ）
release: 次回リリースに向けて作業をするブランチ。各種更新作業は release ブランチをベースに作業用ブランチを作成し、releaseブランチに対してプルリクエストを実施する。

今回は運用の規模が大きくなく、さらにGitHubに不慣れなメンバーもいるため、なるべく簡略化したルールにしてます。（たくさんルールをつくると混乱しちゃう）

リポジトリの引っ越し

最初のリリースまでは（お試しということもあり）私個人のプライベートリポジトリで運用していたのですが、最初のバージョンを出したあとにようやく会社の Organization 配下にお引越ししました。

とはいえ、GitHubの利用歴が浅い私はリポジトリの引っ越し経験がなく、ググったりChatGPT先生にお伺いして移行元のリポジトリをエクスポート→移行先のリポジトリにインポートという流れで実施すればよさそうな感触を得ました。
そして「（もし失敗しても）移行元のリポジトリに残っているから」と軽い気持ちで引っ越ししてみたのですが、なぜかIssueや Discussions などが移行できてませんでした。

こりゃアカン、と移行先のリポジトリを削除した後、結局、Transfer の機能を利用して（どきどきしながら）移譲しました。
実施方法は以下の記事のとおりだったと思い……ます。（記憶が）
※テスト運用していたときのメンバーが全員 Organization に含まれていたのもよかったです。

ちなみに Transfer 後、移行元のリポジトリは消滅、Organization 配下にリポジトリが爆誕したのですが、新しいリポジトリの管理権限がなく、PRのmergeや、branch の保護などの作業ができなくなってました。コーポレートエンジニアリング部門に泣きついて、事なきを得ました。

ブランチの保護設定

メンバーがうっかり master , release ブランチにcommitして大惨事、みたいなことが起こらないように master , release への反映は PR必須、merge 権限を持つメンバーを制限するなどの設定をしています。

これがあるので「操作を間違っても、運用中のドキュメントを更新することはない。だから安心して」という案内ができるのでよいですね。

textlint による自動校正の導入

閉じカッコ抜けや、編集時のtypo などうっかり起こしそうなことや、手慣れで書いてしまう冗長な文章を、PR時に textlintでチェックできるようにしました。

PR後のレビュー時に内容のレビューだけではなく、誤字脱字やtypo（なんども書き直したりしてると、同じ文字が連続で並んだりとかもありますね）、カッコ抜けなども発生するので「仕方ないとはいえ……」と思っていました。
そんな折に textlintの存在を知り、導入しました。

textlint の概要は以下がわかりやすかったです。

https://ics.media/entry/220404/

release へのPR時に GitHub Actionsを利用して自動チェックするようにしましたが、いきなりやると毎回とんでもない量の指摘を受けるので、導入前にローカルでチェック→指摘がなくなるまで修正を実施しています。

フィルタルールを作成する際に、SmartHRさんの記事をとても参考にさせていただきました（ありがとうございます！）

現在利用しているルールなどは以下です。（まだまだ育て中）

.textlintrc.json

{
  "plugins": {},
  "filters": {
    "allowlist": {
      "allow": [
        "◎◎"
      ]
    }
  },
  "rules": {
    "textlint-rule-preset-ja-technical-writing": {
      "sentence-length": {
        "max": 150
      },
      "max-kanji-continuous-len":{
        "max": 8,
        "allow": [
          "自動受注作成件数",
          "重複顧客管理画面",
          "定期継続率分析画面",
          "次回配送予定日通知",
          "次回受注予定日通知",
          "都道府県別配送期間管理"
          ]
      }
    },
    "textlint-rule-ja-no-redundant-expression": true,
    "textlint-rule-ja-hiragana-keishikimeishi": true,
    "@proofdict/proofdict": {
      "dictURL": "https://azu.github.io/proof-dictionary/"
    }
  }
}

textlint-rule-preset-ja-technical-writing をベースにしているのですが、
デフォルトルールだとちょっと厳しいので、

1文の長さは150字まで許容（デフォルト100文字）
連続できる最大の漢字長は8文字まで許容（デフォルト6文字）
- ecforce管理画面上の名称が既に長いものがあるので、8文字以上の固有名詞がある場合は、判明した段階で allow リストに追加しています。

のカスタマイズを入れています。

GitHub Action で textlint を動かすために以下を利用しています。

↓release branchへのPR時のみtextlintのチェックが動作するように調整しています↓

.github/workflows/textlint.yml

name: reviewdog
on: 
  pull_request:
    branches:
      - release

jobs:
  textlint:
    name: runner / textlint

    permissions:
      contents: read
      pull-requests: write

    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
      - name: Setup node/npm
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: textlint-github-pr-check
        uses: tsuyoshicho/action-textlint@v3
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-pr-check
          textlint_flags: "doc/**"
      - name: textlint-github-check
        uses: tsuyoshicho/action-textlint@v3
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-check
          textlint_flags: "doc/**"
      - name: textlint-github-pr-review
        uses: tsuyoshicho/action-textlint@v3
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-pr-review
          textlint_flags: "doc/**"

目検が辛いお年頃なので、textlint はありがたいです。

運用を変えて感じたこと

Markdown は日常で触れることが多い関係で、メンバーの学習コストは少ないと踏んでいましたが、最大の懸念点は「GitHub難しいかも」でした。

導入してみたところ、GitHubに不慣れな非開発職のメンバーだと、以下の傾向にあるようです。

VS Code を使ってれば特定のリポジトリ・ブランチの clone / pull処理までのハードルは、ちょっと丁寧めなドキュメントさえ準備してれば高くなかった。
更新作業（自分作業用のブランチを作って、プルリクエストする）はハードル高い。
というかブランチの概念が難しい。
とはいえ、同じファイルを複数人で編集しても（同じ箇所をいじらない限り）コンフリクトしないところを見せると「うおおお、便利ぃ」ってなってくれます。

ハードルが高そうなので、どこから覚えれば……という方には以下をおすすめしてます。

https://backlog.com/ja/git-tutorial/

見た目かわいくて、ハードル低そうに見えるので。（そして結構わかりやすいと思います）

その他、ドキュメント運用を GitHubベースに変更してみて感じたことを簡単に記載します。

GitHub Issues よき

「急がないけど、ここ、あとで直しておきたい」
「もうすぐこの機能が開発されるから、〇〇と△△は記述見直したほうがよいかも」
「◯月リリースでこういう機能が出ます（確認可能な開発環境はXXです）」

など、すぐに修正する必要のないものや、未来に変更するものなどは忘れずに Issue を作成するようにしています。

Issue をMilestone（次のリリースの目標）に紐付けることにより「次の更新にここまで作業しましょう」と決めることができます。そしてIssue ごとに担当者を決めて作業できるのがよきです。

また、誤字修正も Issue を切っておくと GFI （はじめての人向けのIssue）として練習してもらえるのでよいです。

同じファイルを複数人で同時編集してもほぼ問題にならない

もちろん全く同じ箇所を変更しているとコンフリクトを起こしますが、同じファイルの別の箇所を複数人で作業しても問題にならないのはよいです。
今回のWordドキュメントに限らず、バージョン管理ができても1ドキュメント全更新なものも多いです。Gitに慣れていると当たり前なのですが、デグレの心配をほとんどしなくてよいのがうれしいです。

更新履歴わかりやすい・レビューしやすい

まめにコミットして、コミットごとにコメントをわかるように書く
プルリクエストのコメントもきちんと書く

上記を徹底すると、何を目的にどんな変更がされたのかをリポジトリの更新履歴を見るとすぐにわかるのでよいです。

また、更新履歴がわかりやすくなったので、ドキュメント更新のリリースのたびに記載している「リリースノート」もさくさくっと作成できます。

今後について

現在ではPDFドキュメントの出力依頼は不要となり、各担当者自身で実行してもらうことが可能となりました。

とはいえ、ドキュメントの改訂作業が一部メンバーに偏っているということはあまり変わっていない状況です。
そのため、今後は「ドキュメントをわかりやすくしたい」という担当者を中心にGFIチケットの割当からはじめて、巻き込みが必要と感じています。（今、ぼちぼちはじめてる感じ）

巻き込まれた人が更新作業に慣れてきたら、よりわかりやすく、かつ最新情報が盛り込まれたドキュメント作成へ向けてシフトしていたいと考えています。

また、今回作成しているのはいわゆる「導入ドキュメント」のため、移行ショップさま以外でもオンボーディング用の内容としては共通の内容が多くあります。
CSS組版という仕組みを使っている関係で、独自classを追加することにより「移行ショップさまにのみに該当する記載箇所」を取り除き、一般のショップさま向けのオンボーディングドキュメントへ転用・まとめて運用することも可能かと考えています。
時間のあるときにもう少し深掘りして検証してみようかな、と思っています。

最後に

社内外向けを問わず、マニュアルやFAQサイト（仕様書なども含むでしょう）などは「作って終わり」ではなく、「作ってからずっと育てて運用していく性質のコンテンツ」です。
このようなコンテンツの運用・保守は地味ですし、得てして面倒なことでもあるのですが、作成・運用に携わることで自分たちが提供しているサービス・機能のより深い理解にも繋がります。

特に私のようにカスタマーと直接対応している部門の人間は、できるかぎり「会社として提供しているコンテンツ（＝ショップさまが目にするコンテンツ）」の中身をきちんと把握しておくことも大切なことかもしれません。

このとっても長い記事を最後まで読んでくださった方が「コンテンツを育てて運用していくこと」に少しでも興味を頂いていただければうれしいです。

おまけ

ときどき基本に立ち返るために読み返しています。