x/pkgsite: establish guidelines for feature development for pkgsite

[julieqiu]

Following up on #40612 (comment), the pkgsite team is working on processes to give users time to give feedback on large feature changes, before these features are live in production. These processes include:

• Creating milestones for pkgsite
  • Correlate these milestones with the x/pkgsite Roadmap
• Allowing users to opt-in to experiments before they are fully rollout: x/pkgsite: create a way for users to opt-in to experiments before they are fully rolled out #40905
• Publishing documentation on expectations for feature development with x/pkgsite, in addition to the CONTRIBUTING.md

[tooolbox]

@julieqiu thanks very much!

One thing that I would like to see, if at all possible, is a formal outline of the goals associated with the pkgsite that are leading to the various changes we've seen over the last months.

I'm interested because, as someone who has known, used, and loved Godoc over the past years, I am comfortable with it and find it very useful. What I originally understood pkgsite to be was a superset of Godoc, in other words exactly the same delicious dish the community has been served for years, but with dessert to boot: module-awareness, architecture-awareness, great search capabilities, etc.

However, I've seen a few changes made to the core documentation experience, including #37863 and most recently #40612, which seemed to lessen the value of the pages, moving pkgsite away from that concept of a superset. #37863 was rolled back, and #40612 is still evolving, but these changes telegraph the fact that the Go Team perceived problems with Godoc that deserved to be solved.

I recall a Go Time episode wherein @spf13 discussed the pkgsite, and how it related to his goal of advancing corporate adoption of Go. (You were on that cast too, IIRC.) This was a great insight for me because it put in perspective the focus on surfacing licenses. I as a community member could appreciate the problem being solved and understand that, while I was not the target audience of this feature, it's in service of a great cause that will benefit the Go community as a whole.

Similarly, if the community can understand the reasoning behind UX/UI changes, what problems require solution or what pain points require easing, both large and small, I think it will help pave the way for a smooth upgrade process as the team works to build pkgsite into its final form.

#40905 is really fantastic, so I guess the only thing I can add is that, for large changes or changes that affect the core documentation experience, it may be worthwhile to gather feedback from the community before even building an experiment. That is a strategy and process that has proven invaluable for Go itself as a language, seen most recently in the FS and file-embedding proposals, and perhaps most visibly in the subject of generics.

I admit that we're discussing a documentation website, not the language itself, and said site is not governed by the Go 1 Compatibility Promise. However, Godoc is an integral part of my workflow as a Go developer, and has a bearing on my productivity akin to the go tool, gopls, modules, build times, and so on. All of these things have improved and evolved over the years, and sometimes there is a step back before it goes forward, but there has always been thoughtful discussion and careful consideration of what already exists and its value.

Thanks very much!

[julieqiu]

Thanks for the thoughtful feedback, @tooolbox! It’s great to hear that godoc.org was a big part of your workflow, and we really appreciate the feedback that you have given us here and on other pkgsite issues.

We certainly don’t want to lessen the core documentation experience. It’s the reason we announced our intent to eventually redirect godoc.org traffic in https://blog.golang.org/pkg.go.dev-2020, and asked everyone to start giving us feedback early, so that we could ensure that pkg.go.dev addresses users' needs.

What we’re hearing is that it would be useful to give users a chance to give feedback earlier on the Go issue tracker, before the issue is shipped.

To do this, some things that we are experimenting with are the ones described in #40911 (comment) (posting mocks ahead of implementation, #40905, etc.). These are processes we’d like to invest in, so that users can give us early feedback.

Regarding a formal outline, we currently publish our plans in these places:

• Roadmap in the pkgsite/README
• Milestones with the pkgsite prefix

If you have additional suggestions, feel free to file an issue.

Again, thanks for all your feedback!

[tooolbox]

Thanks very much. I'm glad you want to maintain the same core documentation experience, and I've seen how you're gathering feedback and I really appreciate it. I'm glad that mine has helped 👍

If you have additional suggestions, feel free to file an issue.

Done!