4 ms·

One really minor, but powerful, thing I'd love to see from the Go team is a better designed documentation experience. Here's the Google-produced Github library

by 013a 8y ago

One really minor, but powerful, thing I'd love to see from the Go team is a better designed documentation experience. Here's the Google-produced Github library godoc [1]; its absolutely horrendous to browse, as is any sufficiently large package. Compare that to Elixir's [2] auto-generated documentation. There's a lot of work that can go into just improving that static HTML and making it more easily grokable. [1] https://godoc.org/github.com/google/go-github/github https://godoc.org/github.com/google/go-github/github [2] https://hexdocs.pm/phoenix/overview.html https://hexdocs.pm/phoenix/overview.html

urtrs 8y ago
I prefer godoc. It is concise and I can find faster what I am looking for.
shazow 8y ago
Godoc is an excellent forcing function when it's not ignored. Designing your package's public namespace so that it looks sensible in godoc yields great results for consumers.
thefounder 8y ago
Godoc compensate by being more functional. The elixir example is missing links to the source code of the functions/methods etc. Godoc also generates an excerpt with all the functions/methods/types in the package.
- q1t 8y ago
  ExDoc does not miss links to the source code. (Click on any Module/function and there should be brackets "<>" that point to the source code.) Types are also present in any module that defines them.
weberc2 8y ago
I've not used Elixir, but I'm surprised by the strong dislike for GoDoc. I've used Java, C#, C/C++, Python, and JavaScript and I've never found anything to be as nice as GoDoc. In particular, Godoc is absolutely effortless. No build step in your project, no cryptic documentation syntax, no need to tell the documentation generator how to link to your dependencies' documentation pages, etc. Everything just works, and the output is quite a lot cleaner than the aforementioned as well. No doubt there's a little room for improvement in how the text is layed out and organized, but it's still leagues better than all other documentation systems I've used. With Python (sphinxdocs) in particular, everything gets rendered into a giant page with no clues about what class's `__str__()` method I'm currently looking at.
- 013a 8y ago
  That's mostly what I mean. I love godoc and the philosophy behind it; its a massive improvement over the manual documentation build steps of Java, JS, Python, etc. But even more modern languages, like Rust and Elixir, do it better. There's a lot of low-hanging UX and usability fruit to be fixed in godoc which can make the experience better.
  - weberc2 8y ago
    Ah, I see. I guess I think of these UX improvements as “the last mile”, and it’s nice to have something that gets us 95% of the way there compared to everything else that makes you work to get to 40%. Also, i’ve never found Rust’s docs to be very easy to read; maybe the complexity of the type system makes for a more challenging UX, or maybe my opinion is simply an outlier. In any case, it’s good to know things can get even better. Thanks for sharing!
the_duke 8y ago
I really prefer the Rust auto-generated documentation to both Godoc and Elixir docs. See for example https://docs.rs/diesel/1.2.2/diesel/pg/index.html https://docs.rs/diesel/1.2.2/diesel/pg/index.html. Godoc is too plain and almost cumbersome to read for me, while Elixir is too pretty and not so efficient in displaying the type information in my opinion. Rust has a happy middle ground here.
- ainar-g 8y ago
  It's funny how these things are so personal. I love Godoc, mostly because everything is on one page, with very little JS and a good, almost monochrome colour palette. At the same time, I really can't stand Rust's docs, because everything seems to get its own page, it's colours galore, and of course there is a sidebar. The mileage does vary greatly apparently.
  - weberc2 8y ago
    Agreed on both your preferences and overall YMMV point.
agnivade 8y ago
Hi, godoc maintainer here. We have a lot of UI improvements coming for 1.12. - A TOC at the top - A sidebar for easy scrolling - More cross-links for easy navigation. If hotlinking comes through, that's a major improvement in itself. Stay tuned !

by 013a 8y ago

urtrs 8y ago

I prefer godoc. It is concise and I can find faster what I am looking for.

shazow 8y ago

Godoc is an excellent forcing function when it's not ignored. Designing your package's public namespace so that it looks sensible in godoc yields great results for consumers.

thefounder 8y ago

Godoc compensate by being more functional. The elixir example is missing links to the source code of the functions/methods etc. Godoc also generates an excerpt with all the functions/methods/types in the package.

q1t 8y ago
ExDoc does not miss links to the source code. (Click on any Module/function and there should be brackets "<>" that point to the source code.) Types are also present in any module that defines them.

weberc2 8y ago

I've not used Elixir, but I'm surprised by the strong dislike for GoDoc. I've used Java, C#, C/C++, Python, and JavaScript and I've never found anything to be as nice as GoDoc. In particular, Godoc is absolutely effortless. No build step in your project, no cryptic documentation syntax, no need to tell the documentation generator how to link to your dependencies' documentation pages, etc. Everything just works, and the output is quite a lot cleaner than the aforementioned as well. No doubt there's a little room for improvement in how the text is layed out and organized, but it's still leagues better than all other documentation systems I've used. With Python (sphinxdocs) in particular, everything gets rendered into a giant page with no clues about what class's `__str__()` method I'm currently looking at.

013a 8y ago
That's mostly what I mean. I love godoc and the philosophy behind it; its a massive improvement over the manual documentation build steps of Java, JS, Python, etc. But even more modern languages, like Rust and Elixir, do it better. There's a lot of low-hanging UX and usability fruit to be fixed in godoc which can make the experience better.
- weberc2 8y ago
  Ah, I see. I guess I think of these UX improvements as “the last mile”, and it’s nice to have something that gets us 95% of the way there compared to everything else that makes you work to get to 40%. Also, i’ve never found Rust’s docs to be very easy to read; maybe the complexity of the type system makes for a more challenging UX, or maybe my opinion is simply an outlier. In any case, it’s good to know things can get even better. Thanks for sharing!

the_duke 8y ago

I really prefer the Rust auto-generated documentation to both Godoc and Elixir docs. See for example https://docs.rs/diesel/1.2.2/diesel/pg/index.html https://docs.rs/diesel/1.2.2/diesel/pg/index.html. Godoc is too plain and almost cumbersome to read for me, while Elixir is too pretty and not so efficient in displaying the type information in my opinion. Rust has a happy middle ground here.

ainar-g 8y ago
It's funny how these things are so personal. I love Godoc, mostly because everything is on one page, with very little JS and a good, almost monochrome colour palette. At the same time, I really can't stand Rust's docs, because everything seems to get its own page, it's colours galore, and of course there is a sidebar. The mileage does vary greatly apparently.
- weberc2 8y ago
  Agreed on both your preferences and overall YMMV point.

agnivade 8y ago

Hi, godoc maintainer here. We have a lot of UI improvements coming for 1.12. - A TOC at the top - A sidebar for easy scrolling - More cross-links for easy navigation. If hotlinking comes through, that's a major improvement in itself. Stay tuned !