[インデックス 12361] ファイルの概要

このコミットは、Go言語の公式ドキュメントページ、特にdoc/docs.htmlの整理と改善を目的としています。主な変更点は、ドキュメント内のリンクパスのクリーンアップ、Go Wikiへの参照の追加、およびインストール関連ドキュメントのパス変更です。

変更されたファイルは以下の通りです。

doc/articles/wiki/index.html
doc/articles/wiki/wiki.html
doc/contribute.html
doc/docs.html
doc/gccgo_contribute.html
doc/gccgo_install.html
doc/install-source.html
doc/install.html

コミット

commit f78d50c6e5714ddea000be621216c76fb8f77a33
Author: Andrew Gerrand <adg@golang.org>
Date:   Mon Mar 5 14:31:27 2012 +1100

    doc: clean up docs page, refer to wiki, change install doc paths

    R=golang-dev, minux.ma, r
    CC=golang-dev
    https://golang.org/cl/5728051

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/f78d50c6e5714ddea000be621216c76fb8f77a33

元コミット内容

doc: clean up docs page, refer to wiki, change install doc paths

変更の背景

このコミットの背景には、Go言語の公式ドキュメントのユーザビリティとメンテナンス性の向上が挙げられます。当時のGoドキュメントは、一部のリンクが冗長であったり、情報源が分散していたりする可能性がありました。特に、.html拡張子を含む絶対パスは、URLの見た目を悪くするだけでなく、将来的なURL構造の変更に対して脆弱でした。

また、Goコミュニティが活発になり、Go Wikiのようなコミュニティ主導の情報源が充実してきた時期でもあります。公式ドキュメントからこれらのコミュニティリソースへの適切な参照を設けることで、ユーザーがより広範な情報を得られるようにすることが目的と考えられます。

具体的には、以下の点が変更の動機として考えられます。

URLのクリーンアップ: ドキュメント内の内部リンクから不要な.html拡張子を削除し、より簡潔でRESTfulなURL構造に移行すること。これにより、URLの可読性が向上し、将来的なコンテンツ管理が容易になります。
ドキュメントの整理: doc/docs.htmlページがGoドキュメントの主要なインデックスページであるため、その内容をより論理的に整理し、ユーザーが求める情報に素早くアクセスできるようにすること。
Go Wikiのプロモーション: Go Wikiがコミュニティによって維持される貴重な情報源であるため、公式ドキュメントから積極的に参照することで、その存在を広く知らしめ、ユーザーに活用を促すこと。
インストール関連ドキュメントのパス統一: インストール手順に関するドキュメントへのリンクパスを統一し、一貫性を持たせること。

前提知識の解説

このコミットを理解するためには、以下の前提知識が役立ちます。

Go言語のドキュメント構造: Go言語の公式ドキュメントは、通常、doc/ディレクトリ以下にHTMLファイルとして配置されています。これらのファイルは、Goのウェブサーバーによって提供され、golang.org/doc/のようなパスでアクセスされます。
HTMLとハイパーリンク: HTMLドキュメントにおけるハイパーリンク（<a>タグ）は、href属性にリンク先のURLを指定します。このURLは、絶対パス（例: /doc/install.html）または相対パス（例: install.html）で指定できます。
Go Wiki: Go Wikiは、Goコミュニティによって運営されている情報共有プラットフォームです。公式ドキュメントではカバーしきれない、より実践的な情報、チュートリアル、FAQなどが豊富に掲載されています。当時のGo Wikiはcode.google.com/p/go-wiki/wikiでホストされていました。
Goのインストール手順: Go言語のインストール手順は、OSやインストール方法（バイナリ配布、ソースからのビルド、gccgoなど）によって異なります。これらの手順は、複数のHTMLファイルに分割されて提供されていました。
Goの言語仕様 (Go Language Specification): Go言語の公式な仕様を定義するドキュメントです。この仕様は、言語のあらゆる側面（構文、セマンティクス、組み込み関数など）を詳細に記述しています。

技術的詳細

このコミットの技術的詳細は、主にHTMLファイルの変更と、それに伴うリンク構造の調整に集約されます。

.html拡張子の削除とパスの変更:
- 多くの内部リンク、特に/doc/install.htmlのようなパスが/doc/installのように変更されています。これは、Goのウェブサーバーが.html拡張子なしでもコンテンツを提供できるように設定されていることを示唆しており、よりクリーンなURLを実現するための変更です。
- 同様に、言語仕様へのリンクも/doc/go_spec.html#Errorsから/ref/spec#Errorsに変更されています。これは、言語仕様のURL構造が変更されたか、より汎用的な参照パスに統一されたことを示しています。/ref/specは、Goの公式リファレンスドキュメントへの新しい標準的なパスとして導入された可能性があります。
- doc/gccgo_install.htmlやdoc/install-source.htmlのメタデータにある"Path"フィールドも、/install/gccgo/から/doc/install/gccgoのように変更されています。これは、ドキュメントの内部的なパス管理の一貫性を高めるための調整です。
doc/docs.htmlの再編成:
- このファイルは、Goドキュメントの主要なインデックスページであり、大幅な変更が加えられています。
- 「Installing Go」セクションの追加: 以前は他のセクションに散らばっていたインストール関連のリンクが、独立したセクションとしてまとめられました。これにより、新規ユーザーがGoのインストール方法を簡単に見つけられるようになりました。
- 「How to write Go code」の移動と説明の変更: このセクションは、「Learning Go」の下に移動し、その説明が「新しいパッケージの書き方とコードのテスト方法」から「go commandを使ってパッケージ、コマンドの取得、ビルド、インストール、テストの実行方法」へと変更されました。これは、go commandの重要性を強調し、より実践的な内容に焦点を当てる意図があります。
- Go Wikiへの参照の追加と強調: 「Other introductory articles」セクションが削除され、代わりに「Go Language Community Wiki」への新しいセクションが追加されました。これにより、Go Wikiが公式ドキュメントから明確に推奨される情報源となりました。
- Go Blogへの参照の追加: 「Go Articles」セクションに「The Go Blog」へのリンクが追加され、公式ブログの重要性が強調されました。
- 「Videos and Talks」から「Talks」への変更と注意書きの追加: 「Videos and Talks」セクションが「Talks」に名称変更され、Go 1以前のトークには「*」マークと「Go 1以前に書かれたものであり、一部の例は現在正しくないが、依然として価値がある」という注意書きが追加されました。これは、古い情報による混乱を避けるための配慮です。
- 古いトークの削除とGo Wikiへの誘導: 多くの古いトークへのリンクが削除され、代わりにGo Wikiの「GoTalks」ページへのリンクが追加されました。これにより、トークに関する最新かつ包括的な情報はGo Wikiで管理されるようになりました。
- 「Non-English Documentation」の整理: 以前は各国語ごとに詳細なリストがあったものが、Go Wikiの「NonEnglish」ページへの単一のリンクに集約されました。これにより、多言語ドキュメントの管理がGo Wikiに委譲され、公式ドキュメントのメンテナンス負担が軽減されました。
- 「The Go Community」セクションの整理: コミュニティ関連のリンクも整理され、Go Packages DashboardやGo Project Dashboardへのリンクが更新されました。

