7 ms·

Poor documentation seems to be a Google culture thing. I suspect that's why godoc is literally just source code comments wrapped in HTML.

dan_can_code 6y ago
I have found this to be almost universal when it comes to reading / writing documentation, not just Google. 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.
- scns 6y ago
  There is a name for it: The experts blind spot
  - k00b 6y ago
    I’ve heard it called and prefer to call it the curse of knowledge
  - dan_can_code 6y ago
    Thanks for sharing this with me. I didn't know this was a widely known phenomenon. I'll take a look at the link to help avoid having these blind spots myself, thanks again!
  - dmitriid 6y ago
    Erlang's creator Joe Armstrong once said it like this (quoting from memory) "There's a moment when you go from not getting it to getting it, and you have about 24 hours when you remember both before and after, and that's when you have to write things down. After that you won't remember how it was not getting it"
- virgilp 6y ago
  Rust has pretty decent documentation. 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.
  - dan_can_code 6y ago
    I absolutely agree. There is no reason to settle for anything less. Google certainly has the resources to fill the gap - recognising it would be the first step. Looking at the Go documentation, it seems they have feedback mechanisms for the features of Go, but no means of providing feedback on the actual documentation. Rust however have both Github contributions, as well as a channel on discord specifically for documentation discussions. I would assume this may contribute to the lack of satisfactory documentation for Go.
    - justicezyx 6y ago
      > Google certainly has the resources to fill the gap 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.
    - pjmlp 6y ago
      Try to develop for Android. 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.
- bluGill 6y ago
  People who write code know it too well to write good documentation. You need someone else to come in and write documentation. This is expensive and many/most companies deicde to not hire that person and as a result you get documentation written by people who know the code too well and so they skip many parts as obvious that are not obvious, while going into great detail about esoteric parts that are only rarely used.
  - justicezyx 6y ago
    > People who write code know it too well to write good documentation. 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.
  - 8organicbits 6y ago
    I documented an API a couple years back and then got to see questions from some engineers at another company who were using the tool. 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.
thefounder 6y ago
I can't disagree more.
rob74 6y ago
I've seen projects with much worse documentation than Go. And I think it's unfair to blame the quality of the documentation on godoc, which is actually a pretty powerful documentation tool, and the fact that it's included with the language is a great advantage. As with other aspects of Go, they may have taken the "keep it simple" principle a bit too far here too (e.g. godoc could detect and highlight if you mention the names of a method's parameters in a doc comment), but what's there is very solid. Of course, as with any documentation tool, you have to actually use it by writing good doc comments (end examples, and additional documentation files etc.) to make it useful, but that's not the tool's fault...
- nobleach 6y ago
  Yeah, OCaml's docs are FAR worse as they're often just type signatures. I'm also not a fan of Oracle's Java docs as they do explain what each method does, but often in a rather opaque way. Where Elixir and Kotlin get things right, is they tend to also give quick examples of how one might use any given method.
clinta 6y ago
Isn't that the case with most languages now? Pydoc and rustdoc do the same thing.
- trumpeta 6y ago
  Last time I checked it was not possible to actually use godoc to render the doc, it just started an internal server. That made it super hard to publish docs internally.
jimktrains2 6y ago
Isn't that all javadoc did all those years ago?
- eternalban 6y ago
  Still does. Example: https://docs.oracle.com/en/java/javase/11/docs/api/index.html https://docs.oracle.com/en/java/javase/11/docs/api/index.htm... https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/java/nio/file/package-info.java 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.
  - gostsamo 6y ago
    Isn't emacs the first to do it? I have the vague memory of it self-advertising as self-documenting.
    - eternalban 6y ago
      I don’t know about emacs but your comment prompted a search for Smalltalk-80 docs: http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.pdf 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.
scns 6y ago
In Elixir the code inside comments is tested so it cant go stale.
- Cthulhu_ 6y ago
  In Go the example code is (can be) part of the source as well, and shown as executable in the documentation viewer: https://blog.golang.org/examples https://blog.golang.org/examples
  - jerf 6y ago
    Arguably another feature that could use some shouting from the rooftops. I see it fairly rarely from public packages, and it's something a lot of public packages really ought to have. Little example snippets for specific functions are great, but round-trip, top-to-bottom examples of using your code base are very useful.
Thaxll 6y ago
Most likely people don't know where the doc is, Go documentation for module is excellent: https://github.com/golang/go/wiki/Modules https://github.com/golang/go/wiki/Modules
- mfer 6y ago
  A big problem with this documentation is that it's not with the rest of the docs and isn't found in search on golang.org. 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.
- saturn_vk 6y ago
  But that's not the go modules documentation. That's just some wiki put together with duct tape and good intentions. The real documentation is here: https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more https://golang.org/cmd/go/#hdr-Modules__module_versions__and... and is identical to the output of `go help modules`
jtdev 6y ago
Code never lies, documentation/comments/etc. sometimes do.
- bxparks 6y ago
  Code can be wrong. Documentation/comment can explain what the code was supposed to do.
  - bostik 6y ago
    > was There's the important bit. Code can be wrong, but it gets less out of date than its comments.
jrockway 6y ago
go doc is one of my favorite programming tools. You can get information about any function from the command-line, without having to open a browser or manually grep for what you're looking for. How does strings.Index work? "go doc strings.Index" 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. It even tells you what import statement to use to get the version of the code that you're reading the documentation about. It isn't perfect, but it's my favorite documentation tool and would be my number one reason against switching to another language. (For example, I would kill for this in Typescript.)
- literallycancer 6y ago
  godoc is not go doc

