はじめに
この記事は 2023 年の MDN 翻訳 Advent Calendar 向けに作成したものです。
こんにちは。debiru です。MDN が Wiki プラットフォームだった頃から記事を編集したりしてきました。
今日は、現在の GitHub 管理されている MDN の編集に参加するのは敷居が高いのかどうかについて考えていきたいと思います。
MDN が Wiki だった頃
2020 年 12 月 14 日より、MDN は GitHub ベースの新しい Yari プラットフォームで運用しています。それまでは 2012 年 8 月 3 日に立ち上がった Kuma という Wiki プラットフォームが採用されていました。それ以前にはより古い Wiki プラットフォームが採用されていました。詳細は MDN のあゆみを参照ください。
現行のシステムとそれ以前では、Wiki であったかどうかという点が大きく異なります。Wiki であった頃の MDN は Web ブラウザ上でページの編集を行うことができ、その場でページの更新ができていました。
以下は Kuma 時代のプラットフォームの構成です。図は MDN Web Docs evolves! Lowdown on the upcoming new platform - Mozilla Hacks - the Web developer blog より引用。
編集者（コントリビューター）と一般の読者が共に CDN 上から編集・閲覧操作をする必要がありました。そのため CDN では編集者のことを考慮した短い時間のコンテンツキャッシュを行っていました。
現在の GitHub ベースの MDN
現在の Yari プラットフォームでは、MDN のページは GitHub でファイルとして管理されており、Wiki プラットフォームだったときと比べてシステム構成が改善されています。
以下は Yari 時代のプラットフォームの構成です。図は MDN Web Docs evolves! Lowdown on the upcoming new platform - Mozilla Hacks - the Web developer blog より引用。
Kuma プラットフォームのときと異なり、編集者（コントリビューター）と一般の読者がアクセスする先が分離されました。編集者は GitHub 上でドキュメントの編集や整備を行い、一般の読者は CDN 上からコンテンツを閲覧するという体制になっています。編集者と読者のアクセス口が分離されたことで CDN は読者にとって最適なコンテンツキャッシュの設定ができたりとパフォーマンスを発揮できるようになりました。
Yari に移行してドキュメントを編集するのに敷居は高くなったのか？
結論から述べると、答えは No です。
むしろ GitHub 管理されたことで、ドキュメントの横断的な一括置換など、体系的な編集は圧倒的にやり易くなりました。Yari の移行に際して、ドキュメントの編集に関して生じたデメリットはないと筆者は考えています。
Web ブラウザ上からページを編集できなくなったのかというと、そうでもありません。確かに Wiki ではなくなりましたが、GitHub 経由でコンテンツを編集できることには変わりありません。なお、ドキュメントの編集方法には大きく 2 つの方法があります。
簡易的なページの編集 - Wiki に近い編集方法
通常、以下のような手順で作業を行いますが、軽微な修正であれば Issue への報告を省略しても問題ありません。
- 作業内容を Issue に報告する（他の人が同じ作業をしないようにするため）
- 編集作業を行う
簡易的なページの編集方法
例えば、https://developer.mozilla.org/ja/docs/Web/SVG/Element/g に誤字脱字なんかを見つけたとします。
ドキュメントページの下部にある "Found a content problem with this page?" から "Edit the page on GitHub." のリンクへアクセスします。これは GitHub 上でページを編集するためのリンクです。
0. 作業内容を Issue に報告する
Issue を作成する場合は、以下のリポジトリの Issue を作成してください。
このリポジトリは日本語コミュニティ向けのものなので、全て日本語で記述して構いません。メッセージのフォーマットもあまり気にしなくても大丈夫です。デフォルトのテンプレートは全消しして書いてもらっても構いません。
なお、記述する際は、デフォルトテンプレートのコメント記述は削除してもらえると助かります。Issue の内容が Slack に自動送信されるのですが、その際にデフォルトのコメント記述があると非常に邪魔なのです……。
1. 編集画面
Wiki の編集画面と似ていますね。ここでドキュメント（Markdown 形式）を編集します。
GitHub 管理されている関係で、編集時には残念ながら完全なページプレビューを利用することができません。マクロなどは展開されませんが、代わりに GitHub 標準の Markdown プレビューを利用することができます。
編集を終えたら、右上の緑色のボタン "Commit changes..." をクリックします。
2. git commit を行う
"Commit changes..." をクリックすると、git commit 相当の処理が進みます。
ここで、コミットメッセージを入力します。コミットメッセージは日本語で書いても構いません。
なお、"Extended description" という項目がありますが、ここは空のままで問題ありません。もし詳細なコミットメッセージを記述したい場合は、ここに記述します。
コミットメッセージを記述したら、右下の "Propose changes" をクリックします。
3. 変更内容を確認する
前の画面で "Propose changes" をクリックすると次のような画面に遷移します。
画面下部に git の差分が表示されていますので、ここで変更内容が適切かどうかを確認してください。もし間違いや不備があった場合は、このコミットを無視して、再度編集をやり直します。
変更内容に問題がなければ、右上の "Create pull request" をクリックします。
4. Pull Request を作成する
前の画面で "Create pull request" をクリックすると次のような画面に遷移します。
Add a description に英文が色々書かれていますがテンプレートなので気にしないでください。
まずは Add a title を適切に記述します。タイトルには、修正内容の詳細よりも、どのページの修正なのかが分かるようなタイトルを付けるほうが好ましいと思います。レビュアーが Pull Request 一覧を見るときに知りたいのは修正内容よりも修正対象であるケースが多いからです。
というわけで、次のような感じで記述すれば良いです。
- Add a title には「/Web/SVG/Element/g のライブプレビューを修正」と記述しています。
-
Add a description には「### Description」のセクションだけ「/Web/SVG/Element/g のライブプレビューが表示されていなかったので修正しました。」と記述しています。
- 他のセクション「Motivation」「Additional details」「Related issues and pull requests」は特記すべきことがなければ空のままで問題ありません。セクションごと削除しても良いです。
Pull Request のメッセージにはレビュアーにとって必要だと思われる情報を適切に記述するように心がけましょう。とは言っても、軽微な修正であれば「Description」に「軽微な修正」と書くだけでも構いません（何も書かない人もたまにいます）。
Pull Request のメッセージを記述し終えたら、右下の "Create pull request" をクリックします。
5. 編集作業は以上で完了です！
のような Pull Request が作成されます。
GitHub 管理されてからは MDN では全ての変更に対してレビュープロセスが実施されます。なのでレビューされるのを待ちましょう。
レビュアーは自動で設定されますが、その方がレビューするとは限りません。レビューは我々と同じ日本語コミュニティのコントリビューターが行っています。レビュー権限を持つコントリビューターのうち、気づいた方がレビューしてくれます。
なお、コントリビューターは時間のあるときにしか作業できないため、レビューが遅くなってしまう場合もあります。
作成した Pull Request に対して、もし 1 週間以上音沙汰がないような場合は、Pull Request のコメントで「レビューしていただけますでしょうか」などとコメントを記述してみてください。コメントに気づいたコントリビューターから何かしら反応をもらえるはずです。
本格的なページの編集 - git 操作を伴う編集方法
- 作業内容を Issue に報告する（他の人が同じ作業をしないようにするため）
- 編集作業を行う
こちらの手順については、MDN 月例ミートアップ - 翻訳ガイド | HonKit を参照してください。このドキュメントも私が書いたので、不明点があれば質問してください。
さいごに
MDN が GitHub 管理されて編集の敷居が高くなっていると感じられている方も少なくないと思います。2020 年 12 月から GitHub 管理に変わりましたが、実際、私も 2021 年頃はそのように感じていました。
この記事を参考にして、多くの皆様に MDN の編集に参加してもらえたら幸いです。この記事で説明した通りですが、Wiki のときと比べても、編集の手間はほとんど変わっていません。単に GitHub 管理されているという事実があるだけです。
まぁ、それでももし編集するのはちょっと、と感じられている方は、ぜひ「問題の報告」という方法で MDN に参加してください。
「リクエスト:」と付けて、ページ名と修正内容を Issue に登録するだけで、気づいたコントリビューターが修正作業をしてくれるというものです。あなたのリクエストをお待ちしております！
というわけで、MDN は Wiki から GitHub 管理に変わっても編集の敷居は高くなっていないというお話でした。
おわり。