x/pkgsite: suggesting a survey

[tooolbox]

Following up on #40911 (comment) I wanted to raise a suggestion that will hopefully help pkg.go.dev fulfill its role as the next-gen documentation website for the Go community.

Background

Broadly speaking, Go developers love the simplicity, productivity, and speed of the language. In the same vein, they prize the thorough, empowering documentation that springs from the source code as if by magic.

The 2018 Go Developer Survey showed that 53% of the 5,883 survey respondents use godoc.org, and it's the 2nd highest ranked information source.

The 2019 Go Developer Survey continued this trend, with 47% of the 6,564 question respondents relying on GoDoc which again ranked 2nd. (As a minor aside, I would posit a strong correlation between GoDoc-users and source-readers, as the former helps greatly with the latter, but I don't have the raw data to check this.)

Looking at the big picture, the Go community seems to be very satisfied with documentation for the language, libraries, and tools, as expressed by ~85% of survey respondents over the last 4 years:

Beyond the numbers, I did a brief trawl to gather articles and quotes from the community on GoDoc:

• The canonical article, Godoc: documenting Go code

The Go project takes documentation seriously. Documentation is a huge part of making software accessible and maintainable. Of course it must be well-written and accurate, but it also must be easy to write and to maintain. Ideally, it should be coupled to the code itself so the documentation evolves along with the code. The easier it is for programmers to produce good documentation, the better for everyone.

• Run a godoc Server Locally to See Documentation for Unpublished Packages

Gophers care a lot about documentation and people appreciate it immensely when you have a great overview, succinct summaries, great examples, and helpful details about gotchas.

• Documenting Go Code with Gonotes

When writing code, an abundance of documentation is always welcome to guide future readers and contributors (which includes yourself). Documentation is so important in Go, that the language was designed with a standardized approach to writing good code comments that could be autogenerated into documentation (see the Go team’s official blog post on documentation). There are amazing tools that expose the power of Go documentation, such as godoc.

• godoc: Tips & Tricks

Go has a great emphasis on simple, no-nonsense documentation right out of the box. Rather than using an existing format (like Markdown) where formatting is often explicitly stated godoc uses many implicit rules to extract quality documentation from really plain text so that you can spend less time formatting your documentation and more time writing it.

• Creating a Better ReadMe for GoLang Packages

We’re lucky in the Go community in that we decided to converge around simple but very useful tools early on in the ecosystem. ... One of the tools in our arsenal is godoc which is pretty wonderful, even if it is simple. It does most of what we need and provides enough to make us happy. Almost everyone knows to add comments to our packages for godoc to process and display.

• What's wrong with godoc? (a misleading title)

Like many modern languages, Golang has built-in inline documentation support tool called godoc. To be honest, it’s awesome. It is a really great tool, that has a real impact on the everyday coding process.

• Here are some amazing advantages of Go that you don’t hear much about

Documentation in code is taken very seriously in Go. So is simplicity. GoDoc is a static code analyzing tool that creates beautiful documentation pages straight out of your code.

... GoDoc is the only documentation engine for Go that is used by the whole community. This means that every library or application written in Go has the same format of documentation. In the long run, it saves you tons of time while browsing those docs.

With the high adoption rate and positive sentiments from the community, one would expect many organizations to be running an internal GoDoc server for their own packages, but in the 2019 Go Developer survey, only 6% of 6,408 question respondents reported that they run such a server:

The top reason given for not running such a server, coming in at 38%, was "the amount of effort required to initially set it up and maintain it," which agrees with my personal experience. (Oh, how I wish I could easily point a GoDoc clone at my Gitea instance and have docs for all my internal packages! This blog post—which could perhaps have more visibility, took me a bit to hunt for it just now—seeks to help, but seems limited to private repos on GitHub.)

To summarize, godoc.org (created by a community member and taken over by the Go Team in 2014) is statistically and anecdotally a huge success within the community.

The Go Team

The Go Team has a history of deep engagement with the community, of outreach and conversation and discovery, which has served it very well in ~10 years of stewarding the language and ecosystem. Some prime examples:

• The generics discussion on GitHub, heavily frequented by @ianlancetaylor and @griesemer
• The io/fs Q&A on reddit by @rsc
• Blogs and calls for feedback on next steps for pkg.go.dev by @julieqiu

Interaction like this, tabulation and weighing of feedback, and just plain good sense from the team—all while holding firm to their engineering principles and own sense of right—has given us Go Modules, the best generics design yet, the open-sourcing of pkg.go.dev, and even the withdrawal of try when its success was uncertain.

These sentiments are generally borne out by survey. Roughly three quarters of respondents to the 2019 Go Developer Survey felt confident in Go's leadership, and while the 57% who felt their needs are known could perhaps use improvement, it spiked sharply over the last year. (I recall thinking of Go Modules and the declined try when I clicked my answer to that question.)

pkg.go.dev

As mentioned, the trend of community interaction continues with x/pkgsite. To focus in on this, we have:

• The original announcement: https://blog.golang.org/go.dev
• The next steps: https://blog.golang.org/pkg.go.dev-2020
• Insight and background: https://groups.google.com/d/msg/golang-dev/mfiPCtJ1BGU/qtCrqlrEEwAJ
• The promised open-sourcing: https://blog.golang.org/pkgsite
• The further roadmap: https://github.com/golang/pkgsite#roadmap
• Transparent development guidelines: x/pkgsite: establish guidelines for feature development for pkgsite #40911
• UX Experiments: x/pkgsite: create a way for users to opt-in to experiments before they are fully rolled out #40905

There is a clear upward trend here, and it's very heartening. On a smaller scale, individual issues have received good attention: header content, badges, missing source file listing, even flip-flopping copy behavior based on shifting feedback ("can't those darn users make up their minds?").

That's not to say it's all perfect, but the effort shows and the intention is clear. Even the recent redesign of the main page, perhaps sparked by a community request or the general rebranding of Go, and which has met a lukewarm reception, has only fueled more transparency and a commitment to opening up the process even earlier in the pipeline, towards the design stages.

Surveys

This brings me to my suggestion, which is about the step prior to design: identifying problems in need of a solution.

The Go Developer Surveys have been used for this very effectively in the past. In 2018 they highlighted package management and generics as pain points, and the 2019 edition ranked the sequence of language features people would most like to see. In addition to surveying Gophers at large, one can consult more directly with high-profile community members, the conference speakers, the flagship project owners, the thought leaders, (though they might object to such flattering labels) as was done with the most recent generics proposal.

I don't think this is always necessary; a bug is a bug, and performance improvements are irrefutable. Sometimes the customers ask for a faster horse, and it's someone's job to give them a car instead. But I do think that in the case of GoDoc, more research is warranted, perhaps through surveys. What about it is valuable? What works—what doesn't, or wouldn't? How could it be better? What facilitates workflows? Why is this, by survey, the single most popular information resource controlled by the Go Team, answering questions for half of Gopherdom?

Should it even be changed at all? And, as it's often said in issues tagged LanguageChange and Go2, what is the cost of the change?

I know what my answers are to these questions, and I can make a convincing argument—but I'm sure that mine is not the only point of view.

Thanks very much.

[dmitshur]

/cc @julieqiu @jba @jamalc per owners.

[julieqiu]

Thank you for the detailed feedback, @tooolbox!

/cc @fflewddur for UXR input