Devdocs: Inform user that a newer version of the documentation exists

[erikhansen]

When a user lands on an older version of a page (e.g., "2.0"), I would recommend informing them that a newer version of that page existed. I've seen this cause confusion for both myself and others over the past months.

Google has indexed a lot of the 2.0 versions of pages. For example, search for "devdocs magento keys" and http://devdocs.magento.com/guides/v2.0/install-gde/prereq/connect-auth.html will be the first result. Thankfully the 2.0 and 2.1 versions of those pages are the same, but if they weren't, the user might be presented with outdated info. Here is an example UI:

What would show when the page loads:

What would show after user clicked "Learn more":

[korostii]

I could not upvote this enough.
Ideally, the message should appear if (and only if) the the 2.0 and 2.1 versions of the page are different (not just a symlinked copy), but at least a static message would also be an improvement.

[jcalcaben]

@erikhansen Thanks for bringing this up! We are working with our UX team to find a solution for reducing confusion between versions.

[jcalcaben]

Hi @erikhansen, we have a new design in devdocs. It should reduce confusion by highlighting the version picker.

[erikhansen]

@jcalcaben When will that new design be pushed to production so I can check it out?

[jcalcaben]

It is live on the site right now

[jcalcaben]

@erikhansen if you would like to chat with us in real time about this issue, we have a Slack channel in the Magento Community Engineering workspace:
https://magentocommeng.slack.com/messages/CAN932A3H

[korostii]

Hi @jcalcaben
Not sure what you mean by highlighting the version picker, looks pretty much the same to me. Would you mind clarifying that point if that's not too much to ask?

Well, at least the 2.3-alpha version of the page has some visible notice: http://take.ms/GdgGb
Should be simple enough to just reuse those styles with a text similar to what @erikhansen suggested, no?

[jcalcaben]

Hi @korostii
I may have misspoken about highlighting the version picker. I was under the impression the redesign promoted the feature better.

The team currently does not have the bandwidth to work on this at the moment, but I am re-opening this issue to give the community the opportunity to work on this improvement.

[erikhansen]

Here is some additional context from the #devdocs Slack channel in Magento Community Engineering.

Erik Hansen [3:13 PM] Per this issue: https://github.com/magento/devdocs/issues/1234#issuecomment-391106127 I'm looking at Dev Docs and it's still not obvious to me when I'm viewing an older version of the page (compared with the design mockups I added to my issue):

Jeff Matthews [3:12 PM]
hi @erikpallhansen, i think the best example of what you're describing can be found here: http://docs.graylog.org/en/2.2/

Erik Hansen [3:13 PM]
@JeffYes! Something like that would be great.

Jeff Matthews [3:14 PM]
that site is using the python-based static site generator sphinx, which i think comes with that type of support out of the box. i'm not sure jekyll, which is what we're using for devdocs, comes with native support for that.
this would definitely be an interesting project that would benefit readers, but it would require some custom development that we don't currently have resources for. maybe we can create a community project to work on a proof of concept. would you be interested in participating?

Erik Hansen [3:18 PM]
That sounds like a good idea, but unfortunately I don't have the bandwidth to be able to commit to that.

Jeff Matthews [3:20 PM]
this would be a fun project for a hackathon. i'll add it the list of projects we're putting together for MMDE and MMNL

Erik Hansen [3:21 PM]
👍

[clivewalkden]

I've pushed an example branch on my fork https://github.com/sozo-design/devdocs/tree/fix_issue_1234.

I've hooked into the after-site-header to replicate the current 2.0.x deprecation notice. I think it might need styling to make it more obvious but it links through the the current major version site.version (2.2 from current _config.yml) of Magento.

Does this sound like a solution to the problems above, or does anyone else have any ideas?

[jeff-matthews]

We'll check out your solution @clivewalkden. Thanks for contributing!

[jeff-matthews]

@belbiy, @jcalcaben, & @dshevtsov, will one of you please review https://github.com/sozo-design/devdocs/tree/fix_issue_1234 and provide feedback?

[jcalcaben]

Hey @clivewalkden
This is a good start to a solution! One problem I encountered was when I navigated to a 2.3 topic and see two banners.
Ideally, the 2.3 banner message should be the only one showing in this case.

[clivewalkden]

@jcalcaben I was thinking that the theme styling could be updated to make this upgrade message stand out. That would require the theme to be updated? Or is there alternative message styling already available?

[belbiy]

@claireparker , i don't like the idea of having two messages as well. We don't want to overload the reader with a lot of warnings.

Is it possible to incorporate two messages into one?
For 2.0, can we have the message in the banner like this:

You are not using the most up to date version of Magento. Magento {{ site.version }} is the newest version.

Magento 2.0.18 is the final 2.0.x release. After March 2018, Magento 2.0.x will no longer receive security patches, quality fixes, or documentation updates. To maintain your site's performance, security, and PCI compliance, upgrade to the latest version of Magento.

?

[shrielenee]

@belbiy Does any of the versioning redirect work affect this at all?