4 ms·

Godocs.io One Year Later

80 points by sirodoht 5y ago

WhyNotHugo 5y ago
The VCS Autodiscovery looks pretty neat. I really hope other open source forges start picking it up too.
cientifico 5y ago
Thank you very much for it. There is a clear productivity hole for me since google removed godocs until I discovered godocs.io. In the meantime, I even did a chrome extension to make the new site more readable. It was sad how they ignored the feedback. It felt like a designer that didn't use go documentation daily designed the site. The worst part is they never explained why. godocs.io deserve to have a direct link in the http://golang.org/ http://golang.org/ site.
- Thaxll 5y ago
  Why would you use OP website vs the official version: https://pkg.go.dev/ https://pkg.go.dev/, for example https://pkg.go.dev/github.com/prometheus/client_golang/prometheus https://pkg.go.dev/github.com/prometheus/client_golang/prome... OP site looks inferior to the official one, maybe I'm missing something. Edit: why am I being downvoted?
  - Shared404 5y ago
    The OP website is a replacement of a site that was replaced with pkg.go.dev . Said replacement was created because there were people who didn't like the change, and so fixed it themselves. Edit: Also a heads up: People on HN tend to take questioning downvotes poorly, and the site guidelines say to not do so. In this case, it's probably because you didn't look into OP at all before commenting, and completely disregarded both your parents comment as well as the OP.
  - sirodoht 5y ago
    This is the creator's motivation for godocs.io and against pkg.do.dev: https://drewdevault.com/2020/08/01/pkg-go-dev-sucks.html https://drewdevault.com/2020/08/01/pkg-go-dev-sucks.html
  - cientifico 5y ago
    Here is what I wrote in 2020: https://github.com/golang/go/issues/37862#issuecomment-601817818 https://github.com/golang/go/issues/37862#issuecomment-60181... They closed the issue and asked to write it again while ignoring the concerns. In general, I think a few of us are disappointed. It felt like some marketing guy at google deciding to use GO to promote the company and replace one of the boring doc services with something "cool." It felt like developers were no longer driving the project: Now is a Google project. To the day, I don't know why they decide to kill godoc.org instead of improve it like OP. For me, godocs.org should be in https://killedbygoogle.com/ https://killedbygoogle.com/
    - tjpnz 5y ago
      It felt like some marketing guy at google deciding to use GO to promote himself.
  - Beltalowda 5y ago
    > OP site looks inferior to the official one, maybe I'm missing something. Neither is strictly "better" or "worse", but they are different. I dislike the fixed banned, that stuff animated, and various things. Right now it's broken because clicking a header makes that header sit behind the fixed header (maybe a feature? I think it's confusing). I just want a basic HTML page; it works well for me. Normally I'd fix this with some Stylus CSS, but the site changes (and my CSS breaks) what feels like every week. So, I set up a redirect from pkg.go.dev to godocs.io and my life has been better since.
  - yegle 5y ago
    Fun fact, the Google internal godoc still uses the godoc.org style/layout.
s-video 5y ago
I appreciate the work the Go team put into pkg.go.dev, and I like the new features they've put in (e.g. flagging deprecated things, the search is great) and hope those get into godocs.io as well. But I really just don't care for how its designed compared to the old godoc.org. (and go.dev compared to the old golang.org) It just doesn't gel with me. I wish I had the design vocabulary to explain why. It just feels big, and loud, and cramped. And I really don't care for the animations and drop shadows. The old docs site and old home page just felt quieter, less commercial, yet still fresh and modern and professional. My ideal Go docs site would have the appearance of the old golang.org/pkg pages, with a fixed width. I don't even agree with a lot of the criticism thrown at pkg.go.dev. In older threads Russ Cox gave perfectly acceptable reasons to not accept every license. (legal stuff, better safe than sorry) There's the fact that the source wasn't available for like a month at first, but that changed once it was brought up, and I don't think the Go team was trying hide anything or something. It's mostly just the design that gets me. That, and, I'm little puzzled as to how they rolled out pkg.go.dev, and go.dev, and replaced golang.org with go.dev. Like, at first they rolled out pkg.go.dev, saying "godoc.org is really old, so we're replacing it". Sure. But pkg.go.dev obviously came with go.dev, which they just called a "discovery site" (or something to that effect, I don't remember). ...okay? Then they stripped off golang.org/pkg (the old standard library documentation) and the reason they gave was to reduce the number of doc servers they had to run. And finally, they just scrapped golang.org and replaced it with go.dev. What's really odd to me is that, in retrospect, it seems like they had a long term plan to replace golang.org altogether, at least since they rolled out pkg.go.dev, but just... didn't mention it? It seems highly unlikely that they just rolled out a new package doc site, along with a free bonus "discovery site" -- they never billed it as a new home page until it became the actual home page -- and then noticed the discovery site could conveniently be the new home page. Furthermore, on Twitter, someone criticized the way go.dev has corporate logos, and one of the Go project managers (or some such role, I don't know) replied that it was for funding the project. (I'll dig up that thread if someone REALLY wants me to) So, I'm really convinced that it was always the plan to replace golang.org, but its just bizarre to me that it wasn't communicated like that since the start. It sort of came off as a series of happy accidents. Why not just announce the plan to replace golang.org at the start? Why wait to announce your intentions until you actually do it? I'm not trying to be accusatory and suspicious, I don't think anyone should be, but it's something that I just can't get off of my mind. ...ok, all that said, I'm really grateful for the work and progress done with godocs.io. Keep it up! :)
icholy 5y ago
I'm not a fan of the pkgsite redesign, but godocs.io is missing a key feature: linking identifiers back to their location in the source.
blurker 5y ago
It would be really cool if godoc had a way to generate a module-specific documentation site like Rust can with `cargo doc`: https://doc.rust-lang.org/cargo/commands/cargo-doc.html https://doc.rust-lang.org/cargo/commands/cargo-doc.html Basically, read the go.mod and generate the doc page for that. It doesn't seem like a big leap from what godoc already does, but AFAIK (and please correct me if I'm wrong), godoc doesn't have an option for this. The reason I like it is it's basically a super simple "give me all the docs that are relevant to this project" command. I think it's super clever that cargo does this!
donatj 5y ago
Ooh. I really miss classic godocs. I don't know what it is about the new site but I find it obnoxiously hard to use.
mleonhard 5y ago
Can you please make one for Dart & Flutter, too?
nemo1618 5y ago
Only thing keeping me from switching to this is the ability to jump from docs -> source code. It looks like they do support this in some form, but not in a way that's backwards-compatible with existing packages, which is kind of a dealbreaker.

80 points by sirodoht 5y ago

The VCS Autodiscovery looks pretty neat. I really hope other open source forges start picking it up too.

Thank you very much for it. There is a clear productivity hole for me since google removed godocs until I discovered godocs.io. In the meantime, I even did a chrome extension to make the new site more readable. It was sad how they ignored the feedback. It felt like a designer that didn't use go documentation daily designed the site. The worst part is they never explained why. godocs.io deserve to have a direct link in the http://golang.org/ http://golang.org/ site.

Thaxll 5y ago
Why would you use OP website vs the official version: https://pkg.go.dev/ https://pkg.go.dev/, for example https://pkg.go.dev/github.com/prometheus/client_golang/prometheus https://pkg.go.dev/github.com/prometheus/client_golang/prome... OP site looks inferior to the official one, maybe I'm missing something. Edit: why am I being downvoted?
- Shared404 5y ago
  The OP website is a replacement of a site that was replaced with pkg.go.dev . Said replacement was created because there were people who didn't like the change, and so fixed it themselves. Edit: Also a heads up: People on HN tend to take questioning downvotes poorly, and the site guidelines say to not do so. In this case, it's probably because you didn't look into OP at all before commenting, and completely disregarded both your parents comment as well as the OP.
- sirodoht 5y ago
  This is the creator's motivation for godocs.io and against pkg.do.dev: https://drewdevault.com/2020/08/01/pkg-go-dev-sucks.html https://drewdevault.com/2020/08/01/pkg-go-dev-sucks.html
- cientifico 5y ago
  Here is what I wrote in 2020: https://github.com/golang/go/issues/37862#issuecomment-601817818 https://github.com/golang/go/issues/37862#issuecomment-60181... They closed the issue and asked to write it again while ignoring the concerns. In general, I think a few of us are disappointed. It felt like some marketing guy at google deciding to use GO to promote the company and replace one of the boring doc services with something "cool." It felt like developers were no longer driving the project: Now is a Google project. To the day, I don't know why they decide to kill godoc.org instead of improve it like OP. For me, godocs.org should be in https://killedbygoogle.com/ https://killedbygoogle.com/
  - tjpnz 5y ago
    It felt like some marketing guy at google deciding to use GO to promote himself.
- Beltalowda 5y ago
  > OP site looks inferior to the official one, maybe I'm missing something. Neither is strictly "better" or "worse", but they are different. I dislike the fixed banned, that stuff animated, and various things. Right now it's broken because clicking a header makes that header sit behind the fixed header (maybe a feature? I think it's confusing). I just want a basic HTML page; it works well for me. Normally I'd fix this with some Stylus CSS, but the site changes (and my CSS breaks) what feels like every week. So, I set up a redirect from pkg.go.dev to godocs.io and my life has been better since.
- yegle 5y ago
  Fun fact, the Google internal godoc still uses the godoc.org style/layout.

s-video 5y ago

I appreciate the work the Go team put into pkg.go.dev, and I like the new features they've put in (e.g. flagging deprecated things, the search is great) and hope those get into godocs.io as well. But I really just don't care for how its designed compared to the old godoc.org. (and go.dev compared to the old golang.org) It just doesn't gel with me. I wish I had the design vocabulary to explain why. It just feels big, and loud, and cramped. And I really don't care for the animations and drop shadows. The old docs site and old home page just felt quieter, less commercial, yet still fresh and modern and professional. My ideal Go docs site would have the appearance of the old golang.org/pkg pages, with a fixed width. I don't even agree with a lot of the criticism thrown at pkg.go.dev. In older threads Russ Cox gave perfectly acceptable reasons to not accept every license. (legal stuff, better safe than sorry) There's the fact that the source wasn't available for like a month at first, but that changed once it was brought up, and I don't think the Go team was trying hide anything or something. It's mostly just the design that gets me. That, and, I'm little puzzled as to how they rolled out pkg.go.dev, and go.dev, and replaced golang.org with go.dev. Like, at first they rolled out pkg.go.dev, saying "godoc.org is really old, so we're replacing it". Sure. But pkg.go.dev obviously came with go.dev, which they just called a "discovery site" (or something to that effect, I don't remember). ...okay? Then they stripped off golang.org/pkg (the old standard library documentation) and the reason they gave was to reduce the number of doc servers they had to run. And finally, they just scrapped golang.org and replaced it with go.dev. What's really odd to me is that, in retrospect, it seems like they had a long term plan to replace golang.org altogether, at least since they rolled out pkg.go.dev, but just... didn't mention it? It seems highly unlikely that they just rolled out a new package doc site, along with a free bonus "discovery site" -- they never billed it as a new home page until it became the actual home page -- and then noticed the discovery site could conveniently be the new home page. Furthermore, on Twitter, someone criticized the way go.dev has corporate logos, and one of the Go project managers (or some such role, I don't know) replied that it was for funding the project. (I'll dig up that thread if someone REALLY wants me to) So, I'm really convinced that it was always the plan to replace golang.org, but its just bizarre to me that it wasn't communicated like that since the start. It sort of came off as a series of happy accidents. Why not just announce the plan to replace golang.org at the start? Why wait to announce your intentions until you actually do it? I'm not trying to be accusatory and suspicious, I don't think anyone should be, but it's something that I just can't get off of my mind. ...ok, all that said, I'm really grateful for the work and progress done with godocs.io. Keep it up! :)

icholy 5y ago

I'm not a fan of the pkgsite redesign, but godocs.io is missing a key feature: linking identifiers back to their location in the source.

blurker 5y ago

It would be really cool if godoc had a way to generate a module-specific documentation site like Rust can with `cargo doc`: https://doc.rust-lang.org/cargo/commands/cargo-doc.html https://doc.rust-lang.org/cargo/commands/cargo-doc.html Basically, read the go.mod and generate the doc page for that. It doesn't seem like a big leap from what godoc already does, but AFAIK (and please correct me if I'm wrong), godoc doesn't have an option for this. The reason I like it is it's basically a super simple "give me all the docs that are relevant to this project" command. I think it's super clever that cargo does this!

donatj 5y ago

Ooh. I really miss classic godocs. I don't know what it is about the new site but I find it obnoxiously hard to use.

mleonhard 5y ago

Can you please make one for Dart & Flutter, too?

nemo1618 5y ago

Only thing keeping me from switching to this is the ability to jump from docs -> source code. It looks like they do support this in some form, but not in a way that's backwards-compatible with existing packages, which is kind of a dealbreaker.