elastic.co/guide/* redesign

[bmorelli25]

Click here to view the interactive preview

---

Summary

This PR updates the style and layout of our elastic.co/guide/* documentation.

Page

• Removes margin and widens the container using a new container class to accommodate sticky content on both sides.

Table of contents (left column)

• Moves the table of contents to the left side of the page and makes it sticky.
• Scrolls the TOC to the selected element.
• Styles the table of contents to be more accessible with higher contrast between the text and the background (the blue on gray was difficult to read).
• Adds SVG chevron icons to the table of contents—great for screens of any resolution.

On this page & marketing (right column)

• Makes the "On this page" content sticky.
• Adds an IntersectionObserver() to highlight one item at a time in the "On this page" list.
• Simplifies the styling of the "Most popular" and "We're hiring" boxes and makes them sticky.

Why?

Our documentation is difficult to navigate, and readers constantly have to scroll up and down to maintain context or navigate to new pages. There are a number of reasons why this happens:

• The table of contents is hidden below the fold.
• The "On this page" widget disappears when you scroll down the page.
• Many elements, including the page container have margins that waste too much screen real estate.

What does it look like?

Click here to view the interactive preview

Known limitations

• If no section heading is visible on a page, highlighting is removed from the OTP. Example.
• The OTP does not scroll with the content on longer pages. Example.

Stakeholders

• The documentation team (see Aug. 3rd cross-doc recording)
• Docs infra (@gtback)
• Docs PM (@KOTungseth)
• Front-end (@chandlerprall or @glitteringkatie)
• Marketing / web (see linked internal issue)
• QA (@rashmivkulkarni)
  Others?

QA

Sorry, this is an internal link. Bug history and QA checklist.

[dedemorton]

I love where this is heading. One thing that we should change when we have time: the font in right-side TOC is too small relative to other text. I wonder if we should consider increasing the width of the page so that we do not have so much whitespace, and then we could increase the font size.

[bmorelli25]

I wonder if we should consider increasing the width of the page so that we do not have so much whitespace, and then we could increase the font size.

Agreed. Our docs use Boostrap v4, which defines XL screens as anything above 1200 pixels. The screen recording above was taken on my laptop with a width of ~1400 pixels.

There's a ton of whitespace in the recording because we use the container class which sets our max-width to 1140px:

docs/resources/web/lib/bootstrap/bootstrap.css

Lines 615 to 619 in 0b1e761

	@media (min-width:1200px) {
	.container {
	max-width: 1140px
	}
	}

I haven't done a lot of research, but it sounds like we can instead use the container-fluid class to remove that limitation.

One thing that we should change when we have time: the font in right-side TOC is too small relative to other text.

Yeah, good point. That was me. We can definitely make it larger.

[leemthompo]

This is a great initiative! What do we think of making subheadings more visually distinct, i.e. render h2, h3, etc. more easily distinguishable at a glance? This, plus the work you've already started here would solve 99% of my issues with the current docs reading UX. 🙂

[bmorelli25]

What do we think of making subheadings more visually distinct, i.e. render h2, h3, etc. more easily distinguishable at a glance?

@colleenmcginnis recently brought up the topic of headings. We discussed it, but it might be beyond the scope of this PR. Changing the headings is a bit complex—mainly because of how Asciidoc converts .asciidoc heading levels to built HTML. This results in some pages starting with an H2, and others starting with an H3, H4, etc. We could update the styles for each heading level, but pages would still differ due to the defined heading levels in their asciidoc files.

We're planning on following up this PR with some elastic.co/guide changes. If it's okay, we can look at adding heading style changes into that PR. Thanks for the feedback!

[gtback]

I don't feel particularly qualified to review the CSS or JavaScript changes, but I'm 👍🏻 for these changes as long as others approve. The pages look a lot better to me!

[gtback]

I'd love to find a front-end engineer to review this.

@glitteringkatie @chandlerprall would you have some time to review this, or nominate someone else who might be able to help?

[alaudazzi]

Thank you for leading this initiative! It looks much better than what we have today :-)
QQ: If I search for a term, the results are shown in the old system. Is it because the new system is still on staging?

[colleenmcginnis]

If I search for a term, the results are shown in the old system. Is it because the new system is still on staging?

@alaudazzi By "search for a term" do you mean use the site-wide search and click on a result (see screenshot below)?

It looks like those links go to https://elastic.co/* pages from the staging site. (My guess is that we don't have a staging search set up.) All production pages at https://elastic.co/* URLs use the old layout. Only pages on the staging site show the new layout.

[chandlerprall]

LGTM 👍

[KOTungseth]

LGTM👍

[dedemorton]

I found some places where the page is scrolled instead of starting at the top like it should. I don't think this should be a blocker.

I'm on Chrome Version 103.0.5060.134 (Official Build) (x86_64)

pagescrolling.mp4

[rashmivkulkarni]

Checked for spacing, paragraph breaking, proper rendering, spot checks on various links etc.. LGTM. ( some of my nits are addressed in the PR.)

[colleenmcginnis]

☝️ @bmorelli25 that commit switches from scrollIntoView to scrollTop, which adds a little more complexity, but some light internet research suggests it might be necessary to prevent the full page from scrolling.

[lcawl]

IMO the initial list of pages and sections looks plain and it's not obvious you can click them until you get a mouse over them. For example:

However, the benefits once you start clicking outweigh this issue, so I think it's worth merging as-is.

[dedemorton]

IMO the initial list of pages and sections looks plain and it's not obvious you can click them until you get a mouse over them.

@lcawl TBH for most "books" I wish we could just skip the initial list and go directly to content. In most cases, the list page does not add value. I think there are some books that have introductory text on this page in addition to the list.

Maybe as a next step we could try to beef up the introductory text for each book? Just a thought, not a hard requirement.

[richkuz]

I love the new redesign, really great grassroots effort to improve our docs 💯 😍

Now that the site is live, a lot of the feedback I've heard is very positive. I heard some constructive feedback, too. Listing it here (if there's another place to put this, please let me know):

1. It's new/different, which requires adjustment.
2. It's not obvious that the left-hand column can be scrolled up and down.
3. Maybe consider making the version dropdown list sticky, so that when you scroll down it stays at the top.
4. If the announcement in the right-hand nav gets too large, it could make it hard to see the right-hand navigation content. The announcement today ("We're hiring!") is small, with no impact on the right-hand navigation, so the problem isn't apparent today.

Nothing super actionable, just sharing.