See related task created for iOS T165906: Floating TOC for articles on iOS

Change 442164 had a related patch set uploaded (by Dbrant; owner: Dbrant):
[apps/android/wikipedia@master] [GETTING THERE] Experiments with the ToC.

https://gerrit.wikimedia.org/r/442164

Change 444031 had a related patch set uploaded (by Dbrant; owner: Dbrant):
[apps/android/wikipedia@toc_scroller] Turn ToC into a sliding scrollable controller.

https://gerrit.wikimedia.org/r/444031

Change 442164 abandoned by Dbrant:
Turn ToC into a sliding scrollable controller.

Reason:
This will now be tracked in the proper 'toc_scroller' branch in Gerrit.

https://gerrit.wikimedia.org/r/442164

Testing with app 2.7.237-alpha-2018-07-06 (the test Alpha provided) and Samsung Galaxy Express 3 SM-J120A (Android 6.0.1). Everything seems to be working as described in the Design details above.

So far everything is working pretty well for me. The only thing I can think of so far is a slight improvement in the way the indicator pops to a section title and the section title is visible within the article. It feels to me like if a section is highlighted in the TOC, the section title should be visible onscreen.

For example:

1. I go to the Evel Knievel article with the intention of reading about the Snake River Canyon
2. I use the TOC to scroll down until the Snake River Canyon is highlighted and I release my finger

In this case, it is difficult to land on the section of the article containing the section title. I usually have to scroll up/down to find it. I have found it to be even less accurate after scrolling down and back up again.

hi @Dbrant - just had a quick look and had some additional tweaks as well:

• Swiping left is not triggering opening of the ToC
• When the ToC element is swiped open, the element should appear alongside the section that is 'active'. For example in the following screenshot I have just opened the ToC when scrolled to "Death" but the scroller icon element is shown between References and External links

• The vertical dotted line should start from the title's dot, and end at the last ToC section header (at the moment it is extending from top to bottom of the screen). Dots should be 2dp diameter and 8dp apart (apologies the Sketch mock has stretched the dots to be ovals).
• Article title is the same font as the article title in the article (Droid Serif), with font-weight Regular and size 24sp (with line height 28dp).
• Section headings are normally in the Section title (Light: Base20) color, with the active section header in Primary color (Light: Accent50). At the moment, section headings are weirdly sometimes black and sometimes the Base20 color (as can be seen in the above screenshot)
• the active section heading should NOT change font-weight

@RHo Thanks for taking a look. I'll try to address the minor style issues, but the other items are much more complex, and will likely not be done by Wikimania.

• The table of contents is no longer a sliding drawer component (other portions of the component wouldn't work if it remained one), and therefore no longer reacts to horizontal gestures.
• Note that the Google Docs app does not have a swipe-left action in its table of contents.

At the moment, section headings are weirdly sometimes black and sometimes the Base20 color

The lighter items are subsections (h3) of top-level sections (h2). What should be the style of subsections?

In T165964#4419868, @Dbrant wrote:

• The table of contents is no longer a sliding drawer component (other portions of the component wouldn't work if it remained one), and therefore no longer reacts to horizontal gestures.
• Note that the Google Docs app does not have a swipe-left action in its table of contents.

hi @Dbrant - I think it's really important we keep the existing swipe left action to trigger the ToC right now, esp. given there is no longer a an icon fixed in position to show the ToC. Can we make it work on Prototype A, if not B?

At the moment, section headings are weirdly sometimes black and sometimes the Base20 color

The lighter items are subsections (h3) of top-level sections (h2). What should be the style of subsections?

• Let's keep subsections the same color as top-level sections

Can we make it work on Prototype A, if not B?

@RHo It's not really a matter of being able to plug it into any particular prototype. The best we could do might be to detect the swipe gesture on the right edge of the screen, and make the new ToC fade in when the gesture is detected (i.e. the same action as short-pressing the round scrolling button). Would that be sufficient? To clarify, the ToC wouldn't "follow" the motion of the finger as you're swiping, but would just fade in after the swipe gesture is complete.

Let's keep subsections the same color as top-level sections

If subsections are indistinguishable from top-level sections, wouldn't that make it quite confusing? A table of contents should provide a sense of structure in the depth-dimension of sections, shouldn't it?

In T165964#4434693, @Dbrant wrote:

Can we make it work on Prototype A, if not B?

@RHo It's not really a matter of being able to plug it into any particular prototype. The best we could do might be to detect the swipe gesture on the right edge of the screen, and make the new ToC fade in when the gesture is detected (i.e. the same action as short-pressing the round scrolling button). Would that be sufficient? To clarify, the ToC wouldn't "follow" the motion of the finger as you're swiping, but would just fade in after the swipe gesture is complete.

• that sounds like a reasonable compromise in theory, better than not having the swipe gesture at all.

Let's keep subsections the same color as top-level sections

If subsections are indistinguishable from top-level sections, wouldn't that make it quite confusing? A table of contents should provide a sense of structure in the depth-dimension of sections, shouldn't it?

• At the moment the lighter colour on subsections makes it appear like these sections are disabled or unvisited. Let's still remove this different colour first while I explore other ways to provide visual indication of hierarchical structure (different font size, indentation with a "–", etc)

@RHo
Alright! I've made some major enhancements (use the same APK linked in the description), namely:

• The edge of the screen now recognizes a swipe gesture, which will cause the ToC to be shown.
• When dragging the scroll thumb, the current section title will be "sticky" relative to the thumb, more in line with the Google Docs example.
• When the ToC is first shown, it will correctly align the current section title with the scroll thumb.
• Normalized font & color of section names (with a TODO item for coming up with a different style for subsections).

Awesome, thanks @Dbrant !

hi @Dbrant - I've updated the styling for H2 and H3s. You can refer to the updated Zeplin mocks (ER09 and ER10), but essentially the changes are:

• H2 top level section headings use the serif font, matching the headings in the article content
• H3 section headings use Roboto Regular 14sp

BTW, have noticed that there are still a couple of visual design issues pending fix:
a) Expected: The vertical dotted line should start from the title's dot, and end at the last ToC section header. Actual: The line is extending from top to bottom of the screen.
b) Dots forming the dotted line should be 2dp diameter, and are circular (ie 1dp border radii) and ~8dp apart. Actual: Dots are 2dp squares.
c) Expected: The circular marker next to the Article title should be vertically centered on the first line of the article title. Actual: The marker is sitting about ~6dp higher than expected.

