Page redesign issues and design notes

[tobous]

This all related to the prototype for the new page layout, available here (but probably only temporarily).

Issues I have found found so far:

• [x] [CANNOT REPRODUCE; me neither, marked as resolved] Then entry 'Continuous Integration' is not highlighted in the nav-bar when selected (see here).
• [X] Clicking the Saros logo in the header leads to a 404 (see here).
• [X] On the "Releases" landing page, the first entry of the navbar (named "Get Saros") is highlighted (see here). This seems to be the only category where this happens.
• [X] In the "Releases" category, the entry "Get Saros" is highlighted in the navbar, even when we are actually browsing one of the release notes pages (see here).
• [X] Scrolling the section out of view removes the box from the selected IDE tab (see here).
• [X] Scrolling the section out of view removes the highlighting from the current navbar entry (see here).
• [X] The size of the TOC changes depending on the position on the page. It is quite small when at the top of the page but then stretches to the border of the page when starting to scroll (see here).
• [X] The "Support" category displays the navbar of the category "Contribute" (see here).
• [X] The "Research" category displays the navbar of the category "Docs" (see here).
• [X] The page no longer sets a page icon displayed in the browser tab. (The current page uses the Saros icon.)
• [X] In the mobile view, the TOC is still displayed when the screen is big enough, but it overlaps with the titlebar. (This happens for a mobile view with a width of 768 or higher for me.)
• [X] The spacing of the navbar entries is not uniform if they are squished (i.e. if the window is too small). An example for this would be the contribute category, where there is a blank line after the navbar entries "Best Practices" and "Saros Testing Framework" if the window is small enough (halve-sized horizontally for me).

Design descition we should discuss

• [ ] The navbar on the left no longer scrolls with the view but rather remains at the top of the page. This makes it harder to navigate the site as we have quite a few long pages.
• [ ] The titlebar no longer scrolls with the view but rather remains at the top of the page. This makes it harder to navigate the site as we have quite a few long pages. This also goes for the landing page.

Notes on the design:

• The visibility of the "Getting Started" button on the landing page could be improved. It kind of blends into the background. You could change its color to make it more distinct. -> Inverted colors
• The position of the Saros logo in the header bar seem a bit weird to me. Previously, it lined up with the navbar. Now, it looks so "disconnected". -> Removed separation of logo and navigation
• With the navbar being so close to the content, it is harder to differentiate them. Especially with navbar entries that can be unfolded this looks weird as the arrow is so close to the content (see here). In general, there is a lot of unused space on the left and right edge. -> Substituted right-aligned arrow by left-aligned collapse-plus/minus.
• The contact info is only visible at the bottom of the page, making it harder to find on longer pages that can't entirely be displayed at once (see here). -> Added to the header bar
• The highlighting of the sections in the TOC on the right is nice but has some weird side-effects (see below). So if it is to hard to fix/make consistent, I would suggest just dropping it. -> We use the Bootstrap default scrollspy. Furthermore, I would not know a better handling in these cases.
  • At the top of the page, no entry is highlighted.
  • At the bottom of some pages (probably tabbed ones), the first displayed entry is highlighted (see here), even if another section is specifically selected by clicking the TOC.
  • On the other pages (see troubleshooting page), the TOC highlighting jumps directly from "Editing > Network Issues" to "Known Issues > About Eclipse Plugins". It seems like the last entry is always highlighted in the TOC when at the bottom of the page.
• Renaming the category "Docs" into something more descriptive (like "User Documentation", as previously displayed on the landing page) might be nice, especially since it is now one of the main ways to navigate the site from the landing page. -> Renamed to "User docs"
• Having the "Host" field on the "Docs" landing page and "Getting Started" page seems sensible, but with the current color scheme, it looks like a serious warning instead of a "good to know" fact. Maybe use a different highlighting color instead of yellow? -> Changed to blue
• I am not a fan of the listing of the awareness information on the landing page. The layout for selection and contribution annotations would be ok, but for the viewport annotations, it just looks super weird to have such a long text over a tiny, vertically stretched picture. But I don't know hot to improve it. -> Removed the viewport stuff, but I think about a better visualization in the future
• The Saros UI contains more elements than the annotations mentioned on the landing page. These other elements (the Saros view and its components as well as the project view highlights) are now never mentioned on the page. Previously, they were described in the screenshot section. So i would suggest extending the information on the landing page or re-adding the screenshots (or, even better, adding current screenshots) and their description.
• The category entries in the titlebar are underlined when moused over. This is not a big deal but it does not match the rest of the page styling. I would suggest to remove it. -> removed
• Just to mention it, I consciously moved the order of the contact entries around to put twitter at the end as it is very rarely used (basically only for announcements). Furthermore, I wanted to minimize the amount of user asking for help for technical issues over twitter. But it isn't that important. -> done
• As an idea: To improve usability of the "Getting started" section, we could add gifs for all explained stuff (e.g. how to add a contact, how to start a session, etc.). But this would take a lot of work, so I can understand if you don't want to do it as part of this update.

