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

このコミットは、Go言語の公式ドキュメントの一部である doc/install.html ファイルに対する変更です。具体的には、Go言語のインストール手順を説明するページのコンテンツが更新されており、ユーザーがより素早く、効率的に情報を把握できるよう、ドキュメントの可読性とユーザビリティの向上を目的としています。

コミット

• コミットハッシュ: ce06e15e2a74de89d13e648760f75da7262d0149
• 作者: Andrew Gerrand adg@golang.org
• コミット日時: 2012年3月26日 月曜日 13:59:30 +1100
• 変更ファイル: doc/install.html (1ファイル)
• 変更行数: 14行追加, 10行削除

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

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

元コミット内容

doc: make installation instructions more skim-friendly

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5908052

変更の背景

このコミットの主な背景は、Go言語のインストール手順に関する公式ドキュメントのユーザビリティ向上です。当時のドキュメントは、見出しが説明的すぎたり、ダウンロードリンクが直接提供されていなかったりする点が、新規ユーザーにとって情報の把握を妨げる可能性がありました。

コミットメッセージにある「skim-friendly」（流し読みしやすい）という言葉が示す通り、ユーザーがドキュメント全体を詳細に読むことなく、必要な情報（特にダウンロードとインストールに関するアクション）を素早く見つけられるようにすることが目的でした。具体的には、以下の点が改善の対象となりました。

1. 見出しの明確化: 各セクションの目的をより行動指向の言葉で表現することで、ユーザーがドキュメントをスキャンする際に、次に何をすべきかを直感的に理解できるようにする。
2. ダウンロードプロセスの簡素化: 各OS向けのGoバイナリのダウンロードページへの直接リンクを提供することで、ユーザーが別途ダウンロードページを探す手間を省き、インストールプロセスをよりスムーズにする。

これらの変更により、Go言語の導入障壁を低減し、より多くのユーザーが簡単にGoを使い始められるようにすることが意図されています。

前提知識の解説

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

• Go言語 (Golang): Googleによって開発されたオープンソースのプログラミング言語です。シンプルさ、効率性、並行処理のサポートを特徴とし、Webサービス、ネットワークプログラミング、CLIツールなど幅広い分野で利用されています。
• ドキュメンテーション (Documentation): ソフトウェアやシステムの使用方法、機能、設計などを説明する文書群のことです。公式ドキュメントは、ユーザーがソフトウェアを正しく理解し、利用するために不可欠な情報源となります。
• HTML (HyperText Markup Language): Webページの構造と内容を記述するための標準的なマークアップ言語です。このコミットでは、HTMLファイル（doc/install.html）が直接編集されています。
  • <h2> タグ: HTMLにおけるセクションの主要な見出し（レベル2）を表します。
  • <a> タグ: ハイパーリンクを作成するために使用されます。href属性でリンク先URLを指定します。
  • <pre> タグ: 整形済みテキストを表示するために使用され、通常はコードブロックやアスキーアートなどに用いられます。
• ユーザビリティ (Usability): 製品やシステムが、特定のユーザーによって、特定の目的を達成するために、どれだけ効果的に、効率的に、そして満足して使用できるかの度合いを指します。このコミットは、ドキュメントのユーザビリティ向上に焦点を当てています。
• UX (User Experience): ユーザーが製品やサービスを利用する際に得られる全体的な体験のことです。ドキュメントの改善は、Go言語のインストールという初期のUXに直接影響を与えます。
• スキムリーディング (Skim Reading): 文書全体をざっと読んで、主要なアイデアや情報を素早く把握する読書方法です。このコミットの目的である「skim-friendly」とは、この読書方法に適したドキュメント構造を意味します。

技術的詳細

このコミットにおける技術的な変更は、doc/install.html という単一のHTMLファイルに集中しています。変更の核心は、ドキュメントの構造とナビゲーションを改善し、ユーザーがGo言語のインストールプロセスをより直感的に進められるようにすることです。

具体的には、以下の点が変更されています。

1. 見出しの変更:

   • <h2>Obtaining the Go tools</h2> が <h2>Download the Go tools</h2> に変更されました。
   • <h2>Installing the Go tools</h2> が <h2>Install the Go tools</h2> に変更されました。
   • <h2>Testing your installation</h2> が <h2>Test your installation</h2> に変更されました。 これらの変更は、見出しをより動詞的で行動指向な表現にすることで、ユーザーがドキュメントを流し読みする際に、各セクションがどのようなアクションを要求しているのかを瞬時に理解できるようにすることを目的としています。例えば、「Obtaining (取得する)」よりも「Download (ダウンロードする)」の方が、ユーザーにとって具体的な行動を促す表現となります。

