code review 6868071: godoc: move example list into index section

godoc: move example list into index section

Putting it before the Index (where it is now) is wrong:
we don't even know what's in the package yet.

Fixes issue 4484.

[rsc, 2012-12-05 16:39:09]

Hello adg (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://go.googlecode.com/hg/

[adg, 2012-12-10 04:21:21]

We changed this a while back to make the examples more discoverable. This
restores the earlier behavior. Hm.

[rsc, 2012-12-10 06:44:31]

The new layout makes the list visible always, at the bottom of the
index, instead of being something you have to toggle. So it should
still be more discoverable than what we had 1 iteration ago. But
putting the examples before the index is putting the cart before the
horse.

[dsymonds, 2012-12-10 08:25:24]

On Mon, Dec 10, 2012 at 5:44 PM, Russ Cox <rsc@golang.org> wrote:

> The new layout makes the list visible always, at the bottom of the
> index, instead of being something you have to toggle. So it should
> still be more discoverable than what we had 1 iteration ago. But
> putting the examples before the index is putting the cart before the
> horse.

The problem was for big packages (net/http, os, and so on), where the
index is very long. We found that casual browsers never scrolled all
the way to the bottom of the index to find the examples, and were thus
struggling to get a grip on how to use the package.

I don't think this is a case of cart before horse. Package doc pages
aren't stories that gradually develop; they are reference material.
Experienced folk will jump straight for what they are looking for
(either via index, or Ctrl+F), and new folk can get a handle on a
package by getting the examples up front.

[rsc, 2012-12-10 14:45:17]

> The problem was for big packages (net/http, os, and so on), where the
> index is very long. We found that casual browsers never scrolled all
> the way to the bottom of the index to find the examples, and were thus
> struggling to get a grip on how to use the package.

The word Examples still shows up in the mini-index.

> I don't think this is a case of cart before horse. Package doc pages
> aren't stories that gradually develop; they are reference material.
> Experienced folk will jump straight for what they are looking for
> (either via index, or Ctrl+F), and new folk can get a handle on a
> package by getting the examples up front.

I disagree.
Package docs are also how you learn how to use the package.
If they were purely reference there'd be no problem with having the
overview at the end of the page, and yet no one thinks that is a good idea.

Russ

[adg, 2012-12-11 00:51:17]

LGTM

[rsc, 2012-12-11 01:20:08]

*** Submitted as https://code.google.com/p/go/source/detail?r=7b9e9fc59eb5 ***

godoc: move example list into index section

Putting it before the Index (where it is now) is wrong:
we don't even know what's in the package yet.

Fixes issue 4484.

R=adg, dsymonds
CC=golang-dev
https://codereview.appspot.com/6868071