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/tools/cmd/godoc: add hamburger button to quickly navigate docs #26637

Closed
iamclaytonray opened this issue Jul 27, 2018 · 25 comments

Comments

Projects
None yet
9 participants
@iamclaytonray
Copy link

commented Jul 27, 2018

What version of Go are you using (go version)?

go1.10.3 darwin/amd64

Feature request?

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. I am proposing a way to provide a better UX/DX.

  • A sidebar that maps over exported functions/types/etc
    or
  • A back-to-top FAB of some sort

The FAB would be the easiest option but I think the sidebar would be the best UX/DX option, as you can quickly scroll through the sidebar and find the next function/type/etc that you are looking for. This isn't high priority but I will submit a PR for this if it gets approved. Thanks!

PS: I deleted most of this issue template as none of it was really relevant.

@gopherbot gopherbot added this to the Unreleased milestone Jul 27, 2018

@agnivade agnivade changed the title x/tools/(godoc): add sidebar to quickly navigate docs proposal: x/tools/cmd/godoc: add sidebar to quickly navigate docs Jul 27, 2018

@gopherbot gopherbot added the Proposal label Jul 27, 2018

@agnivade

This comment has been minimized.

Copy link
Member

commented Jul 27, 2018

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

@ainar-g

This comment has been minimized.

Copy link
Contributor

commented Jul 27, 2018

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.

@iamclaytonray

This comment has been minimized.

Copy link
Author

commented Jul 27, 2018

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.

@ainar-g

This comment has been minimized.

Copy link
Contributor

commented Jul 27, 2018

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.

@iamclaytonray

This comment has been minimized.

Copy link
Author

commented Jul 27, 2018

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

@rsc

This comment has been minimized.

Copy link
Contributor

commented Aug 6, 2018

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

@iamclaytonray

This comment has been minimized.

Copy link
Author

commented Aug 6, 2018

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

godoc-1

Open Sidebar

godoc-2

@agnivade

This comment has been minimized.

Copy link
Member

commented Aug 7, 2018

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

@agnivade

This comment has been minimized.

Copy link
Member

commented Aug 8, 2018

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.

@iamclaytonray

This comment has been minimized.

Copy link
Author

commented Aug 8, 2018

@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 😅

@agnivade

This comment has been minimized.

Copy link
Member

commented Aug 8, 2018

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.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Aug 20, 2018

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 rsc changed the title proposal: x/tools/cmd/godoc: add sidebar to quickly navigate docs x/tools/cmd/godoc: add hamburger button to quickly navigate docs Aug 20, 2018

@iamclaytonray

This comment has been minimized.

Copy link
Author

commented Aug 20, 2018

@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!

@agnivade

This comment has been minimized.

Copy link
Member

commented Aug 21, 2018

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

@hooluupog

This comment has been minimized.

Copy link

commented Sep 14, 2018

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
2018-09-14_223536

@iamclaytonray

This comment has been minimized.

Copy link
Author

commented Sep 14, 2018

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.

@agnivade

This comment has been minimized.

Copy link
Member

commented Sep 14, 2018

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

@andybons

This comment has been minimized.

Copy link
Member

commented Sep 15, 2018

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

@agnivade

This comment has been minimized.

Copy link
Member

commented Sep 15, 2018

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)

@andybons

This comment has been minimized.

Copy link
Member

commented Sep 16, 2018

@dmitshur

This comment has been minimized.

Copy link
Member

commented Sep 17, 2018

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

@spf13

This comment has been minimized.

Copy link
Contributor

commented Sep 18, 2018

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.

@agnivade

This comment has been minimized.

Copy link
Member

commented Sep 18, 2018

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" ?

@iamclaytonray

This comment has been minimized.

Copy link
Author

commented Sep 18, 2018

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.

@spf13

This comment has been minimized.

Copy link
Contributor

commented Sep 19, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.