2. ダウンロードリンクの追加:

   • Linux/FreeBSDセクションにおいて、tar -C /usr/local -xzf go.release.go1.tar.gz の説明の前に、Goのダウンロードリストページへの直接リンクが追加されました。これにより、ユーザーはドキュメントを読み進めながら、必要なアーカイブファイルをすぐにダウンロードできるようになります。

     Extract <a href="http://code.google.com/p/go/downloads/list?q=OpSys-FreeBSD+OR+OpSys-Linux">the archive</a>
     into <code>/usr/local</code>, creating a Go tree in <code>/usr/local/go</code>:
     

   • Mac OS Xセクションにおいて、.pkg ファイルの説明に、Mac OS X向けのパッケージファイルダウンロードページへの直接リンクが追加されました。

     Open the <a href="http://code.google.com/p/go/downloads/list?q=OpSys-Darwin">package file</a>
     and follow the prompts to install the Go tools.
     

   • Windows MSIインストーラセクションにおいて、.msi ファイルの説明に、Windows MSIインストーラダウンロードページへの直接リンクが追加されました。

     Open the <a href="http://code.google.com/p/go/downloads/list?q=OpSys-Windows+Type%3DInstaller">MSI file</a>
     and follow the prompts to install the Go tools.
     

   • Windows Zipアーカイブセクションにおいて、.zip ファイルの説明に、Windows Zipアーカイブダウンロードページへの直接リンクが追加されました。

     Extract the <a href="http://code.google.com/p/go/downloads/list?q=OpSys-Windows+Type%3DArchive">ZIP file</a>
     to the directory of your choice (we suggest <code>c:\Go</code>).
     

   これらのリンク追加により、ユーザーはドキュメント内で必要なダウンロードファイルを見つけるためのナビゲーションが大幅に簡素化され、インストールプロセス全体がよりスムーズになります。

3. 段落の整形:

   • (Typically these commands must be run as root or through <code>sudo</code>.) という注意書きが、前の段落から独立した新しい段落として配置されました。これにより、この重要な注意書きがより目立つようになり、可読性が向上しています。

これらの変更は、HTMLの基本的な要素（見出し、リンク、段落）を効果的に利用して、ドキュメントの構造とコンテンツフローを最適化し、ユーザーエクスペリエンスを向上させる典型的な例と言えます。

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

doc/install.html ファイルにおける主要な変更箇所は以下の通りです。

--- a/doc/install.html
+++ b/doc/install.html
@@ -24,7 +24,7 @@
 <a href="/doc/install/gccgo">Setting up and using gccgo</a>.
 </p>
 
-<h2 id="download">Obtaining the Go tools</h2>
+<h2 id="download">Download the Go tools</h2>
 
 <p>
 Visit the
@@ -47,7 +47,7 @@
 OS/arch combination you may want to try
 <a href="/doc/install/gccgo">installing gccgo instead of gc</a>.
 </p>
 
-<h2 id="install">Installing the Go tools</h2>
+<h2 id="install">Install the Go tools</h2>
 
 <p>
 The Go binary distributions assume they will be installed in
@@ -84,15 +84,17 @@
 rm -r /usr/local/go
 </pre>
 
 <p>
-Extract the archive into <code>/usr/local</code>, creating a Go tree in
-<code>/usr/local/go</code>:\n
+Extract <a href="http://code.google.com/p/go/downloads/list?q=OpSys-FreeBSD+OR+OpSys-Linux">the archive</a>
+into <code>/usr/local</code>, creating a Go tree in <code>/usr/local/go</code>:
 </p>
 
 <pre>
 tar -C /usr/local -xzf go.release.go1.tar.gz
 </pre>
 
-<p>(Typically these commands must be run as root or through <code>sudo</code>.)</p>
+<p>
+(Typically these commands must be run as root or through <code>sudo</code>.)
+</p>
 
 <p>
 Add <code>/usr/local/go/bin</code> to the <code>PATH</code> environment
