Perhaps saying the docs are categorically terrible is too critical to elicit anything other than emotional responses, but put that in the context of me and my team having spent hours laboring over what should have been trivial tasks, and when developers are turning in huge time sheets AND scripts written in other languages (completed on their own time) that accomplish the same tasks that we have still failed to accomplish in Go, it's demoralizing and it indicates problems with the docs.
I'm happy to elaborate with specific examples, but first, let me frame this around the concept of education and teaching. The Go docs are good at being a dictionary reference, but as anyone who has travelled abroad and learned to speak another language can tell you, a dictionary reference is not the most important thing to have: the most important reference is a phrasebook. Nothing wrong with the dictionary, but it is in fact secondary (especially to newcomers).
So in addition to #learning and #references being the core roles of the docs, I would include #usage as well (i.e. the phrasebook). In practice, the phrasebook functionality usually gets merged in with the reference material. To clarify my frustration, it is the features of the phrasebook that I feel are largely missing from the current Go docs, and that's what I feel is a huge impediment to learning the language.
Having experience as a technical writer, a translator, and an instructor at the university level, I cannot overstate the importance of having these "phrases" to work with. They become "thinking units", and they cement the cursory lessons outlined in the #learning articles AND they form the foundation of everything else that follows. They are the underlying currency that enables learning of any language or skill -- some parts of the Go docs are bankrupt.
Imagine the absurdity of teaching a baby to speak by reading it dictionary definitions A to Z. And who has ever had a music lesson where instead of learning to play the instrument, you get your ears talked off about chromaticism, major scales, and enharmonic equivalents? The article I linked to was especially apt about this music analogy (http://stevelosh.com/blog/2013/09/teach-dont-tell/
). And who doesn't remember those futile days from elementary school when you would go to look up a word like "solipsistic" in the big dead-tree dictionary, and finding the definition would be a wild goose chase starting with "a person who follows the principles of solipsism" etc. While living abroad, I was so glad when I discovered a dictionary by Pon's that gave real functional definitions of each word. It's such a simple idea, but it's so effective. I would even put money on it: give one set of developers the old-school dictionary documentation, give another the "phrasebook" style docs and I have little doubt which group would complete their tasks faster. It's important to consider that virtually no programmer ever undertakes to learn every function in a language -- it's nearly always a hunt for "how do I do this?" I.e. it's a phrasebook question, not a dictionary one, so to me it seems inappropriate to devote docs to a dictionary structure when that isn't representative of their primary usage.
Two common mistakes that I would warn against here were covered in Act 1 and Act 2 of the article: Source Code and Tests cannot substitute for documentation. No harm in linking to it, but it fills a different need and fundamentally it's ineffective as a teaching strategy for beginners. Why? Because most often, the source code and the tests are MORE complex with more moving parts, so to understand what's going on, you need to have a broader background. Maybe the user doesn't understand exactly how tests work or maybe it's using some construct that's unfamiliar to the specific problem at hand. Sure, having that perspective can help, but in order to provide a functional example (i.e. a phrasebook entry), the code needs to be reduced to the simplest possible example, where complexity is REMOVED, not added.
I'm not suggesting anything new: it's a formula that has worked successfully for many other languages. E.g. consider your humble man page, and that it's no accident that many languages include the same basic segments in their docs. Broadly speaking, Perl, PHP, Java docs have these sections:
- SYNOPSIS - function usage + signature
- See Also
Go follows some of this at the package level, but zooming into the function level gets grainy. By contrast, PHP implements this very well in my opinion (and I contend it has absolutely nothing to do with its architecture): the PHP docs include a detailed description of the PARAMETERS and output value (which is less important in Go), but they include the all important section for EXAMPLES, SEE ALSO, and USER CONTRIBUTED NOTES. Go misses out a lot of explanations by being too concise with its parameters: knowing an argument's data type is not enough information to know how to use it.
So, now that I've laid out a bit more of the philosophy behind useful documentation, I can include some general comments that apply to everything in the Go docs:
1. Include a link for feedback on the documentation. If it's managed via a github repo, include a link to it there, so at the very least, interested users could fork it and submit pull requests. It's not clear at the moment where one could submit changes if they wanted to.
2. Explain any abbreviations. I understand the desire to shorten code, but when abbreviations are used in package, function, and variable names, it would prevent a lot of mental friction to be clear as to what those terse tidbits were referring to.
3. Describe the parameters in meaningful ways. It is not enough to know the data types: it takes several trips to the playground to do variations on the inputs to see what affect they have. Why not just save the time and include the inputs and outputs next to different options?
4. Include examples for each function. If there's not an example for a function, there probably should be. This one thing alone would revolutionize the docs.
Already, we can see there are no examples here, making it tough for a newcomer to follow along with. For example, it's not clear that the functions that are listed here need to be prefixed with the "hex." prefix. Yes, that's a simple language thing, but if it's not re-enforced in the documentation with a few examples, it takes that much longer to learn.
Consider this (BAD/CONFUSING):
var ErrLength = errors.New("encoding/hex: odd length hex string")
What is that? My first assumption is that this is some type of package variable because it's under the "Variables" heading. It's only by comparing this to other packages that I can guess that this is a reference to a particular error message. But without an example to see how it might arise, I have no idea what to do with this info or what exactly it pertains to.
BETTER: include an example of working with the returned variables to see how/why they might be relevant or omit this entirely and just list the message strings.
BAD: func Dumper
This "crosses the beams" by referencing another package: "io". Without an example to work off of, it's not clear how one might instantiate an io.Writer or what might be done with an io.WriteCloser. We end up banging our heads on a different wall over at the "io" docs.
BETTER: include an example here so we aren't on a wild goose chase to figure out how to instantiate io.Writer objects.
BAD: func DecodeString
Again, no example, so immediately I have to pay the toll of fiddling with this to see how it works. Perhaps an example like this:
bytes, _ := hex.DecodeString("AE")
fmt.Println(hex.EncodeToString(bytes)) // ae (lowercase)
It might be worth mentioning that the output is always lowercase, and it would be good to explain the behavior that pops up if your input is out of range, e.g. "XX". This is why it would be useful to describe the parameters and output in their own dedicated sections.
BAD: func Decode
The explanation includes "Decode decodes src into DecodedLen(len(src)) bytes" -- nesting like that is more concise, but it's harder to follow. I'm not entirely sure I understand what this function does. Again, an example would help clarify this more than paragraphs of text.
Similar comments would apply to https://golang.org/pkg/strconv/
(or indeed, to every single bit of Go documentation I have looked at over the past 2 weeks).
In conclusion, I think that the current organization and terseness of the docs really does affect usability of Go, and I would love to see the organizational strategy changed to something with more meat to it (e.g. the man page format) so that those developers who need additional explanations and examples can have them to work with. That's really the best way to ensure idiomatic code writing: via repetitive demonstrations of it.