Hacker News Reader

Comment by grenoire | Hacker News Reader

Re: "They need at the very least a section of the documentation that lays it out clearly and in layman's terms."

As a Go outsider who's trying to get his feet dipped in the lake, trying to use modules has felt... uneasy? I tried to look up the official resources on the matter and found the official blog posts to be lacking concrete and concise examples on the usage; documentation feels like it's written for people who work on the project and already digested the unit tests as examples.

As for the case of v2, similarly messy and undocumented. I also appreciate author's call for action on warning messages in tooling.

Wasn't the unified tooling supposed to be a selling point for Go? It just doesn't feel good to use.

View on HN

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 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.

There is a name for it: The experts blind spot

I’ve heard it called and prefer to call it the curse of knowledge

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!

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"

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.

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.

> 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.

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.

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.

> 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.

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.

I can't disagree more.

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...

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.

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

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.

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

Still does.

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.

Isn't emacs the first to do it? I have the vague memory of it self-advertising as self-documenting.

I don’t know about emacs but your comment prompted a search for Smalltalk-80 docs:

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.

If you search the book you will find samples like:

    sum: xValue with: yValue
      "sums two values"
      ^ xValue + yValue

That is where commentString gets used.

Several Lisp variants also have a similar approach.

I fiddled around with SmalltalkAgents back in the day. Don’t remember how the doc was surfaced though.

This product probably deserves its own hn post: http://preserve.mactech.com/articles/mactech/Vol.10/10.04/Sm...

Indeed, it looks quite interesting

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

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

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.

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

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.

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...

and is identical to the output of `go help modules`

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

Code can be wrong. Documentation/comment can explain what the code was supposed to do.

> was

There's the important bit. Code can be wrong, but it gets less out of date than its comments.

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.)

godoc is not go doc

It's not only that the documentation is quite bad. It's also the rest of go.

Here's what it spews when you specidy a dependency incorrectly

Dependency:

  github.com/robfig/cron v3.0.1

go's handling of this:

  require github.com/robfig/cron: version "v3.0.1" invalid: 
  module contains a go.mod file, so major version must be 
  compatible: should be v0 or v1, not v3

Right. What?

I solved it by looking through this issue that comes at the top of Google Search for it: https://github.com/golang/go/issues/35732

I come to judge language's quality of documentation almost solely on their documentation around local and module imports. If they don't provide clear documentation on that subject, which is paramount imo to getting past simple scripts, then the rest of their higher level documentation is probably lacking. I've been upgrading some personal Go projects I have to a more modern folder layout (pkg, internal, etc. vs. src folder) and I really found their documentation lacking. Rust for example, in their imports, is so so, but I've found way better external examples for imports in Rust than Go.

Reply on news.ycombinator.com