Moving to proposal so that this gets visibility in the proposal-review meeting.

Just to add some input, I love how the current Go documentation, and I don't understand OP's frustrations at all. When I browse the documentation I simply click the links in the index. If I want to see another method, a better way is to just press "back", which in any decent browser takes one back to the index, and click on that other method. So I think both a sidebar and a FAB would actually hurt the experience for me by taking away the space.

Well, I didn't mean "and". I wrote "or". And this would barely take any real estate. We could simply add a hamburger style sidebar and by default, the state is closed. It doesn't affect anyone's current use of godoc negatively and for those who want to utilize it, they reap the benefits. Does that sound fair?

I should add, I'm not saying that what we currently have is bad. I just think it would be a bit more convenient and faster to search through docs with either one of those options that I stated in the OP.

English is not my mother tongue, so I might have phrased that incorrectly. What I meant is, if either of those options are on-screen, without a way to remove them, they hurt the readability of the docs. I am mostly fine with adding them as an option.

They don't, though. Check out tour.golang.com. If you notice on the top right, there's a hamburger style menu where you can simply click it to open the menu, otherwise, virtually no real estate is taken. I'm not saying for us to completely redesign godoc. Just something to help developers become more efficient. A good example of a large set of docs where this is implemented is the AWS Go SDK. Some people may not care about scrolling for 20 seconds to go back to the top but I do, especially if I have to do that for 10 methods. That equates to about 2 minutes of time that I lose simply because I have to scroll for so long. Now repeat that several times a day and those numbers start adding up a bit too much for my personal preference. Again, I'm not looking for a huge redesign. Just something to help with User Experience (UX).

Something unobtrusive seems reasonable. The sticky top-bar on tour.golang.org and its hamburger menu seem like a decent compromise. Can someone prototype something like that for godoc so we can see what it would look like? (It would be a bit different than the code on tour.golang.org since the tour is all frame-based and presumably godoc would not be.)

I know this doesn't look like the best thing in the world but hopefully it gets the point across. Basically, we don't need to map over everything like godoc traditionally does. We can omit certain things, such as arguments, return types, and so on. If someone wants to know those things, they can click a method, type, etc, and then see that method in more detail. If I need to make this better, let me know and I'll do my best

For the sidebar to work, either...

• the docs would have to be pushed over ~150px when open and come back to the center when closed
• the sidebar would overlay the docs
• the docs are permanently pushed over ~150px, which could look a little odd
• the sidebar is just super narrow, which could also look odd and longer method names would be clipped

Closed Sidebar

Open Sidebar

I like the docs pushing to right. Overlaying is not very ideal because people are reading the text, and it would be an obstruction. Contrary to tour.golang.org, where the links point to separate pages, here they are anchors where everything is in the same page. So it is expected people will keep the sidebar open and scroll the page.

It's okay if the sidebar is narrow. If there are longer method/type names, they can just be ellipsisized.

Also, can we highlight the item in the sidebar by increasing the font size when a user scrolls to that item ? That allows to user to get his/her bearings in a page.

We would also need to see what will be the behavior in mobile devices. Should the sidebar cover the entire screen when opened ? (that is what tour.golang.org does).

Please kindly avoid making offtopic posts. This thread is not about perl, or CPAN, or adding collapsible sections. If you have any concrete suggestions on how to improve the sidebar, please do. If you want collapsible sections, please create new issues. Otherwise posting random links to sites just adds noise.

@agnivade - sorry, got a new contract so got distracted a bit.

I like the docs pushing to right. Overlaying is not very ideal because people are reading the text, and it would be an obstruction.

I agree. This isn't too difficult. 😄

Also, can we highlight the item in the sidebar by increasing the font size when a user scrolls to that item? That allows to user to get his/her bearings in a page.

Absolutely. I think that's an important feature to bake in.

We would also need to see what will be the behavior in mobile devices. Should the sidebar cover the entire screen when opened ? (that is what tour.golang.org does).

I think it probably should. Anything less will be too hard to read and things will start getting pushed into each other pretty bad, causing a bad UX.