@@ -107,7 +109,8 @@
 export PATH=$PATH:/usr/local/go/bin
 <h3 id="osx">Mac OS X</h3>
 
 <p>
-Open the <code>.pkg</code> file and follow the prompts to install the Go tools.
+Open the <a href="http://code.google.com/p/go/downloads/list?q=OpSys-Darwin">package file</a>
+and follow the prompts to install the Go tools.
 The package installs the Go distribution to <code>/usr/local/go</code>.
 </p>
 
@@ -129,7 +132,8 @@
 and a zip archive that requires you to set some environment variables.
 <h4 id="windows_msi">MSI installer</h3>
 
 <p>
-Open the <code>.msi</code> file and follow the prompts to install the Go tools.
+Open the <a href="http://code.google.com/p/go/downloads/list?q=OpSys-Windows+Type%3DInstaller">MSI file</a>
+and follow the prompts to install the Go tools.
 By default, the installer puts the Go distribution in <code>c:\Go</code>.
 </p>
 
@@ -142,8 +146,8 @@
 command prompts for the change to take effect.
 <h4 id="windows_zip">Zip archive</h3>
 
 <p>
-Extract the <code>.zip</code> file to the directory of your choice (we
-suggest <code>c:\\Go</code>).
+Extract the <a href="http://code.google.com/p/go/downloads/list?q=OpSys-Windows+Type%3DArchive">ZIP file</a>
+to the directory of your choice (we suggest <code>c:\\Go</code>).
 </p>
 
 <p>
@@ -164,7 +168,7 @@
 versions of Windows provide this control panel through the "Advanced System"
 Settings" option inside the "System" control panel.
 </p>
 
-<h2 id="testing">Testing your installation</h2>
+<h2 id="testing">Test your installation</h2>
 
 <p>
 Check that Go is installed correctly by building a simple program, as follows.

コアとなるコードの解説

このコミットのコアとなるコード変更は、Go言語のインストール手順ドキュメントのユーザビリティを向上させるための、戦略的なHTML要素の調整です。

1. 見出しの変更 (<h2> タグ):

   • 変更前: "Obtaining the Go tools", "Installing the Go tools", "Testing your installation"
   • 変更後: "Download the Go tools", "Install the Go tools", "Test your installation" この変更は、見出しをより動詞的で直接的な表現にすることで、ユーザーがドキュメントを流し読みする際に、各セクションの目的を瞬時に把握できるようにすることを意図しています。例えば、「Goツールを取得すること」という説明的な表現から、「Goツールをダウンロードする」という具体的な行動を促す表現に変わることで、ユーザーは次に何をすべきかを直感的に理解しやすくなります。これは、ドキュメントの「skim-friendly」化に直接貢献しています。

2. ダウンロードリンクの追加 (<a> タグ): 各OS（FreeBSD/Linux, Mac OS X, Windows）のインストール手順の説明箇所に、Goのダウンロードリストページへの直接リンクが追加されました。

   • 変更前は、ユーザーはGoのバイナリをダウンロードするために、別途ダウンロードページにアクセスする必要がありました。
   • 変更後は、ドキュメントを読み進めながら、必要なファイルをすぐにダウンロードできるリンクが提供されるため、ユーザーの作業フローが中断されることなく、よりスムーズにインストールプロセスを進めることができます。これは、ユーザーがドキュメントとダウンロードサイトを行き来する手間を省き、全体的なユーザーエクスペリエンスを向上させる重要な改善です。

3. 段落の整形: Linux/FreeBSDのインストール手順における (Typically these commands must be run as root or through <code>sudo</code>.) という注意書きが、独立した段落として配置されました。これにより、この重要な情報が他のテキストに埋もれることなく、ユーザーの目に留まりやすくなり、コマンド実行時の権限に関する誤解を防ぐのに役立ちます。

これらの変更は、技術的には非常にシンプルですが、ユーザーがGo言語を使い始める際の最初の体験を大幅に改善するという点で、非常に効果的なドキュメントの改善と言えます。

関連リンク

• Go言語公式サイト: https://go.dev/
• Go言語ドキュメント: https://go.dev/doc/
• Go言語ダウンロードページ: https://go.dev/dl/

参考にした情報源リンク

• GitHubコミットページ: https://github.com/golang/go/commit/ce06e15e2a74de89d13e648760f75da7262d0149
• Go言語の公式ドキュメント (一般的な情報源として)