Poor documentation seems to be a Google culture thing. I suspect that's why godoc is literally just source code comments wrapped in HTML.
I have come to the understanding that to write good documentation, you should write it as soon as you have learned it, or at least, try and explain in a similar way in the way you learned (which is not easy at all). I feel the issue stems from abstraction. Once you become somewhat an expert in a topic or develop a deeper understanding of said topic, you automatically abstract away the information that lead you to that understanding in the first place.
Otherwise you end up reading or writing documentation with a bunch of assumptions for knowledge and understanding, which are not only not stated but may not be available to the person trying to get to grips with the technology. A bit of a digression from the post, but I don't feel this is just a Google thing.
My point is that it's possible/ we shouldn't settle for "that's the universal status quo, nothing can be done about it". Something _can_ be done. And we _should_ be demanding more - especially so from tech giants like Google.
Quite possibly they dont have the resource.
The eng culture today is dominanted by visible impact. Documents are great for everyone, every Googler knows that, but it just cannot be measured.
I wrote some of the most spectacular docs in my previous Google teams. Everyone loves it when they saw them. And no one mentioned them in any formal scenarios. And I am aware of the measurement rules well enough that I didn't bother to waste my time to promote them.
For me, I just care the feelings of the users so much that I personally feels rewarded, but for Google as a whole, there cannot be enough resources for documentation, by the design of the engineering system.
Lots of very relevant details aren't in Android developer documentation, rather scattered around in Stack Overflow, G+ (when it existed), Twitter, Medium or the developer personal blog.
Apparently the team keeps forgeting that Android has its own documentation website.
I doubt this.
Like Eistein said, if you understand something well enough, you will have no problem breaking it down in to simple, easy to digest information.
The idea that someone knows something well enough and therefore not able to write good docs, misses the crux of the problem: The writer here failed to understand his audience.
And when someone is educated to be conscious about their audience, I see no reason why the one knows the system best in any way hindered by his/her knowledge.
I did a good job of documenting how to call each function, but they were actually struggling with how dynamic linking worked in C. At the time, I was surprised and questioned their ability to problem solve.
Looking back now, it's common for engineers to jump between skills and work in unfamiliar places. Adding a simple Makefile example would have helped them immensely, and may have helped others as well.
I disagree that it needs to be someone else, but you need some empathy, and the ability to observe your users struggling to understand how to improve your documentation. You can't write it for yourself and expect it to be helpful to everyone.
The docs provide enough to make modules work but are far from excellent in terms of docs.
These docs also highlight things about how the Go team thinks. For example, if a project is versioned at v2 or later they recommend incrementing the major version of your code when adopting modules. Instead of modules being support tooling for the app it's designed and thought of as important as a major version change.
The real documentation is here: https://golang.org/cmd/go/#hdr-Modules__module_versions__and...
and is identical to the output of `go help modules`
func Index(s, substr string) int
Index returns the index of the first instance of substr in s, or -1 if
substr is not present in s.
Example:
https://docs.oracle.com/en/java/javase/11/docs/api/index.htm...
https://github.com/openjdk/jdk/blob/master/src/java.base/sha...
I think Gophers borrowed the idea of generating docs from header/source comment from Java. Java itself spec'd it in 1996. Where did Gosling and friends got the idea, I don't know. It may have precedents either in Sun's other languages or possibly an earlier precedent.
Some relatively minor differences:
In Go, documentation is externalized IFF top level code (function, type, var defs and declarations) immediately follows a comment line.
In Java comments have two forms. The comment form using two asterisks is externalized.
In Go comments (iirc) support some very basic text styling (of the generated doc).
In Java externalized comments can use a basic set of markup ala HTML. This includes comment level hyperlinks to javadocs of referenced elements.
Having used both languages rather extensively, Go's approach lends itself to CLI usage. Java provides richer markup and hyperlinks via java and is much better for someone who wants to explore the API via documentation.
http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook....
On page 309 the `Metaclass Protocol` is defined. This class has a property “comment” [with value semantic of] ‘commentString’. So possibly they got it from Smalltalk. Don’t know.
sum: xValue with: yValue
"sums two values"
^ xValue + yValue
Several Lisp variants also have a similar approach.
This product probably deserves its own hn post: http://preserve.mactech.com/articles/mactech/Vol.10/10.04/Sm...
There's the important bit. Code can be wrong, but it gets less out of date than its comments.