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: suggesting a survey #41119

tooolbox opened this issue Aug 28, 2020 · 2 comments

x/pkgsite: suggesting a survey #41119

tooolbox opened this issue Aug 28, 2020 · 2 comments
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite


Copy link

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


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, and it's the 2nd highest ranked information source.

2018 Survey Results

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.)

2019 Survey Results

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:

2019 Satisfaction Question Results

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

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.

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.

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.

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.

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.

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.

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:

2019 Internal Go Documentation Survey Question Results

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, (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:

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, 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.)

2019 Survey Question on the Go Project & Leadership

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

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.


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.

@gopherbot gopherbot added this to the Unreleased milestone Aug 28, 2020
Copy link

/cc @julieqiu @jba @jamalc per owners.

@dmitshur dmitshur added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite labels Aug 31, 2020
Copy link

Thank you for the detailed feedback, @tooolbox!

/cc @fflewddur for UXR input

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite
None yet

No branches or pull requests

4 participants