I can go ahead and start working on this and then we can iterate if you are approving this for a PR? Just want to confirm so I don't waste your time reviewing a PR that never got approved from the original issue 😅

I like where it is heading. Probably will need a couple iterations. Let's wait on @rsc's approval before you send over any code.

The images above look like permanently reserved space. What we liked about https://tour.golang.org/welcome/1 is that the index appears when you ask (overlaying existing material) for it but otherwise doesn't occupy a permanent margin. Can we do something like that?

Assuming yes, the proposal seems fine. Please send the code review to @andybons.

@rsc - yes, we can do it that way. I'll likely take a look at how tour.golang.com does it and draw inspiration from there, just with a few obvious modifications. I'll start working on this within the next couple of days. Thanks for approving!

@rsc - I kinda liked the permanently reserved space. It helps the reader to continue reading the page, otherwise one has to close the sidebar to continue reading. From my comment above -

I like the docs pushing to right. Overlaying is not very ideal because people are reading the text, and it would be an obstruction. Contrary to tour.golang.org, where the links point to separate pages, here they are anchors where everything is in the same page. So it is expected people will keep the sidebar open and scroll the page.

Apart from a sidebar and a back-to-top FAB, a sticky top-bar with a search box(providing me with suggestions in a drop down list and let me directly jump to the search result) can be very handy.

Example, Search suggestions

We can do it that way too - sorry for not responsibly taking care of this issue. I've had interviews almost every day for the past 2 weeks and getting ready to move upstate.

@agnivade @rsc - can we nail down the positioning of the main view? I can do it either way. I think pushing the main view over provides a better UX but I am not a pro when it comes to UI/UX.

@hooluupog - Let us just focus on the current proposal - which is about the sidebar.

@iamclaytonray - @rsc is on leave. @andybons can you chime in ? Russ wants the sidebar to overlay the main page. My points are here #26637 (comment)

@agnivade the sidebar will need to be constructed in a way that it can be mobile friendly anyway, so here’s what I would do:

• Have desktop/tablet viewport widths have a fixed sidebar that is always visible
• For mobile views, have it be in the hamburger menu so that it’s not obtrusive (I’m assuming this was your plan for mobile?)

If we see it and don’t like the end result on desktop, then we adjust the CSS to treat it like the mobile version.

This will allow us to try the different views without losing much engineering effort if we decide to go the route of having it be a popup.

I see. I thought it would be a hamburger menu always (so that the default behavior is a closed sidebar).

The only point of contention was what would happen to the main page on expanding the side bar in different resolutions. Should the main page push right ? (in desktop/tablet) Should the hamburger cover the entire screen ? (in mobile)

@spf13

Currently, when going through larger sets of documentation, it can be a little annoying to scroll down to a method, only to have to scroll back to the top and repeat. For libs/projects that don't have too much documentation, this isn't a big deal. For large projects, though, that's a lot of scrolling.

@iamclaytonray Are you aware of the "jump to identifier" functionality that https://godoc.org offers via the F keyboard shortcut? I rely on that for getting to known identifiers within a package, and it saves me a lot of unnecessary scrolling.

I wanted to ask because I plan to open an issue about backporting that functionality to x/tools/cmd/godoc (edit: opened #27714), and it seems to have some overlap with this issue (not necessarily a conflict).

We are already quite far into the redesign process as announced in https://blog.golang.org/go-brand. The new design already has implemented this improvement as part of a larger set of improvements to usability on the sidebar and site in general.

This proposal can be accepted as we've already incorporated the initial request. The later requests around the hamburger no longer apply to the new design.

Ah great, I didn't think the redesign will be applied to the package documentation too.

The later requests around the hamburger no longer apply to the new design.

Are you referring to "jump to identifier" or the "autocomplete" ?

Ahh, okay. @spf13 - should I just go ahead and close this then? There's no reason for me to submit a PR if you guys are internally doing the same thing.

Yes. I'll close it for you since I'm here. Thanks for the proposal. Please keep 'em coming.