Astro DocsにIdea Discussionを出した話
▼ 目次
こんにちは、Sakuです。先日Astro DocsにIdeaのDiscussionを出してみました。「改善案を思いついたらDiscussionで共有してみる」という経験が、思ったより学びになったので、Discussion開設の経緯や流れを整理し、残しておきます〜。
今回出したDiscussionはこちらです。 https://github.com/withastro/docs/discussions/13023
そもそもAstro Docsと私の関わり
Astroはコンテンツ重視のWebフレームワークで、そのAstroの公式ドキュメントがAstro Docsです。
Astro Docs
Astroの公式ドキュメント。Astro v5時点の内容が最新として公開されている。
現在のメジャーバージョンはv5です。次のメジャーバージョンであるv6も今年中に公開されそうなので、個人的に注目しています。
自分は昨年末からAstro Docsの日本語版にぼちぼちコントリビュートしています。英語版が最新なので、英語版との差分を埋めたり、日本語ページがない場合は新規に追加する流れが中心です。普段の作業は、英語版の変更を追って日本語版を更新することが多いです。
改善案を出した背景
今回の更新作業中に「ここはこうした方がいいんじゃないか」と思う箇所が見つかったので、Ideaとして出してみました。スタンスとしては、「気づいたことは共有してみる」くらいの軽さです。
発端は、Docs 過去バージョンへのリンクに関してです。Astro Docsは過去のメジャーバージョンの資料へのリンクも用意しています。これは「古いバージョンを使い続ける人」「久しぶりにバージョンアップする人」「過去との差分を確認したい人」など、一定数のニーズがあるからだと思います。
ただし、古いバージョンを常にデプロイして維持するのは難しいため、Astroの場合は、Internet ArchiveのWayback Machineへのリンクで補っているようです。Astroだけが特別というわけではなく、他のフレームワークでも似た対応はよく見かけます。
過去のDocsを維持するとなると、ドキュメント自体がAstroで動いているなどの都合もあって、AstroのバージョンやNode.jsなど依存関係においてバージョンとの整合を取る必要があります。この点を加味すると、翻訳も含めて長期運用するのは現実的に難しいと思いますし、「最新優先で、過去はアーカイブで補う」という方針は納得できました。1 逆に言うと、ReactやNext.jsは割と異常レベルですごいと思います。エコシステムがなせる技だと感じました。
Internet ArchiveのWayback Machine
過去のWebページのスナップショットを保存し、当時の内容を閲覧できるサービス。
Astroは古いDocsへのリンクを提供しています。現行版はv5なので、過去版はv4〜v1ということになり、いずれもunmaintainedのsnapshotということになります。具体的にv4以外のv3リンクはInternet ArchiveのWayback Machineのスナップショットリンクであり、v2のリンクはNetlifyのプレビューに飛ぶリンクでしたが、遷移しても「Site not found」と表示されるいわゆる内容がない状態でした。そこで、v2に対応するスナップショットを探し、「このリンクに差し替えた方がよいのでは」というIdeaを出しました。全言語の該当箇所にも同様に反映するべきかと思うので、その旨も伝えました。
Idea Discussion
具体的な不具合報告ではなく、改善案や提案を共有するための場。
具体的に出したDiscussionについてまとめると
実際に私が出したDiscussionの内容を簡単にまとめると、以下の通りです。
実際の提案内容
主に書いたこと
- 詳細
- 影響範囲
- 現状の挙動
- 確認に使用したブラウザ
- どのような場面で発見したのか
- 改善案
提案内容には色々書いていますが、個人的にはわかりやすさが重要かなと思っています。提案内容が伝わらないと意味がないので、なるべく具体的に、かつ簡潔に書くことを心がけました。
その上で、大事だなと思っているのは改善案の部分です。単に「ここが間違っている」と指摘するだけでなく、「こうしたらよいのではないか」という提案を添えることで、受け取る側も対応しやすくなります。OSSプロジェクトは多くの人が関わっているので、提案内容が明確であることは非常に重要だと思います。正直この改善案に関しては正しくなくても、正解でなくてもいいと思います。とりあえず自分の意見を持ち伝えるこれこそが本質ですし、真摯に伝えれば相手からも意見が返ってくる為、これらを加味してより良い方法を模索することができます。そうしたこのやり取りこそがdiscussionだと思います。
Discussionで得たこと
提案内容そのものより、「なぜ古いDocsは残りづらいのか」を考えるきっかけになりました。
- ドキュメント自体もAstroで動いていて、古いAstroのまま維持するのは依存関係的に難しい
- 翻訳も含めると、過去バージョンのメンテナンスはコストが高い
- 一定数の古いバージョン利用者はいるが、最新への誘導も必要
自分が実際に感じたのは、古いDocsを残すこと「運用コスト」と「環境依存」が想像以上にかかるということです。Astroのバージョンに合わせてNode.jsのバージョンも変わり、古い環境では動作が保証されないケースもあります。そこまでして過去Docsを維持するより、最新への移行を案内する方が現実的ですし、そうした他フレームワークの方針もものすごく理解できます。
このあたりを背景として理解できたのが大きいです。自分が提案したのは小さな修正ですが、「運用上なぜそうなっているか」を読み解く良い学習になりました。2
今回はAstro DocsにIdea Discussionを出した経緯をまとめました。まだDiscussionはオープンなので、興味のある方はぜひ意見を追加してください。OSS初心者でも、疑問や改善案があればDiscussionやIssueで共有するだけで学びになると感じました。