Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: establish guidelines for feature development for pkgsite #40911

Open
julieqiu opened this issue Aug 19, 2020 · 3 comments
Open

x/pkgsite: establish guidelines for feature development for pkgsite #40911

julieqiu opened this issue Aug 19, 2020 · 3 comments

Comments

@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Aug 19, 2020

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
  • Allowing users to opt-in to experiments before they are fully rollout: #40905
  • Publishing documentation on expectations for feature development with x/pkgsite, in addition to the CONTRIBUTING.md
@tooolbox
Copy link

@tooolbox tooolbox commented Aug 21, 2020

@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
Copy link
Contributor Author

@julieqiu julieqiu commented Aug 25, 2020

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:

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

Again, thanks for all your feedback!

@tooolbox
Copy link

@tooolbox tooolbox commented Aug 28, 2020

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
You can’t perform that action at this time.