Docs homepage, nav change

[jathayde]

This PR contains navigation changes as discussed with Amanda, including a new Docs homepage and linking out to the new Merch store. Navigation now highlights based on the page you are on.

There is a new docs homepage linking out to various locations, and the case studies area to link to future Jekyll pages. The Doximity is held here with a "COMING SOON" banner.

We may want to 301 redirect old /blog urls to the new /news.

[AmandaPerino]

Adding screenshots:

[AmandaPerino]

@jathayde Are we able to already add the blog redirects to this PR? We have a lot of links in the wild that I wouldn't want to interfere with.

[dhh]

Where is the actual doximity case study living?

Also, wonder if the forum should live under Community instead of under Docs? But don't have that strong opinions about it either way.

In terms of design, I think the desktop one is fine, but the mobile one looks pretty inefficient with it's space. This is basically just a page of links. To only be able to fit one link per visible scroll on mobile doesn't seem quite right. I'd just kill the navigation logos at that size.

[jathayde]

@jathayde Are we able to already add the blog redirects to this PR? We have a lot of links in the wild that I wouldn't want to interfere with.

I'll work on that and add here.

[jathayde]

Where is the actual doximity case study living?

It doesn't exist yet, but the discussion was something around /docs/case-studies/doximity or perhaps pulling /case-studies to a top-level directory. Regardless, it would be in this site in Jekyll.

Also, wonder if the forum should live under Community instead of under Docs? But don't have that strong opinions about it either way.

Community is now about the people involved in the framework (the prior "Team" link, is still located at /community). Forum doesn't feel like it fits with that content, although it does make sense affinity-wise with "Community".

In terms of design, I think the desktop one is fine, but the mobile one looks pretty inefficient with it's space. This is basically just a page of links. To only be able to fit one link per visible scroll on mobile doesn't seem quite right. I'd just kill the navigation logos at that size.

Will take a stab at a few options to reduce the vertical space taken up by the graphics.

Thanks!

[dhh]

Okay. I'm not sure it makes sense to actually screw with the links here, btw. Even with a 301. We can just call the link News instead of blog, but retain blog in the URL. Then we don't risk screwing with search engines and old links and whatever. And it doesn't matter anyway.

But I would also not launch this until there's some actual content to show for it. Moving the links around should be in service of some actual new stuff. Does not make sense to me without that.

[dhh]

Also, I'd prefer if we kept the style for the headline in line with the rest of the site. Don't think this needs to be broken into three lines for stylistic reasons.

[zzak]

Will take a stab at a few options to reduce the vertical space taken up by the graphics.

Maybe you can shrink the logo and put it on the top left, and float that header in the top middle and shrink it too. It looks like the logo is the same size on mobile and desktop, I think more detail on the smaller screen size is preferable.

Also on mobile, maybe the section banners could just be the outline of the emoji next to the relevant section header. It's very red right now.

I think the team preferred "News" over blog since it is more appropriate title, but does having the label of a link not line up with the URL or content matter for SEO?

Is the merch site also a work in progress? How does that line up to releasing this?

Thanks for your hard work!

[AmandaPerino]

I think the team preferred "News" over blog since it is more appropriate title, but does having the label of a link not line up with the URL or content matter for SEO?

I could be wrong, but don't think that matters so much for SEO.

Is the merch site also a work in progress? How does that line up to releasing this?

Merch store is ready to go. The Doximity case study and the tutorial will take a bit more work, so we have a bit of time to get everything ready to go live together.

[jathayde]

Also, I'd prefer if we kept the style for the headline in line with the rest of the site. Don't think this needs to be broken into three lines for stylistic reasons.

In original, unaltered h1 style we break the line:

I'd like to at least control that to look like this:

on mobile, we'd display: none on the <br> and let it wrap naturally:

[jathayde]

Will take a stab at a few options to reduce the vertical space taken up by the graphics.

Maybe you can shrink the logo and put it on the top left, and float that header in the top middle and shrink it too. It looks like the logo is the same size on mobile and desktop, I think more detail on the smaller screen size is preferable.

This is how it is in production today. I can take a look at this and see what we can do, but reducing that top 150px to maybe 75 would help focus more on the content.

Also on mobile, maybe the section banners could just be the outline of the emoji next to the relevant section header. It's very red right now.

Agreed. Working on two different options to reduce both the red and the lost space/inefficency per your and @dhh's notes

Thank you for the feedback!

[jathayde]

Here's an option for the homepage on mobile, which dramatically reduces the vertical space but retains the icons without having additional graphics.

[dhh]

That's certainly a lot better. But I think it also calls into question what the value of those icons really is. But still, big improvement.

[dhh]

Something else is that we need to retain a consistent capitalization scheme. "How Did They Do It" stands out from the entire rest of the site which uses "You're in good company" etc.

[jathayde]

Revised using visual elements from other parts of the existing site, removing icons entirely, and some copy help from @AmandaPerino to balance the lines in the boxes better and reduce repitition.

[matthewd]

I do have a general concern that a significant segment of repeat visitors are going to be looking exclusively for the API docs or maybe guides, and beyond the extra click, it feels like they're floating in the middle of a large space. I'm not sure what I'd suggest to do differently, though. 😕

[AmandaPerino]

I do have a general concern that a significant segment of repeat visitors are going to be looking exclusively for the API docs or maybe guides, and beyond the extra click, it feels like they're floating in the middle of a large space. I'm not sure what I'd suggest to do differently, though. 😕

The only thing I can think to do here to address that is to create a dropdown from that navbar tab to make it a more direct/fewer clicks experience, but not sure if that's ideal either.

However, my guess is that most devs would just start typing "api" in the URL and the API docs would load based on previous visits, bypassing the homepage and docs landing page altogether.

[jathayde]

I feel from a flow perspective, most people aren't coming to this page as power users. They have their bookmarks, muscle memory, or other means of consuming the docs (e.g. Dash on macOS is my go to for API reference). We can provide a drop down, but we don't do that on other items, so I would ask if it is truly needed.

[zzak]

I'm not sure I like the card style on mobile, it eats up so much space, but I also didn't love the gradient style on the icon version either. 🤔

However, my guess is that most devs would just start typing "api" in the URL and the API docs would load based on previous visits, bypassing the homepage and docs landing page altogether.

This is me, but I also think the dropdown is fine ala vuejs but they don't have a docs landing page. Also looking at swift, they have a separate page for "get started" and a docs landing page which points to api reference, etc. Kind of making the choice down to "are you new here?" or "do you know what you're looking for?"