Drake: 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 #14757)
  
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786812568
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786814233
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786816637
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786823323
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786824251
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786833984
  
  
• [ ] The landing page lower portion's three-wide-box offering is confusing (now tracked under #14757)
  
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786833759
  
  
• [x] Unclickable menu items => PR #14753
  
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786830105
  
  
• [ ] Something about margins (now tracked under #14757)
  
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786872059
  
  
• [ ] Lighthouse report (now tracked under #14757)
  
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786824510
  
  
• [ ] Mobile devices (now tracked under #14757)
  
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-790037743
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-790038534
  
  
• [ ] Use https for off-site links (now tracked under #14757)
  
  
  
  • https://github.com/RobotLocomotion/drake/issues/14695#issuecomment-786297667
  
  

[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: https://github.com/RobotLocomotion/drake/issues/1766#issuecomment-318955338

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

[hongkai-dai]

On Resources/Getting Help /Asking Your Question/, when clicking the link "submit a pull request", it jumps to the page developers.html#pull-request. But it seems to me that there is not a pull-request tag on developers.html.

[ggould-tri]

main.css:285 sets a top margin on the dropdown menus. This causes the menu to vanish if you move your mouse too slowly down from the menu heading (because a mouse event occurs inside of the margin). Deactivating this margin in developer tools removes the issue.

https://user-images.githubusercontent.com/17596413/109342331-b5976900-7839-11eb-80e2-3a4b5fbab224.mp4

[ggould-tri]

vim.html broken markdown formatting for link

[ggould-tri]

Release playbook, section "cutting the release", bullet 4 has a broken link: https://drake-jenkins.csail.mit.edu/view/Documentation/job/linux-bionic-gcc-bazel-nightly-documentation/ (url should include "unprovisioned")

[hongkai-dai]

In Code Review Checklist, the facepalm emoji is missing

_Edit (Jeremy): This is working as intended._

[sherm1]

• On the bottom part of the front page (just below "CORE LIBRARY") are three boxes. My first attempt was to click on the boxes but nothing happened. Then I realized the tiny red text below was actually the clickable part and in fact "API | TUTORIAL" was actually two different links. To me that seems more obscure than it needs to be. I think anything that looks like a clickable box should be clickable, and it should be more clear that the red text is clickable but the "CORE LIBRARY" text is not.
• Under these (non-clickable) boxes, the text that on the current Drake site says "Doc" has been changed to "API". The second "API" (under "Solving Mathematical Programs") leads to non-API documentation, although there is eventually an API link there. The third one (under "Multibody Kinematics and Dynamics") links just to some obscure documentation and doesn't lead to any meaninful API as far as I could tell. Consider changing at least that one back to "Documentation" or (better) just make the box clickable?

[SeanCurtis-TRI]

To @sherm1's point about the unobvious-ness of scrolling. While the "core library" footer is always present as you scale the window, it isn't a clickable link and scrolling isn't obvious. I'd contrast that with TRI's robotics page (https://www.tri.global/our-work/robotics/) which includes "Scroll & Explore" with a down arrow. Very ergonomic.

[ggould-tri]

On release playbook, the link "link" is broken with a spurious >: https://github.com/RobotLocomotion/drake/pull/14208/commits/674b84877bc08448b59a2243f3b910a7b6dbab43%3E

[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 (6ecb9bb7bf1), 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.