dan_can_code 6y ago

I have found this to be almost universal when it comes to reading / writing documentation, not just Google. 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.

scns 6y ago
There is a name for it: The experts blind spot
- k00b 6y ago
  I’ve heard it called and prefer to call it the curse of knowledge
- dan_can_code 6y ago
  Thanks for sharing this with me. I didn't know this was a widely known phenomenon. I'll take a look at the link to help avoid having these blind spots myself, thanks again!
- dmitriid 6y ago
  Erlang's creator Joe Armstrong once said it like this (quoting from memory) "There's a moment when you go from not getting it to getting it, and you have about 24 hours when you remember both before and after, and that's when you have to write things down. After that you won't remember how it was not getting it"
virgilp 6y ago
Rust has pretty decent documentation. 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.
- dan_can_code 6y ago
  I absolutely agree. There is no reason to settle for anything less. Google certainly has the resources to fill the gap - recognising it would be the first step. Looking at the Go documentation, it seems they have feedback mechanisms for the features of Go, but no means of providing feedback on the actual documentation. Rust however have both Github contributions, as well as a channel on discord specifically for documentation discussions. I would assume this may contribute to the lack of satisfactory documentation for Go.
  - justicezyx 6y ago
    > Google certainly has the resources to fill the gap 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.
  - pjmlp 6y ago
    Try to develop for Android. 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.
bluGill 6y ago
People who write code know it too well to write good documentation. You need someone else to come in and write documentation. This is expensive and many/most companies deicde to not hire that person and as a result you get documentation written by people who know the code too well and so they skip many parts as obvious that are not obvious, while going into great detail about esoteric parts that are only rarely used.
- justicezyx 6y ago
  > People who write code know it too well to write good documentation. 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.
- 8organicbits 6y ago
  I documented an API a couple years back and then got to see questions from some engineers at another company who were using the tool. 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.

thefounder 6y ago

I can't disagree more.

rob74 6y ago

I've seen projects with much worse documentation than Go. And I think it's unfair to blame the quality of the documentation on godoc, which is actually a pretty powerful documentation tool, and the fact that it's included with the language is a great advantage. As with other aspects of Go, they may have taken the "keep it simple" principle a bit too far here too (e.g. godoc could detect and highlight if you mention the names of a method's parameters in a doc comment), but what's there is very solid. Of course, as with any documentation tool, you have to actually use it by writing good doc comments (end examples, and additional documentation files etc.) to make it useful, but that's not the tool's fault...

nobleach 6y ago
Yeah, OCaml's docs are FAR worse as they're often just type signatures. I'm also not a fan of Oracle's Java docs as they do explain what each method does, but often in a rather opaque way. Where Elixir and Kotlin get things right, is they tend to also give quick examples of how one might use any given method.

clinta 6y ago

Isn't that the case with most languages now? Pydoc and rustdoc do the same thing.

trumpeta 6y ago
Last time I checked it was not possible to actually use godoc to render the doc, it just started an internal server. That made it super hard to publish docs internally.

jimktrains2 6y ago

Isn't that all javadoc did all those years ago?

eternalban 6y ago
Still does. Example: https://docs.oracle.com/en/java/javase/11/docs/api/index.html https://docs.oracle.com/en/java/javase/11/docs/api/index.htm... https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/java/nio/file/package-info.java 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.
- gostsamo 6y ago
  Isn't emacs the first to do it? I have the vague memory of it self-advertising as self-documenting.
  - eternalban 6y ago
    I don’t know about emacs but your comment prompted a search for Smalltalk-80 docs: http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.pdf 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.

scns 6y ago

In Elixir the code inside comments is tested so it cant go stale.

Cthulhu_ 6y ago
In Go the example code is (can be) part of the source as well, and shown as executable in the documentation viewer: https://blog.golang.org/examples https://blog.golang.org/examples
- jerf 6y ago
  Arguably another feature that could use some shouting from the rooftops. I see it fairly rarely from public packages, and it's something a lot of public packages really ought to have. Little example snippets for specific functions are great, but round-trip, top-to-bottom examples of using your code base are very useful.

Thaxll 6y ago

Most likely people don't know where the doc is, Go documentation for module is excellent: https://github.com/golang/go/wiki/Modules https://github.com/golang/go/wiki/Modules

mfer 6y ago
A big problem with this documentation is that it's not with the rest of the docs and isn't found in search on golang.org. 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.
saturn_vk 6y ago
But that's not the go modules documentation. That's just some wiki put together with duct tape and good intentions. The real documentation is here: https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more https://golang.org/cmd/go/#hdr-Modules__module_versions__and... and is identical to the output of `go help modules`

jtdev 6y ago

Code never lies, documentation/comments/etc. sometimes do.

bxparks 6y ago
Code can be wrong. Documentation/comment can explain what the code was supposed to do.
- bostik 6y ago
  > was There's the important bit. Code can be wrong, but it gets less out of date than its comments.

jrockway 6y ago

go doc is one of my favorite programming tools. You can get information about any function from the command-line, without having to open a browser or manually grep for what you're looking for. How does strings.Index work? "go doc strings.Index" 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. It even tells you what import statement to use to get the version of the code that you're reading the documentation about. It isn't perfect, but it's my favorite documentation tool and would be my number one reason against switching to another language. (For example, I would kill for this in Typescript.)

literallycancer 6y ago
godoc is not go doc