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

このコミットは、Go言語プロジェクトの公式ドキュメントに関する更新です。具体的には、ユーザーがGoに関するヘルプを見つけやすくするための新しいヘルプページ（doc/help.html）の追加と、プロジェクトページ（doc/contrib.html）およびドキュメントインデックスページ（doc/docs.html）の更新が含まれています。これらの変更は、Goコミュニティのリソースへのアクセスを改善し、ドキュメントの整理を目的としています。

コミット

コミットハッシュ: 539178bd01336824453cc82de6a7181c7a28a7f7
作者: Andrew Gerrand adg@golang.org
コミット日時: 2012年3月5日月曜日 15:07:43 +1100

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

https://github.com/golang/go/commit/539178bd01336824453cc82de6a7181c7a28a7f7

元コミット内容

doc: add help page, update project page

R=golang-dev, kyle, r, bradfitz
CC=golang-dev
https://golang.org/cl/5729053

変更の背景

このコミットの背景には、Go言語プロジェクトの成長と、それに伴うユーザーサポートおよびコミュニティエンゲージメントの重要性の高まりがあります。オープンソースプロジェクトでは、ユーザーが問題に直面した際に適切な情報源やコミュニティサポートに迅速にアクセスできることが極めて重要です。

ヘルプアクセスの改善: Go言語のユーザーベースが拡大するにつれて、FAQ、Wiki、メーリングリスト、IRCチャンネル、ソーシャルメディアなど、様々なヘルプリソースが散在するようになりました。これらのリソースを一元的にまとめたヘルプページを設けることで、新規ユーザーや既存ユーザーが困ったときに、どこに助けを求めればよいかを明確にすることが目的です。
プロジェクト情報の整理: contrib.html（貢献者向け情報やプロジェクトリソースをまとめたページ）は、プロジェクトの進化とともに内容が追加・変更されてきました。このコミットでは、情報の重複を避け、より論理的な構造に再編成することで、ユーザーが求める情報を見つけやすくすることを目指しています。特に、開発者向けリソースとコミュニティ関連リソースを明確に分離し、関連性の高い情報を集約しています。
ドキュメントの一貫性: 既存のドキュメントページ（docs.html）から重複する情報（特にGo Wikiへのリンク）を削除し、新しく追加されるhelp.htmlにその役割を移管することで、ドキュメント全体の一貫性と保守性を向上させています。

これらの変更は、Goプロジェクトのドキュメントがユーザーフレンドリーであり続け、コミュニティの健全な成長を促進するための継続的な取り組みの一環です。

前提知識の解説

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

Go言語プロジェクトのドキュメント構造: Go言語の公式ドキュメントは、主にHTMLファイルで構成されており、これらはGoのウェブサイト（golang.org）上で公開されています。これらのHTMLファイルは、Goのソースコードリポジトリの一部として管理されています。各HTMLファイルには、のような特殊なコメントが含まれており、これはドキュメントのタイトルやURLパスを定義するためのメタデータとして機能します。
バージョン管理システム (Git): GoプロジェクトはGitを使用してソースコードを管理しています。コミットは、コードベースに加えられた変更の単位であり、特定の変更セット、作者、日時、コミットメッセージ、および変更されたファイルの一覧を含みます。
オープンソースプロジェクトにおけるドキュメントの重要性: オープンソースプロジェクトでは、コードだけでなく、質の高いドキュメントが不可欠です。ドキュメントは、プロジェクトの目的、使用方法、貢献方法、トラブルシューティングなどを説明し、ユーザーや貢献者がプロジェクトに参加しやすくするために重要な役割を果たします。特に、ヘルプやコミュニティリソースへの明確なガイドは、ユーザーの定着とコミュニティの活性化に直結します。
コミュニティツール: オープンソースプロジェクトでは、ユーザーや開発者間のコミュニケーションのために様々なツールが利用されます。
- メーリングリスト: golang-nuts (一般議論), golang-dev (開発者議論), golang-checkins (コミット通知) など、特定のトピックに特化した電子メールベースの議論グループ。
- IRC (Internet Relay Chat): リアルタイムチャットのためのプロトコル。#go-nutsのようなチャンネルで即座のサポートや議論が行われます。
- Wiki: コミュニティによって共同で編集される情報サイト。FAQ、ハウツーガイド、ベストプラクティスなどがまとめられます。
- ソーシャルメディア: Google+ (当時), Twitter など、プロジェクトの最新情報やコミュニティの交流に利用されます。
- ビルドステータス: プロジェクトの自動テストやビルドの状況を示すダッシュボード。開発者がコード変更の健全性を確認するために重要です。