hi @Dbrant - per conversation with @Charlotte - let's push this to BETA only and monitor usage and feedback.

Testing with BLU Dash L2 (Android 6) and Wikipedia app build version 2.7.237-alpha-2018-07-18. According to the screencaps below this is working when tapping the article (the indicator appears and moves along the screen), TOC opens when indicator is tapped (no need to long press, tap is fine), active TOC section highlights in blue, and tapping outside the TOC closes it. The keyword in the Design Details is "or" as swiping will not open or close the TOC on this particular Android device.

Moving back to K board and bumping styling comment for @Dbrant

In T165964#4481019, @RHo wrote:

hi @Dbrant - I've updated the styling for H2 and H3s. You can refer to the updated Zeplin mocks (ER09 and ER10), but essentially the changes are:

• H2 top level section headings use the serif font, matching the headings in the article content
• H3 section headings use Roboto Regular 14sp

BTW, have noticed that there are still a couple of visual design issues pending fix:
a) Expected: The vertical dotted line should start from the title's dot, and end at the last ToC section header. Actual: The line is extending from top to bottom of the screen.
b) Dots forming the dotted line should be 2dp diameter, and are circular (ie 1dp border radii) and ~8dp apart. Actual: Dots are 2dp squares.
c) Expected: The circular marker next to the Article title should be vertically centered on the first line of the article title. Actual: The marker is sitting about ~6dp higher than expected.

Hi @Nicholas.tsg - the latest alpha should have an updated version where the swipe gesture works.

@RHo Testing with BLU Dash L2 (Android 6) and Wikipedia app build version 2.7.239-alpha-2018-08-08. It was a good thing the alpha link was provided last time - usually I get builds from here however, while the swipe gesture works on the latest alpha build, it does not currently have the TOC indicator, blue highlights, and other expected dynamic scrollable TOC elements.

hi @Dbrant - just checking if these updates are in-progress?

In T165964#4418853, @RHo wrote:

hi @Dbrant - just had a quick look and had some additional tweaks as well:

• Swiping left is not triggering opening of the ToC
• When the ToC element is swiped open, the element should appear alongside the section that is 'active'. For example in the following screenshot I have just opened the ToC when scrolled to "Death" but the scroller icon element is shown between References and External links

Visual design:

• The vertical dotted line should start from the title's dot, and end at the last ToC section header (at the moment it is extending from top to bottom of the screen). Dots should be 2dp diameter and 8dp apart (apologies the Sketch mock has stretched the dots to be ovals).
• Article title is the same font as the article title in the article (Droid Serif), with font-weight Regular and size 24sp (with line height 28dp).
• Section headings are normally in the Section title (Light: Base20) color, with the active section header in Primary color (Light: Accent50). At the moment, section headings are weirdly sometimes black and sometimes the Base20 color (as can be seen in the above screenshot)
• the active section heading should NOT change font-weight

Hi @Dbrant - in addition to the outstanding visual design items in the above comment, some other initial comments from user testing:

• ToC menu items only scroll when it exceeds the vertical height of the ToC pane

• The dotted line is not a static 'track', it should move with the ToC items when the ToC does scroll

