COLUMN
CMS移行後のマニュアル作成｜管理画面を全部開いたら、不具合が3つ見つかった
WordPressからコンテナへ移行したサイトで、公開から少したって更新マニュアルを作った。
管理画面を左メニューの上から順に全部開いて撮影したら、表示確認では一度も見つからなかった不具合が3つ出てきた。
ひとつは、そのまま保存するとお知らせのカテゴリーが消える状態になっていたことだった。
この記事では、移行後の引き継ぎでマニュアルを作ったときに何が見つかったのか、なぜ移行の検証で漏れたのか、いまは移行のどの段階でマニュアル作りを始めているのかをまとめておく。
CMS移行の最後の工程を「データを入れて表示を確かめたら終わり」にしている人に、一つ工程を足すきっかけにしてほしい。
CMS移行の「引き継ぎ」は、データを入れた後に始まる
CMSの移行というと、記事やページを新しい仕組みに運び、見た目を整え、URLを合わせるところまでを思い浮かべることが多いと思う。
私たちもそこまでを移行の本体として扱ってきた。
ただ、サイトを持っている会社にとっての本番は、公開した翌日からだ。
担当の人が自分で新着情報を書き、写真を差し替え、ページの文言を直せるようになって、はじめて移行が終わる。
その引き継ぎのために、更新マニュアルをPowerPointで作ることにした。
依頼の中身は「固定ページと投稿の直し方が分かる資料」で、管理画面の画面写真に番号を付け、サイトのどこが変わるのかを同じ番号で示す形にした。
できあがったのは90枚近いスライドで、作る途中で見つかった不具合は3件だった。
3件とも、移行したデータを公開ページで見るだけでは気づけない種類のものだった。
マニュアルは、左メニューの並び順で章を立てた
章立ては、管理画面の左メニューの並び順にそろえた。
はじめに、固定ページ、投稿ページ、メディア管理、カテゴリー管理、全固定ページ一覧、投稿マスタ管理、困ったとき、の8章だ。
目次のスライドには左メニューの画面写真を置き、各項目に章番号の丸を付けた。
担当の人が管理画面を開いたときに、マニュアルのどこを読めばいいかが左メニューから引けるようにするためだ。
固定ページの章は、1ページごとに「全体の地図」を1枚作り、その後にブロックごとの対応スライドを続けた。
地図は、左にページ全体の画面写真を置いて各ブロックに番号を振り、右の表に編集のしかたを色で分けて載せた。
青は入力欄で直せるもの、オレンジはHTMLの中の文字だけを直すもの、ティールは設定だけで中身が自動で入るもの、グレーは触らないもの、という4色だ。
対応スライドでは、左に管理画面でそのブロックを開いた画面、右にサイトの該当部分を置き、同じ番号の枠でつないだ。
こういう作りにすると、管理画面にある入力欄を一つ残らず開いて、サイトのどこに出るのかを1つずつ確かめることになる。
不具合が見つかったのは、まさにこの作業の途中だった。
見つかった不具合1：保存するとカテゴリーが消える状態だった
新着情報の編集画面を開いたら、カテゴリーを選ぶ欄がどこにも出ていなかった。
サイトの新着情報一覧では、4つのカテゴリーでちゃんと絞り込めていた。
表示は正しいのに、更新する画面にだけ欄が無い、という状態だ。
原因は、移行のときの初期データの入れ方にあった。
旧サイトのお知らせとカテゴリーは、管理画面から1件ずつ登録したのではなく、SQLでデータベースに直接入れていた。
そのとき、管理画面が保存するときの形と、少しだけ違う形で入っていた。
カテゴリーがどのディレクトリに属するかの書き方が違ったために、編集画面の検索に引っかからず、欄ごと出ていなかった。
もっと怖かったのは、欄を出しただけでは直らないことだった。
記事側に入っていたカテゴリーの値も、管理画面の保存形式と書き方が違っていた。
そのため欄を表示しても既存の選択が空のままになり、担当の人が本文の誤字だけ直して保存すると、カテゴリーが消える状態だった。
一覧の絞り込みからその記事が黙って外れるので、気づくのはずっと後になっていたと思う。
直し方は、データを管理画面の保存形式に統一することだった。
カテゴリー側の書き方を直し、管理画面が使う補助のテーブルに4行を足し、記事側の値を下書き・公開・プレビュー・履歴の4系統すべてで同じ形にそろえた。
何度流しても結果が変わらないSQLにして、本番では対象のテーブルを先に書き出してから流した。
反映後は、編集画面で既存の選択が残っていること、4つのカテゴリーの絞り込みがそれぞれ1件ずつ、一覧が4件出ることを確かめた。
ローカルでは実際に管理画面から保存し、管理画面と同じ形で保存されることも見た。
見つかった不具合2と3：使われていない欄と、化けたサイト名
2つ目は、事例の投稿の編集画面にあった、地域を示すチェックの欄だった。
マニュアルに「この欄を変えるとサイトのここが変わる」と書くために表示先を探したら、どのページもこの欄を参照していなかった。
実際の一覧は、別の「地域」の項目で並んでいた。
担当の人がチェックを入れても何も起きない欄なので、マニュアルに載せるより先に、編集画面から欄を外した。
データベースの列は残し、画面からだけ消している。
3つ目は、ログイン画面と管理画面の左上に出る会社名だった。
社名に半角のアポストロフィが入っていて、それがアンパサンドとシャープと数字039を並べた記号の列のまま表示されていた。
設定値がすでに安全な形に変換された状態で保存されているのに、表示のときにもう一度変換していたのが原因だった。
これはこのサイトだけの問題ではなく、CMSの本体の関数の作りだったので、本体の修正として直し、このサイトにはその1ファイルだけを先に届けた。
3件のうち、サイトを見に来る人の目に触れるものは一つも無い。
どれも、更新する人が管理画面を開いたときに初めて出てくる。
なぜ移行のテストでは見つからなかったのか
移行のときの検証は、公開ページを基準にしていた。
全ページが表示されるか、URLが旧サイトと同じか、一覧の件数が合っているか、検索エンジン向けの情報が出ているか。
どれも大事な確認で、実際にここでも別の問題をいくつも拾っている。
でも、どの確認も「データが表示側からどう見えるか」を見ていて、「管理画面から保存したら何が起きるか」は見ていなかった。
SQLで直接入れたデータは、表示側の読み方に合っていれば正しく表示される。
管理画面の保存の形と合っているかどうかは、管理画面で開いて保存してみるまで分からない。
移行作業をする側は、データを入れ、表示を確かめ、URLを合わせるところで仕事が終わったと感じやすい。
更新する人の手順を最初から最後までなぞる工程が、移行の計画に入っていなかった。
マニュアル作りは、その工程を強制的に通す作業になっていた。
入力欄を1つずつ開き、表示先を1つずつ探さないと、スライドが作れないからだ。
不具合を探すつもりで始めたわけではないのに、結果として一番細かい受け入れ検査になっていた。
更新マニュアルを作るときに守っていること
この案件の後、マニュアル作りの手順を決めごととしてまとめた。
移行の検証として効いたものを中心に、いくつか挙げておく。
1つ目は、実際に更新する人のアカウントで撮ることだ。
コンテナは権限によって左メニューや入力欄が変わるので、管理者のアカウントで撮ると、担当の人には出ない欄まで載ってしまう。
逆に、担当の人にしか出ない不具合を見落とす。
2つ目は、本番の内容で撮り、本番では保存もプレビューも押さないことだ。
プレビューもデータベースに書き込む操作なので、撮影は閲覧だけに限っている。
編集画面を開くと編集ロックがかかるので、撮り終えたら別のページへ移ってログアウトする。
保存してどうなるかを確かめたいときは、同じデータを入れたローカルの環境で試す。
3つ目は、書く前に実際の画面で確かめることだ。
「必須」と書かれた欄が空でも保存できるのか、ボタンの名前が権限ごとに違わないか、メニューの項目名が目次と一致しているかを、実物から拾って突き合わせる。
思い込みで書いた説明は、そのまま担当の人の操作ミスになる。
4つ目は、マニュアルを作る途中で不具合を見つけたら、先に直してから撮り直すことだ。
「この欄は使わないでください」とマニュアルに書いて済ませると、欄は残り続け、説明だけが増える。
今回の地域の欄も、注意書きを書く代わりに画面から外した。
ちなみに画面写真が多いので、最初はファイルが29MBあった。
大きな画像だけを自動で圧縮する処理を足して16MBまで減らし、メールで送れる大きさにした。
マニュアル作りを、移行の工程表に入れておく
いまは、更新マニュアルを公開後のおまけではなく、移行の工程の一つとして扱っている。
データを入れ、表示を確かめ、URLを合わせた後に、「更新する人の操作をすべてなぞる」工程を置く。
マニュアルを作らない案件でも、左メニューの上から順に編集画面を開き、1件保存してみるところまではやるようにした。
見つかる不具合は、たいてい小さい。
でも、小さいまま放っておくと、担当の人は「何か変だけど、自分の操作が悪いのだろう」と思って黙ってしまう。
移行した側がそれに気づくのは、カテゴリーが消えた記事がたまって、一覧の数が合わなくなってからになる。
公開の前に一度、管理画面から保存してみる。
それだけで、移行後の数か月の問い合わせはだいぶ減ると私は思う。
コンテナには、管理画面の中に運用マニュアルやお知らせを置いておける機能がある。
PowerPointの資料とは別に、よく使う手順を管理画面の中にも残しておくと、担当の人が替わったときの引き継ぎにも使える。
WordPressからの移行の進め方は、移行のページにまとめている。