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