• Scroller control often appears in the wrong place in the ToC when opened (esp. on shorter articles):

Hey @RHo - just talked with @Dbrant about these and am going to go ahead and waive this through as-is. Particular comments on your tweaks:

Vertical height - this is an artefact of setting the top and bottom margin. There will always be an edge case where there are just enough items in the ToC to make this scrolly.

Dotted line - would require a great deal of time to alter; more than is reasonable under the circumstances.

Scroller control - is an artefact of the short sections on these articles.

Hi @Charlotte @Dbrant - can we move the dotted line and scrolling item to be moved to a ux-debt task rather than being passed through? Particularly the dotted line item, since the movement when user scrolls within the ToC was noticed as being quite janky and unexpected both by internal and external user testing folks.

In T165964#4667085, @Charlotte wrote:

Hey @RHo - just talked with @Dbrant about these and am going to go ahead and waive this through as-is. Particular comments on your tweaks:

Vertical height - this is an artefact of setting the top and bottom margin. There will always be an edge case where there are just enough items in the ToC to make this scrolly.

Dotted line - would require a great deal of time to alter; more than is reasonable under the circumstances.

Scroller control - is an artefact of the short sections on these articles.

@RHo If you want to make a UX debt task for the dotted line, I'm happy to leave it in the UX debt backlog. The scroller control is - from my understanding of what @Dbrant said anyhow - unlikely to be fixable in a way that actually makes it look better. What he suggested was to allow for additional space between ToC items in these instances, which to my mind would look just as strange. But please do suggest another solution if you have one!

In T165964#4669852, @Charlotte wrote:

@RHo If you want to make a UX debt task for the dotted line, I'm happy to leave it in the UX debt backlog. The scroller control is - from my understanding of what @Dbrant said anyhow - unlikely to be fixable in a way that actually makes it look better. What he suggested was to allow for additional space between ToC items in these instances, which to my mind would look just as strange. But please do suggest another solution if you have one!

Thanks, have filed the UX-debt task for the dotted line item T207276, but moving back since it looks like the visual design items have still yet to be addressed, perhaps lost in the comment history:

1. Top level section headings (H2s) should use the serif font, matching the headings in the article content
2. H3s should use Roboto Regular 14sp
3. Expected: The vertical dotted line should start from the title's dot, and end at the last ToC section header. Actual: The line is extending from top to bottom of the screen.
4. Dots forming the dotted line should be 2dp diameter, and are circular (ie 1dp border radii) and ~8dp apart. Actual: Dots are 2dp squares.
5. Expected: The circular marker next to the Article title should be vertically centered on the first line of the article title. Actual: The marker is sitting about ~6dp higher than expected.
   

Hi @Dbrant (cc @cmadeo) - given there's a fair amount of comments about the unstructured ToC, just wanted to bump this ticket about finishing the visual design items on this task. esp. points 1, 2 and 3.

In T165964#4674090, @RHo wrote:

In T165964#4669852, @Charlotte wrote:

@RHo If you want to make a UX debt task for the dotted line, I'm happy to leave it in the UX debt backlog. The scroller control is - from my understanding of what @Dbrant said anyhow - unlikely to be fixable in a way that actually makes it look better. What he suggested was to allow for additional space between ToC items in these instances, which to my mind would look just as strange. But please do suggest another solution if you have one!

Thanks, have filed the UX-debt task for the dotted line item T207276, but moving back since it looks like the visual design items have still yet to be addressed, perhaps lost in the comment history:

1. Top level section headings (H2s) should use the serif font, matching the headings in the article content
2. H3s should use Roboto Regular 14sp
3. Expected: The vertical dotted line should start from the title's dot, and end at the last ToC section header. Actual: The line is extending from top to bottom of the screen.
4. Dots forming the dotted line should be 2dp diameter, and are circular (ie 1dp border radii) and ~8dp apart. Actual: Dots are 2dp squares.
5. Expected: The circular marker next to the Article title should be vertically centered on the first line of the article title. Actual: The marker is sitting about ~6dp higher than expected.
   

+1 to @RHo's comment above. I'm realizing now that this would have probably been something that would have come up if we had tested with existing users rather than new users, so my apologies for that.

Perhaps we can also sneak in https://phabricator.wikimedia.org/T208060 ?

Change 471740 had a related patch set uploaded (by Dbrant; owner: Dbrant):
[apps/android/wikipedia@master] Design tweaks in ToC.

https://gerrit.wikimedia.org/r/471740

Change 471740 merged by jenkins-bot:
[apps/android/wikipedia@master] Design tweaks in ToC.

https://gerrit.wikimedia.org/r/471740

@ABorbaWMF - Couldn't address Rita's points 3 and 4, so please sign off if the rest of the points look fine.

Looks good to me on 2.7.264-alpha-2018-11-08 and a few of the previous builds as well. Tested on a few devices.