Drake website beta testing

[jwnimmer-tri]

As the final step of #13832, we're going to ask a few people to beta test the website redesign.

Preview instructions are given at https://drake.mit.edu/documentation_instructions.html. Remember to pull the latest master branch first, and note that you need to run install_prereqs with extra flags first per the top of that page, and then jump down to the Jekyll section.

Testers are welcome to open a PR with changes they'd like to suggest, and we can merge those at any point.

Alternatively, problems that people identify which they can't or won't themselves should be posted as independent comments in this issue. We'll come by later and turn any required fixes based on those comments into a checklist in the top post here.

Testing & comments are due by 2021-03-03.

---

The problems which remain unfixed are:

• The landing page "CORE LIBRARY" footer is confusing (now tracked under Remaining bugs from website testing #14757)
  • Drake website beta testing #14695 (comment)
  • Drake website beta testing #14695 (comment)
  • Drake website beta testing #14695 (comment)
  • Drake website beta testing #14695 (comment)
  • Drake website beta testing #14695 (comment)
  • Drake website beta testing #14695 (comment)
• The landing page lower portion's three-wide-box offering is confusing (now tracked under Remaining bugs from website testing #14757)
  • Drake website beta testing #14695 (comment)
• Unclickable menu items => PR doc: Debounce Jekyll nav menus #14753
  • Drake website beta testing #14695 (comment)
• Something about margins (now tracked under Remaining bugs from website testing #14757)
  • Drake website beta testing #14695 (comment)
• Lighthouse report (now tracked under Remaining bugs from website testing #14757)
  • Drake website beta testing #14695 (comment)
• Mobile devices (now tracked under Remaining bugs from website testing #14757)
  • Drake website beta testing #14695 (comment)
  • Drake website beta testing #14695 (comment)
• Use https for off-site links (now tracked under Remaining bugs from website testing #14757)
  • Drake website beta testing #14695 (comment)

[ToffeeAlbina-TRI]

Are all the links supposed to be functional?
The Getting Help link on the homepage is Not Found
[2021-02-24 14:56:55] ERROR `/getting-help.html' not found.

[jwnimmer-tri]

Yup, everything should be finished, so anything that looks or operates wrong is unexpected.

The link should point to getting_help.html not getting-help.html.

[joemasterjohn]

There are quite a few explicit uses of http:// rather than https://. For most websites that implement strict transport security (github, etc.) this is mostly fine, but a few sites (groups.csail.mit.edu/locomotion) don't and won't redirect to HTTPS. Any particular reason for the explicit http, or should they be changed?

Hopefully everyone is using something like HTTPS Everywhere.

[jwnimmer-tri]

Comments will be due by March 3rd. I guess we'll pull the trigger and go live soon after that.

[avalenzu]

In from_binary.html, the "There are binary packages of Drake available at:" link points to a comment on a github issue: #1766 (comment)

Is that intentional? Seems odd given that the links to the actual tarballs are below.

[jwnimmer-tri]

In from_binary.html, ...

That matches the current website: https://drake.mit.edu/from_binary.html

I added it to the #13539 checklist as something to fix later on.

[avalenzu]

So in our beta testing, should we only flag things that don't match the current website?

[jwnimmer-tri]

I think its good to point out anything you don't like, but not all of the bugs will be blockers for switching over to the redesign.

[avalenzu]

On developers.html#supported-configurations, the table didn't quite translate correctly. The original has merged cells for values that are common between rows (e.g. Bazel and Java versions)

but the new one does not

Edit by Jeremy: Also the hard linebreak between GCC and Clang in the Ubuntu lines is missing, but important.

[avalenzu]

In developers.html#configuration-management-non-determinism the "following the instructions" link points to build_from_source.html which does not exist. It should be from_source.html.

Edit by Sean: More particularly, it should be from_source.html#build-from-source to preserve maximum parity with the sphinx documentation. Although, the anchor that is being referenced is the top of the file. So, probably no value.

[avalenzu]

In developers.html#issue-tracking , the "Platform Reviewer Checklists" link points to platform-reviewer-checklist.html which does not exist. It should be platform_reviewer_checklist.html.

Same issue with the "platform reviewer’s responsibilities" link in developers.html#review-process.

[avalenzu]

In developers.html#review-process-tooling the "Tips for participating ..." link has been incorrectly promoted to a heading.
Original:

New:

[avalenzu]

In jenkins.html ("Scheduling Builds via the Jenkins User Interface" section), the links to continuous, nightly, and weekly builds all have spurious trailing >s.

[sherm1]

On the front page, bottom left are the words "CORE LIBRARY". I assumed that was a link but it appears just to be text. It's unclear to me why it is there at all.

[jwnimmer-tri]

It's unclear to me why [CORE LIBRARY] is there at all.

I think it's supposed to be a header (title) for the three boxes below it within that same gray region.

Edit: To be clear, I'm not suggesting it's not a bug. Just for context.

Edit 2: The https://drake.sky.a2hosted.com/ from the contractors didn't have this problem. Our rewrite / restyle of the index page appears to have broken this title position and spacing.

[sherm1]

Oh, NVM! It formatted so tidily I didn't realize I wasn't looking at the whole page (missed the skinny scrollbar).

[sherm1]

The link at Resources/For Developers/Issue Tracking/Platform Reviewer Checklists (http://127.0.0.1:8000/platform-reviewer-checklist.html) says "Not Found" but other links on that page work. (That link appears in two places on that page.)

[sherm1]

FYI, just in case I'm not the only person making this mistake -- I didn't realize there was any more to the front page than I initially saw because (due to random window sizing I suppose) this is what I saw:

I didn't notice the skinny scroll bar to the right and there was nothing at the bottom indicating more below. Many websites that require scrolling have a down arrow at the bottom to notify the unobservant among us who might miss it.

[hongkai-dai]

On Resources/Getting Help/Asking Your Questions/, we say "please email Russ Tedrake for access", shall we add Russ's email here?

Edit (Jeremy): No. The intent is that only people who we already personally know (and thus who know Russ' email) will ask.

[jwnimmer-tri]

@sherm1

... (due to random window sizing I suppose) ...

The style is actually written so that we always see this. If you resize your window you'll see that the "core library" is always there on the bottom, even in significantly different viewport sizes.

[ggould-tri]

• Lighthouse report: https://htmlpreview.github.io/?https://gist.githubusercontent.com/ggould-tri/65ccee694ff4420134224bdfcbae65e4/raw/f72bf321ea2e1129625e43befdba7804bff3f1e1/lighthouse.html identifies only minor usability issues; I don't see anything here that merits special consideration except for its complaint about contrast.

• On a large window, the fonts are tiny and the majority of screen real estate blank. This comes from the use of a fixed 'px' font size, which is always going to be tiny on large monitors. It is possible that this is intentional but it is funny-looking and not awesome responsive design.

(arguably the tiny-font readability is impaired by oversaturation; https://ianstormtaylor.com/design-tip-never-use-black/ .)

[sherm1]

At the bottom of the front page (after scrolling all the way) there is a list of Acknowledgements with links. All of those work except the Office Of Naval Research link (currently http://www.onr.navy.mil/). It needs to be https.

[ggould-tri]

python_bindings.html : extra period after "package"

[SeanCurtis-TRI]

Legacy issue in buildcop.html

Check the Continuous Production build dashboard in Jenkins at least once an hour during on-call hours. These builds run after every merge to Drake. Also check the Nightly Production build dashboard every morning and Weekly Production build dashboard on Monday morning. These builds are unusually resource-intensive, and therefore run at most once per day.

It seems when the weekly CI info was inserted (6ecb9bb), the weekly info was squeezed before "nightly" and "run at most once per day".

Edit (Jeremy): I don't see the problem? It is correct that the weekly builds are resource intensive, and that they are run at most once per day.

[ggould-tri]

python_bindings page, "using the python bindings", the link under "Python API" has weird trailing giblets https://drake.mit.edu/pydrake/index.html#://. These don't break anything but are not needed in order to load.

Edit (Jeremy): In the Sphinx page that contained the hyperlink, they were actually required. We can drop them from Jekyll now, though.

[ggould-tri]

website_licenses.html Two of the linked documents (for the github mark and for python) are markdown but are rendered as text.

Edit (Jeremy): Working as intended.

[ggould-tri]

developers.html still has a .rst-style :ref:

... and :doc:

[ggould-tri]

developers.html A bulleted list has failed to format one of its items.

[SeanCurtis-TRI]

In clion.html

• Under "Building and Running Targets"
  • The new site corrects a bug in the old site. "the Bazel manual" is an actual link in jekyll, but mangled in sphinx. So, hooray, Jekyll!
• Under "Lint selected file for google style guide"
  • The string $FILE_PATH$:$LINE$ is no longer simply an indented, "code"-formatted string, but it gets the full treatment of black text box. Furthermore, it leaves backticks in the printed value.

[ggould-tri]

older_releases Missing punctuation between sentences.
... and also here:

[SeanCurtis-TRI]

In code_style_guide.html

• Under Python - Additional Rules.
  • The footnote on "Executable Python files should be limited..." is a live link in sphinx, but not in Jekyll.
  • The style for a "shell" block is horrible to read. There's basically a white screen, with a black block, with a bit of dark blue text in that black. Humans are bad at blue as it is, and when your pupil has shut down because of the white background, reading becomes taxing at best.

[ggould-tri]

older_releases page is the only one with a leading "Back to ..." link. This is ideosyncratic, especially as it is linked from other places than its backto parent.

Edit (Jeremy): All of the release notes pages (0.27, etc.) have this back-link.

[SeanCurtis-TRI]

in code_review_checklist.html

• Under "Is the code the minimal set of what you want"
  • Sphinx contains guidance for finding deprecations. They are missing in Jekyll.

[SeanCurtis-TRI]

in documentation_instructions.html

• I'm a bit surprised that there's not an extra warning that the sphinx portion will be going away. :)

[SeanCurtis-TRI]

In code_style_tools.html

• Under "Automated style checks"
  • Under "Bazel: Uses both pycodestylce like Python, and also buildifier.
  • buildifier is a link into bazel.html. Specifically, to the #buildifier tag. In Sphinx, it takes us to the middle of the page ("Updating build files"). In Jekyll, it takes us to the top of bazel.html.

[SeanCurtis-TRI]

On mac.html

The link to Source Installation (macOS, Ubuntu) is broken. Given as from_-_source.html.

[hongkai-dai]

On developers.html/#review-process

Not sure if this :doc:buildcop should show up as in the screenshop, especially ":doc:" seems suspicious.

[SeanCurtis-TRI]

In getting_help.html

• Under "Helpful Information"
  • Language (C++, Python), Python has a link to the python bindings. It lists python-bindings.html. It should be python_bindings.html.

[SeanCurtis-TRI]

A passing note inspired by python_bindings.html.

Given a fixed-width browser, on the whole the pages have been readable. In this case, because of:

• presence of a table of contents
• Huge horizontal margins on said table
• large font in code blocks

Much of the text is no longer available and requires me to scroll individual windows. Sad. :(

[jwnimmer-tri]

We should probably also test the site with javascript disabled?

[ggould-tri]

Javascript disabled:

The gallery videos fail as expected, and with a correct error message with a working link

Everything else appears unchanged.

[jamiesnape]

Is anyone testing with a mobile device profile (or even better an actual mobile device)?

[ggould-tri]

I've viewed a few pages with chrome dev tools' mobile renderer; they are neither especially good nor especially bad. If we really care about mobile users we should follow the lighthouse recommendations linked above (mobile readability being especially contrast sensitive, for example, because of glare) rather than mostly ignore them as I had suggested.

However debugging mobile presentation will be a lot easier once we're serving the pages; Drake isn't exactly useful from mobile, so I would propose deferring any serious mobile optimization until after the new site is up on drake.mit.edu in a viewable form.

[jamiesnape]

However debugging mobile presentation will be a lot easier once we're serving the pages; Drake isn't exactly useful from mobile, so I would propose deferring any serious mobile optimization until after the new site is up on drake.mit.edu in a viewable form.

Certainly, though the Google indexer is mobile first now.

[jwnimmer-tri]

The remaining open items have been moved into #14757.