Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
x/pkgsite: establish guidelines for feature development for pkgsite #40911
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:
@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,
Thanks very much!
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!