技術的詳細

このコミットは、主にGo言語の公式ドキュメントを構成するHTMLファイルのコンテンツと構造を変更しています。

doc/help.html の新規追加:
- このファイルは、Goに関するヘルプを求めるユーザーのための新しいランディングページとして作成されました。
- タイトルは「Getting Help」、パスは/help/として定義されています。
- コンテンツには、以下の主要なヘルプリソースへのリンクが含まれています。
  - Go FAQ (Frequently Asked Questions)
  - Go Language Community Wiki
  - Go Nuts Mailing List (アーカイブ検索と投稿前のFAQ/Wiki参照を推奨)
  - Go IRC Channel (#go-nuts on irc.freenode.net)
  - @go_nuts at Twitter (ツイート時に#golangハッシュタグの使用を推奨)
  - The Go Programming Language at Google+ (当時のGoogle+ページ)
- このページは、ユーザーがGoに関する疑問を解決するための最初の一歩となることを意図しています。
doc/contrib.html の変更:
- このファイルは、Goプロジェクトへの貢献方法や開発者向けリソースをまとめたページです。
- 変更の主な目的は、情報の再編成とコミュニティ関連リソースの追加です。
- コンテンツの再編成:
  - 既存の「The Go Project」セクションが削除され、Goがオープンソースプロジェクトであり、Googleと多くの貢献者によって開発されていること、およびBSDスタイルのライセンスで配布されていることに関する簡潔な説明が冒頭に追加されました。
  - 「Developer Resources」セクションが導入され、ソースコード、リリース履歴、週次スナップショット履歴、開発者メーリングリスト、チェックインメーリングリストがこのセクションにまとめられました。
  - 「Build Status」へのリンクが、「The Go Project」セクションから「Developer Resources」セクション内のより適切な位置に移動されました。
  - 「How you can help」セクションはそのまま維持され、課題報告やコード貢献に関する情報が含まれています。
  - 「The Go Community」という新しいセクションが追加され、Go Nuts Mailing List、Go Project Dashboard、Go IRC Channel、Google+ページ、Twitterアカウント、Go Blogといったコミュニティ関連のリソースがここに集約されました。これにより、開発者向けリソースとコミュニティ向けリソースが明確に分離され、情報の見つけやすさが向上しました。
- 重複の解消: doc/docs.htmlから移動されたコミュニティ関連のリンクが追加されました。
doc/docs.html の変更:
- このファイルは、Goの主要なドキュメントへのリンクをまとめたインデックスページです。
- 変更は主に、情報の重複を解消し、新しく追加されたdoc/help.htmlとの役割分担を明確にすることに焦点を当てています。
- 「Go Language Community Wiki」へのリンクが、より簡潔な説明に変更され、doc/help.htmlに主要なリンクが移管されました。
- 「Go Project Dashboard」と「Go IRC Channel」へのリンクが削除されました。これらの情報は、doc/contrib.htmlの「The Go Community」セクション、または新しく追加されたdoc/help.htmlに集約されることになります。これにより、docs.htmlは純粋に主要なドキュメントへのリンク集としての役割に特化されます。

全体として、このコミットはGoプロジェクトのドキュメント構造を改善し、ユーザーがGoに関する情報やサポートをより効率的に見つけられるようにするための、体系的な取り組みを示しています。

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

このコミットでは、以下の3つのHTMLファイルが変更されています。

doc/contrib.html:
- The Go Projectの見出しが削除され、Goプロジェクトの概要とライセンスに関する簡潔な段落が追加されました。
- Developer Resourcesという新しい見出しが追加され、その下に開発者向けの各種リソース（ソースコード、リリース履歴、週次スナップショット履歴、メーリングリスト、ビルドステータスなど）が再配置されました。
- Build Statusのリンクが移動されました。
- The Go Communityという新しい見出しが追加され、その下にGo Nuts Mailing List、Go Project Dashboard、Go IRC Channel、Google+ページ、Twitterアカウント、Go Blogといったコミュニティ関連のリソースが追加されました。
- 合計で48行が追加され、6行が削除されました。
doc/docs.html:
- Go Language Community Wikiの記述が簡略化されました。
- Go Project DashboardとGo IRC Channelへのリンクが削除されました。
- 合計で1行が追加され、4行が削除されました。
doc/help.html:
- このファイルは新規作成されました。
- Goに関するヘルプを見つけるための各種リソース（FAQ、Wiki、メーリングリスト、IRC、Twitter、Google+）へのリンクを含むHTML構造が定義されています。
- 合計で36行が追加されました。

具体的な差分は以下の通りです（抜粋）。

doc/contrib.html の差分例:

--- a/doc/contrib.html
+++ b/doc/contrib.html
@@ -3,19 +3,27 @@
 	"Path": "/project/"
 }-->
 
-<h2 id="the_go_project">The Go Project</h2>
+<div id="manual-nav"></div>
+
+<p>
+Go is an open source project developed by a team at
+<a href="http://google.com/">Google</a> and many
+<a href="/CONTRIBUTORS">contributors</a> from the open source community.
+</p>
+
+<p>
+Go is distributed under a <a href="/LICENSE">BSD-style license</a>.
+</p>
+
+<h2 id="resources">Developer Resources</h2>
 
 <h3 id="source"><a href="https://code.google.com/p/go/source">Source Code</a></h3>
 <p>Check out the Go source code.</p>
 
-<h3 id="build_status"><a href="http://build.golang.org/">Build Status</a></h3>
-<p>View the status of Go builds across the supported operating
-systems and architectures.</p>
-
 <h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3>
 <p>A summary of the changes between Go releases.</p>
 
-<h3 id="release"><a href="/doc/devel/weekly.html">Weekly Snapshot History</a></h3>
+<h3 id="weekly"><a href="/doc/devel/weekly.html">Weekly Snapshot History</a></h3>
 <p>A summary of the changes between weekly snapshots of Go.</p>
 
 <h3 id="golang-dev"><a href="http://groups.google.com/group/golang-dev">Developer Mailing List</a></h3>
@@ -27,6 +35,11 @@ href="http://groups.google.com/group/golang-nuts">golang-nuts</a>.</p>
 <h3 id="golang-checkins"><a href="http://groups.google.com/group/golang-checkins">Checkins Mailing List</a></h3>
 <p>A mailing list that receives a message summarizing each checkin to the Go repository.</p>
 
+<h3 id="build_status"><a href="http://build.golang.org/">Build Status</a></h3>
+<p>View the status of Go builds across the supported operating
+systems and architectures.</p>
+
+
 <h2 id="howto">How you can help</h2>
 
 <h3><a href="http://code.google.com/p/go/issues">Reporting issues</a></h3>
@@ -59,3 +72,26 @@ open issues that interest you. Those labeled
 <a href="http://code.google.com/p/go/issues/list?q=status=HelpWanted\">HelpWanted</a>
 are particularly in need of outside help.\n </p>\n+\n+\n+<h2 id="community">The Go Community</h2>\n+\n+<h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>\n+<p>The <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a> \n+mailing list is for general Go discussion.</p>\n+\n+<h3 id="projects"><a href="http://godashboard.appspot.com/project">Go Project Dashboard</a></h3>\n+<p>A list of external Go projects including programs and libraries.</p>\n+\n+<h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>\n+<p><b>#go-nuts</b> on <b>irc.freenode.net</b> is the official Go IRC channel.</p>\n+\n+<h3 id="plus"><a href="https://plus.google.com/101406623878176903605/posts">The Go Programming Language at Google+</a></h3>\n+<p>The Go project\'s Google+ page.</p>\n+\n+<h3 id="twitter"><a href="http://twitter.com/go_nuts">@go_nuts at Twitter</a></h3>\n+<p>The Go project\'s official Twitter account.</p>\n+\n+<h3 id="blog"><a href="http://blog.golang.org/">The Go Blog</a></h3>\n+<p>The official blog of the Go project, featuring news and in-depth articles by\n+the Go team and guests.</p>

doc/docs.html の差分例:

--- a/doc/docs.html
+++ b/doc/docs.html
@@ -66,7 +66,7 @@ Answers to common questions about Go.
 </p>
 
 <h3 id="wiki"><a href="http://code.google.com/p/go-wiki/wiki">Go Language Community Wiki</a></h3>
-<p>A wiki full of useful information maintained by the Go community.</p>
+<p>A wiki maintained by the Go community.</p>
 
 <h2 id="articles">Go Articles</h2>
 
@@ -186,9 +186,6 @@ mailing list is for general Go discussion.</p>
 <h3 id="projects"><a href="http://godashboard.appspot.com/project">Go Project Dashboard</a></h3>
 <p>A list of external Go projects including programs and libraries.</p>
 
-<h3 id="wiki"><a href="http://code.google.com/p/go-wiki/wiki">Go Language Community Wiki</a></h3>
-<p>A wiki full of useful information maintained by the Go community.</p>
-
 <h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>
 <p><b>#go-nuts</b> on <b>irc.freenode.net</b> is the official Go IRC channel.</p>

doc/help.html の新規追加内容 (抜粋):

<!--{
	"Title": "Getting Help",
	"Path": "/help/"
}-->

<p>
Need help with Go? Try these resources.
</p>

<div id="manual-nav"></div>

<h3 id="go_faq"><a href="/doc/go_faq.html">Frequently Asked Questions (FAQ)</a></h3>
<p>Answers to common questions about Go.</p>

<h3 id="wiki"><a href="http://code.google.com/p/go-wiki/wiki">Go Language Community Wiki</a></h3>
<p>A wiki maintained by the Go community.</p>

<h3 id="mailinglist"><a href="http://groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
<p>
Search the <a href="http://groups.google.com/group/golang-nuts">golang-nuts</a>
archives and consult the <a href="/doc/go_faq.html">FAQ</a> and
<a href="http://code.google.com/p/go-wiki/wiki">wiki</a> before posting.
</p>

<h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>
<p>Get live support at <b>#go-nuts</b> on <b>irc.freenode.net</b>, the official
Go IRC channel.</p>

<h3 id="twitter"><a href="http://twitter.com/go_nuts">@go_nuts at Twitter</a></h3>
<p>The Go project's official Twitter account.</p>
<p>Tweeting your about problem with the <code>#golang</code> hashtag usually
generates some helpful responses.</p>

<h3 id="plus"><a href="https://plus.google.com/101406623878176903605/posts">The Go Programming Language at Google+</a></h3>
<p>The Go project's Google+ page.</p>

コアとなるコードの解説

このコミットの核となる変更は、Goプロジェクトのドキュメントにおける情報アーキテクチャの改善です。

doc/help.html の導入:
- この新しいページは、Goに関するあらゆる種類のヘルプを求めるユーザーのための単一のエントリポイントとして機能します。以前は、FAQ、Wiki、メーリングリストなどの情報が異なるページに散らばっていた可能性がありますが、help.htmlはこれらを一箇所に集約することで、ユーザーの利便性を大幅に向上させます。
- 特に、メーリングリストへの投稿前にFAQやWikiを参照することを促す記述は、コミュニティの負担を軽減し、より効率的なサポートフローを確立するためのベストプラクティスを反映しています。
- IRCやTwitterといったリアルタイム性の高いコミュニケーションチャネルへの言及は、ユーザーが迅速な回答を得るための選択肢を提供します。
doc/contrib.html の再編成:
- このページの変更は、Goプロジェクトへの貢献を考えている開発者や、プロジェクトの内部リソースに関心のあるユーザーにとって、情報の見つけやすさを向上させることを目的としています。
- 「Developer Resources」と「The Go Community」という明確なセクション分けは、開発者向けの技術的なリソース（ソースコード、ビルドステータスなど）と、より広範なコミュニティ活動（メーリングリスト、SNSなど）を区別し、それぞれのターゲットユーザーが求める情報に素早くたどり着けるように設計されています。
- 「Build Status」のような重要な開発者向け情報が適切なセクションに移動されたことで、ドキュメント全体の論理的な整合性が高まりました。
doc/docs.html の整理:
- このページからの重複するコミュニティ関連リンクの削除は、ドキュメント全体の一貫性を保つ上で重要です。docs.htmlはGoの主要なドキュメントへのリンク集としての役割に特化され、コミュニティやヘルプに関する情報はcontrib.htmlやhelp.htmlに集約されることで、各ページの役割が明確になります。これにより、ユーザーはどのページでどのような情報が得られるかを直感的に理解できるようになります。

これらの変更は、単にコンテンツを追加・移動するだけでなく、Goプロジェクトのドキュメントがより構造化され、ユーザーフレンドリーになるように、情報アーキテクチャの観点から慎重に設計されたものです。これにより、Goコミュニティの成長と、ユーザーおよび貢献者のエンゲージメントが促進されることが期待されます。

参考にした情報源リンク

コミットデータ: /home/orange/Project/comemo/commit_data/12362.txt
GitHubコミットページ: https://github.com/golang/go/commit/539178bd01336824453cc82de6a7181c7a28a7f7
一般的なオープンソースプロジェクトのドキュメントとコミュニティに関する知識。
HTMLの基本的な構造とウェブページの構成に関する知識。

Keyboard shortcuts

comemo