[rorrr]

> Go nails code [cut] documentation better than any other language I'm aware of.

That's because you haven't seen PHP's documentation.

Look at your Go's list example.

It doesn't even show how to create a list and fill it with items.

It doesn't have users' comments.

It doesn't explain much about the data structure. Can it be a circular doubly link list, for instance?

Is there a method to empty the list, or quickly insert more than one element?

Instead it has strangely named sections (like "type Element") that aren't obvious to somebody new to the language.

Sorry, but this documentation is shit.

[sambeau]

  "Sorry, but this documentation is shit."

Woah. That's way off the mark. I'm currently having to use both the Go documentation and the PHP documentation and I will take the Go docs anytime.

Yes, they are short of useful examples but, then, so are the PHP docs. Worse than that I find most of the user comments on the PHP docs are noise: self-proclaimed PHP gurus trying to out-clever each other.

The Go Library docs have one major advantage: you can click on the supplied link to see the simple, understandable implementation.

[enneff]

That's a bit harsh. Library docs are for users of the language. I grant that the list package could use more docs (I personally find it a bad example) but for someone who knows Go, all the important stuff is there.

Juba surprised that you rate the PHP docs so highly, particularly the user comments. Typically those comments contain terrible advice!

[rorrr]

Users' comments are important to figure out unusual behaviors, bugs, edge cases, to clarify documentation in general, and to add code examples. Of course, some of them will be incorrect and bad advice, that's why I think PHP docs should add up/down voting on each post.

More than anything, it creates the sense of community. You always know there are people reading and writing stuff about a specific method, and, most of the time, it's helpful.

Considering how bad and inconsistent PHP is, their documentation is amazing.

[codygman]

Documentation is for documentation by the people who implement the language and know how it should be best used. User comments on official documentation are likely to have tons of different coding styles, so a new user would pick up a lot of bad habits.

If all of the docs are written by go developers/contributors who know that the code in examples should be consistent, then all those bad habits aren't ingrained in new users.

Something golang has that I don't know anyone else has is this:

http://talks.golang.org/2012/concurrency.slide#1

Also another thing about Go, is the source code for each of those packages is extremely easy to understand... it's truly self documenting... there's also the option of looking at the list_test.go file.

I will admit a method to empty the list as well as insert more than one element would be nice.