これらの変更は、Goドキュメント全体の構造を改善し、ユーザーがより効率的に情報を探し、Goコミュニティのリソースを活用できるようにするための包括的な取り組みの一環です。

コアとなるコードの変更箇所

このコミットにおけるコアとなるコードの変更箇所は、主に以下のファイルと行に集中しています。

doc/docs.html:
- インストール関連セクションの追加と再編成。
- 「How to write Go code」セクションの移動と説明の変更。
- Go Wiki、Go Blogへの新しい参照の追加。
- 古いトークの削除と、Go Wikiの「GoTalks」ページへの誘導。
- 多言語ドキュメントの整理と、Go Wikiの「NonEnglish」ページへの誘導。
- コミュニティ関連リンクの整理。
- 具体的には、doc/docs.htmlでは168行が変更されており、これはこのコミットの最も大きな変更点です。
doc/articles/wiki/index.html および doc/articles/wiki/wiki.html:
- Goのインストール手順へのリンクが/doc/install.htmlから/doc/installに変更。
- 言語仕様へのリンクが/doc/go_spec.html#Errorsから/ref/spec#Errorsに変更。
- 関数リテラルに関する言語仕様へのリンクがhttp://golang.org/doc/go_spec.html#Function_declarationsから/ref/spec#Function_declarationsに変更。
doc/contribute.html、doc/gccgo_contribute.html、doc/gccgo_install.html、doc/install-source.html、doc/install.html:
- これらのファイル内のGoインストール関連ドキュメントへの内部リンクが、.html拡張子なしのパス（例: /doc/install）に統一されました。
- 特にdoc/gccgo_install.htmlとdoc/install-source.html、doc/install.htmlでは、HTMLファイルのメタデータにある"Path"フィールドも更新され、URL構造の変更が反映されています。

コアとなるコードの解説

これらの変更は、Go言語のドキュメントエコシステム全体の一貫性とユーザビリティを向上させるための戦略的なものです。

URLの簡潔化と永続性: .html拡張子を削除し、よりセマンティックなURLパスを使用することで、URLがよりクリーンになり、ユーザーにとって覚えやすくなります。また、将来的にドキュメントのフォーマットがHTML以外に変わった場合でも、URLを変更する必要がなくなるため、リンクの永続性が高まります。/ref/specのような新しいパスは、Goの公式リファレンスへの安定した参照を提供します。
情報アーキテクチャの改善: doc/docs.htmlの再編成は、情報アーキテクチャの観点から非常に重要です。インストール、学習、記事、トーク、コミュニティといった明確なカテゴリに情報を整理することで、ユーザーは自分の目的（例: Goをインストールしたい、Goのコードの書き方を学びたい）に応じて、必要な情報に素早くたどり着けるようになります。
コミュニティリソースの統合: Go WikiやGo Blogへの明確な参照を追加することで、公式ドキュメントがGoエコシステム全体のハブとしての役割を強化しています。これにより、ユーザーは公式情報だけでなく、コミュニティが生成する豊富な情報にもアクセスできるようになります。特に、多言語ドキュメントや古いトークの情報をGo Wikiに集約することで、公式ドキュメントのメンテナンスコストを削減しつつ、情報の網羅性を維持しています。
情報の鮮度と正確性への配慮: Go 1以前のトークに注意書きを追加したことは、情報の鮮度と正確性に対する配慮を示しています。技術の進化に伴い、古い情報が誤解を招く可能性があるため、このような警告はユーザーにとって非常に有用です。

これらの変更は、単なるファイルの修正に留まらず、Go言語のドキュメントがどのように提供され、ユーザーがどのようにそれにアクセスすべきかという、より広範な戦略の一部を形成しています。

参考にした情報源リンク

コミット情報: /home/orange/Project/comemo/commit_data/12361.txt
GitHubコミットページ: https://github.com/golang/go/commit/f78d50c6e5714ddea000be621216c76fb8f77a33
Go言語のドキュメント構造に関する一般的な知識
HTMLのハイパーリンクに関する一般的な知識
Go言語の歴史とコミュニティに関する一般的な知識

Keyboard shortcuts

comemo