[m273d15]

Wow, thanks. Some issues are design decisions and I still have to fix multiple small issues, but I wanted to agree on a design before polishing it. Probably we should discuss this in a Screensharing session.

[tobous]

Some issues are design decisions

If you mean the no longer scrolling navbar and titlebar stuff, yes, it can be seen as a design decision. I put it in the category "issue/bug" as there was a similar issue with the old design. But If you feel like they should no longer scroll that is something that we can discuss.

[m273d15]

@tobous I tried to fix all issues and reworked the header bar. I found the reason for the strange issue "The "Support" category displays the navbar of the category "Contribute"". My local jekyll version was 3.8.3 and the github action builds with 4.0 (which has a slightly adjusted rendering mechanism). As a follow-up I want to add information on the landing page concerning IntelliJ. However, I want to introduce the new page structure first before adding new content.

[tobous]

LGTM in general. Haven't found any other obvious issues with the current layout. (Header bar sometimes looks a little weird for different width in the mobile view, but that is acceptable in my opinion.)

There is still some nitpicky stuff regarding capitalization, spelling, and punctuation marks, but that can be addressed in the code review for the PR.

But I still have one big issue (landing page) and one smaller, subjective issue (TOC highlighting):

Landing Page Issues

I am still not happy with the landing page.

Layout

First of all, the ordering of the sections seems confusing to me. I would suggest first explaining the plugin functionality before mentioning data security/privacy.

With the current ordering, you have a nice introduction: the headline talks about "collaborative development", followed by the gif showing "collaboration." But after that, without any further context or explanation of what the plugin does, you talk about data privacy (after that about awareness information and only then about what the collaborative aspect of Saros actually is). As you haven't really explained the core functionality of Saros yet, readers won't really know what to make of the gif (which is why I put the collaboration in quotation marks; without any context, it is hard to understand that the shown windows are supposed to represent different instances that are synchronized across the network; you tried to alleviate the problem by introducing a gap between the windows, but I don't think it helps much without any context).

It seems weird to me to put data privacy in the spotlight as it is not a core feature or design aspect of Saros but rather a byproduct of how it was build (if I understand it correctly; maybe I am mistaken and it was an initial design decision; either way, it is not something we are frequently talking about when thinking about the feature scope/design of Saros).

I know that data privacy is an important factor to differentiate the plugin from other solutions offering remote collaboration and to potentially draw in enterprise users, but I still think we should first properly explain what the plugin does.

An issue for such a reordering would be that it no longer fits the current layout scheme (text -> picture -> text -> picture ...), as it also looks weird to position the privacy text between "Awareness Information" and "Follow-Mode".

"Awareness Information" section

As hinted at before, I am also not happy with the "Awareness Information" section. The layout still looks weird, even without the viewport annotation listing. Furthermore, it sells the awareness information Saros provides short in my opinion.

With

• the viewport annotations (for the whole file and the currently visible area),
• caret annotations,
• project view annotations (which files are shared and which files are currently visible to which participants), and
• the information provided in the Saros view (who is in the Session, who is looking at which file, and who is following whom),

Saros provides far more awareness information that suggested by this section.

I get that you are trying to keep it to the basics in this post, but, with the new layout, this information is also mentioned nowhere else on the page.

So how about adding a button to the section leading to a more detailed screenshot page as it existed on the old/current page?

TOC Highlighting Issues

I am still not a big fan of the TOC highlighting.

(I found another weird side-effect of the TOC highlighting to add to the list: On pages that are short enough to not need a scroll bar, the last entry of the TOC is always highlighted. See here.)

In general, I would suggest to remove the highlighting as the edge cases seem confusing and it doesn't provide that much of a benefit. But that is just my opinion. If I am in the minority here, I also don't mind keeping it in.

[m273d15]

Ok, so I will prepare a WIP PR (without the scrollspy / toc highlighting (we can discuss the highlighting issues in the future)) with some TODOs.

[tobous]

Design descition we should discuss

• [ ] The navbar on the left no longer scrolls with the view but rather remains at the top of the page. This makes it harder to navigate the site as we have quite a few long pages.
• [ ] The titlebar no longer scrolls with the view but rather remains at the top of the page. This makes it harder to navigate the site as we have quite a few long pages. This also goes for the landing page.

The two design decisions on the behavior of the title-bar (on the top) and nav-bar (on the left) are still open.

As already mentioned, I think both of them scrolling with the view would offer the best usability as it allows the user to always directly navigate to whatever other page they want to go to without having to scroll to the top of the page. Especially with the nav-bar, it allows the user to always get a quick overview over which other pages are part of the current topic. (Also, the nav-bar would only take up unused space anyways, so I don't see much of a reason to not have it always be visible/scroll with the view except for "distracting the reader".)

@m273d15 If I remember correctly, you like the behavior the way it is. Could you present your argument as to why (or what you don't like about the scrolling behavior)?

@stefaus What is your opinion on the matter (as the potential tie-breaker :wink:)?