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: redesign - the documentation section #41587
We'll be redesigning pkg.go.dev based on feedback received over the last year. This is the second in a series of issues about plans for the pkgsite/design-2020 milestone. Comment below with any feedback or suggestions related to this issue!
The documentation section of the pkg.go.dev/<path> page will have the following changes:
Here's a preview of what the documentation section will look like:
Note: The images shown in this issue are mocks, so the data may not accurately represent the exact contents of a given package.
Based on feedback that we've received, we understand that users find viewing the full package API useful, so the documentation index will be added back.
At the same time, we’ve heard that having a sidenav is useful for navigating the documentation, especially when the documentation is very long. We plan to keep this feature as well. In the new design, the function and type sections will be closed by default, since having everything expanded can be overwhelming. When a user clicks on a function or type from the index, that section will auto-expand.
We want to create a consistent structure across different packages in the documentation section. Therefore, when a section in the documentation is empty, we will still display the section header (for example, "Variables"), along with a message indicating it is empty ("There are no variables in this pacakge."):
We believe that doing so allows users to become familiar with the structure of this section over time. More importantly, UX research has shown that consistent documentation is important for accessibility. For screen reader users, having a consistent documentation structure allows them to predict the page structure. This means, for instance, if they know “Variables” is the fourth header, and they’re looking for variables, they can bounce to the fourth header without listening to each of the first three.
View Source Code
Thanks for posting, @julieqiu, my 2 cents:
This sounds good and the mock GIF looks good as well. Initial reaction is that it's cool that the README is in the sidebar as well, and I feel like the header (with package version, refresh date, license, etc.) seems improved.
I think this is a great idea.
Sounds neat; not major, but neat.
Sounds good; it would be cool to have an example as well. Linking into appropriate source locations is a very useful aspect of the docs, so expanding this is capability sounds like a move in the right direction, although it could perhaps be overdone with links in every nook and cranny.
Thanks @tooolbox! That's great to hear :)