help-docs: Document "Mute/Unmute topic" mobile app feature #22221

duncan64 · 2022-06-09T02:29:24Z

This pull request adds documentation for muting and unmuting topics on mobile.

Fixes #22146.

Rendered docs

Current docs

Desktop/Web instructions

Mobile instructions

Testing

I tested these instructions on the web, desktop, and iOS apps. I haven’t got the apps building for the Android or iPad simulators yet. However, I’ve reviewed this list of differences between mobile platforms and I don’t think any of these differences will affect the instructions in this pull request.

Writing choices

I took the approach suggested in Refactor the instructions for "Resolve a topic" and "Mute a topic" so that a Mobile tab can be used #22178. First, I merged the two ways of muting a topic into one set of instructions. Then, I added new tabs containing instructions for mobile.
There are three ways to access the long-press menu (topic bar, top bar, topics list). I described the first two methods for muting topics, but described the last method for unmuting topics. I think it makes most sense to mute a topic while you’re reading its messages, but when unmuting topics, it’s easiest to do this from the topics list.

Remaining concerns

Is this the preferred way to unmute topics on mobile? It’s less convenient than on desktop/web because the user must tap into each stream one-by-one, rather than seeing a single list of all muted topics. Am I overlooking a better way to do this?
Will readers be confused by the term ‘topic bar’? At first, I thought this was the bar at the top of the screen. Could a screenshot be helpful here?
This article links to the Muted topics settings page. However, this link won’t work for the desktop app because it will open in the user’s browser. Should this link be replaced with a description of how to open the settings page?
There’s some duplication related to the topic-long-press-menu.md macro. The macro states: “Press and hold the topic bar to access the long-press menu.” However I didn’t use the macro because I wanted the step to say: “Press and hold a topic name to access the long-press menu.” Is this amount of duplication ok?

Self-review checklist

Self-reviewed the changes for clarity and maintainability
(variable names, code reuse, readability, etc.).

Communicate decisions, questions, and potential concerns.

Explains differences from previous plans (e.g., issue description).
Highlights technical choices and bugs encountered.
Calls out remaining decisions and concerns.
Automated tests verify logic where appropriate.

Individual commits are ready for review (see commit discipline).

Each commit is a coherent idea.
Commit message(s) explain reasoning and motivation for changes.

Completed manual review and testing of the following:

Visual appearance of the changes.
Responsiveness and internationalization.
Strings and tooltips.
End-to-end functionality of buttons, interactions and flows.
Corner cases, error conditions, and easily imagined bugs.

alya · 2022-06-10T06:03:09Z

Thanks for the PR and the detailed and clear explanations/questions -- this looks great! I'll respond to the concerns in separate messages.

alya · 2022-06-10T06:03:18Z

@gnprice could you take a look as well?

alya · 2022-06-10T06:04:26Z

Is this the preferred way to unmute topics on mobile? It’s less convenient than on desktop/web because the user must tap into each stream one-by-one, rather than seeing a single list of all muted topics. Am I overlooking a better way to do this?

@gnprice let me know if I'm missing something, but I think that's right.

alya · 2022-06-10T06:10:12Z

Will readers be confused by the term ‘topic bar’? At first, I thought this was the bar at the top of the screen. Could a screenshot be helpful here?

Mm, good question!

I think one thing that might be helpful as a follow-up is to put together an article that describes the mobile app in general. Besides serving as an intro, it would give us a way to name all the key screens and components, and refer back to that page any time the terms might be unclear.

That way, we could also include screenshots on that page, and avoid using them (and needing to update them) across a bunch of pages. I don't think we have an exact analogy for this sort of article, but https://zulip.com/help/streams-and-topics is probably the closest.

@duncan64 @gnprice what do you think?

alya · 2022-06-10T06:13:34Z

There’s some duplication related to the topic-long-press-menu.md macro. The macro states: “Press and hold the topic bar to access the long-press menu.” However I didn’t use the macro because I wanted the step to say: “Press and hold a topic name to access the long-press menu.” Is this amount of duplication ok?

When reviewing the PR that added the macro (#22158), I recall thinking that we might want to have it say "Press and hold the topic name" rather than "Press and hold the topic bar," though it looks like I forgot to raise that question.

What do folks think about making that change to make the language more generally applicable? It might be more clear in any case given the potential confusion with the bar at the top that @duncan64 points out above. CC @drrosa

alya · 2022-06-10T06:23:40Z

This article links to the Muted topics settings page. However, this link won’t work for the desktop app because it will open in the user’s browser. Should this link be replaced with a description of how to open the settings page?

Mm, this question got me to dig in a bit to understand more about how the instructions vary based on how you access them.

If you go to https://zulip.com/help/mute-a-topic, you see the following (no link):
If you go to https://[your domain]//help/mute-a-topic, you see the link.

You'd probably get to this page from an in-app help link, either from the desktop app or the webapp.

If you get there from the webapp, it's a pretty smooth experience to have the settings link also open in your browser.

If you get there from the desktop app, it's perhaps a bit unexpected, and could be annoying if you are not currently logged into Zulip in your browser.

Chatting with @timabbott, he suggests that the best solution is to (eventually) implement deep linking for the desktop app, which we would like to do in any case to handle missed message emails better (cf. zulip/zulip-desktop#470, I think). Perhaps we're OK with the suboptimal help center link experience in the meantime.

alya · 2022-06-10T06:27:37Z

templates/zerver/help/mute-a-topic.md

 {settings_tab|muted-topics}

 1. Review and unmute any muted topics.

+{tab|mobile}
+
+1. Tap the streams (<i class="fa fa-hashtag"></i>) tab.


I wonder if we should format this as Streams, similarly to Recent topics on https://zulip.com/help/recent-topics?

I read that sort of formatting as meaning that the text is a label you can look for in the UI. Here, it's just an icon with no text (unless you're on an iPad, or IIRC if you're using screen-reading software.) So I think leaving it unformatted like this is good.

Good points! I forgot to explain why I chose to stylize the ‘streams’ and ‘topics list’ labels this way.

I came to the same reasoning as @gnprice, i.e. no emphasis because the labels do not appear in the UI (except on iPad).

Also, I chose to stay consistent with the Logging out article (under the iOS and Android instructions), which also describes tapping on icon-only buttons on mobile. However, I see there are many examples in the help center where the label is bold, and many examples where it is not bold.

Since we’re starting to document more articles for mobile, it might be a good time to update Writing help center articles with more guidance on how to refer to mobile buttons. I think it would be good to decide on:

Whether text labels for icon-only buttons should be bold.

In which cases to use a capital letter.

Whether icons should be labelled based on their shape or function (e.g. ‘gear’ vs. ‘settings’).

Whether the icon should appear before the label or after it in parenthesis.

For now, I’ll make these labels bold and capitalized, but I’m ok with either way of stylizing them.

I think it would be good to decide on:

Whether text labels for icon-only buttons should be bold.

In which cases to use a capital letter.

Whether icons should be labelled based on their shape or function (e.g. ‘gear’ vs. ‘settings’).

Whether the icon should appear before the label or after it in parenthesis.

I agree, these are all good questions! And I don't think we currently have consistent answers to any of them.

timabbott · 2022-06-10T17:52:50Z

templates/zerver/help/mute-a-topic.md

@@ -38,9 +27,9 @@ They also do not contribute to stream unread counts.

 {settings_tab|muted-topics}

-{end_tabs}
+1. Review and unmute any muted topics.


This is a preexisting issue, but the "unmute any muted topics" phrasing feels a bit off to me, maybe in that it has a weak connotation that we're suggesting you might want to unmute all muted topics, not just the ones you're looking to adjust? Kinda reads in the same way as "fix any errors in this list of errors".

Good call. I changed this to “Click Unmute next to each topic you want to unmute.”

drrosa · 2022-06-10T18:26:23Z

When reviewing the PR that added the macro (#22158), I recall thinking that we might want to have it say "Press and hold the topic name" rather than "Press and hold the topic bar," though it looks like I forgot to raise that question.

I think it's worth considering that if we use the term "topic name", we might be telling users that they can access the long-press menu only from a smaller spot on their screen. This action would probably work well for most users, but this impression could also turn into a nuisance for other users.

But if we use a term such as "topic bar", we would be letting users know they have a wider surface area to choose from on the screen. Ideally, the term should hint that the long-press menu can be accessed using any spot within that region so that users can choose whatever is more convenient/accessible for them.

What do folks think about making that change to make the language more generally applicable? It might be more clear in any case given the potential confusion with the bar at the top that @duncan64 points out above. CC @drrosa

I can imagine users feeling confused upon reading the instructions and viewing a stream narrow at first. But in this case, whichever term we choose to refer to the topic probably wouldn't really make much of a difference for new users. I think the source of confusion is that they are yet to learn which components of the app refer to Topics and which ones refer to Streams. As @alya mentioned, I also think that an article describing the mobile app with named key screens and components plus screenshots would be helpful.

Also, I think it might be best to change it to "Press and hold a topic..." instead of "Press and hold the topic...". In a stream narrow view, this wording might be a better hint that we are referring to a topic bar rather than the bigger bar at the top. I think this phrasing would also make sense in other views, and the Tip already brings attention to the top bar when the user is viewing a topic narrow. I think this small change would clarify things a bit more for users who may find it confusing at first, as @duncan64 pointed out.

gnprice · 2022-06-10T18:43:51Z

Is this the preferred way to unmute topics on mobile? It’s less convenient than on desktop/web because the user must tap into each stream one-by-one, rather than seeing a single list of all muted topics. Am I overlooking a better way to do this?

Yeah, we don't currently have such a list on mobile. Perhaps we should! I think I wasn't actually aware until just now that that feature existed on web/desktop.

Another aspect of this way which is potentially frustrating for the user is that:

Select a stream containing topics you want to unmute.

Tap the topics list (︙) icon.

in step 2, if the user had any unread messages in that stream (and hasn't enabled "Do not mark messages read on scroll" in settings), then this will mark the first screenful of those messages as read.

But we don't currently have a better way in that respect either (short of going and enabling that setting, which is probably too much for these instructions.) We have an open issue zulip/zulip-mobile#4535 for making it so that you could instead long-press on the stream in that streams tab (as well as other places the stream appears, like the main "inbox"/"unread" screen.)

So I think this is currently the best way we can recommend.

gnprice · 2022-06-10T18:58:05Z

I think it's important to consider that if we use the term "topic name", we might be telling users that they can access the long-press menu only from a smaller spot on their screen. This action would probably work well for most users, but this impression could also turn into a nuisance for other users.

But if we use the term "topic bar", we would be letting users know they have a wider surface area to choose from on the screen.

Hmm, that's an interesting point.

In the case of the topic list for a stream (which is where "topic name" currently is used in this PR), "topic bar" wouldn't work, I think -- unlike in a stream narrow where there's a distinct bar introducing a set of messages on a new topic, in the topic list the topics are just items in a list. The same thing applies on the inbox/unread view, I think -- the topics are just the items making up the list, though the stream headings are visually set off in a way that could be called "bars".

One phrasing that could work well in both the topic list for a stream (so in this PR) and in the inbox/unread view is to say "Press and hold a topic to …". This would be similar to "Select a stream …" a couple of steps earlier. That might make people more likely to read it as saying (correctly) that the whole area that's about a given topic, extending the whole width of the screen, is the region they can press to act on that topic.

gnprice · 2022-06-10T19:11:24Z

Will readers be confused by the term ‘topic bar’? At first, I thought this was the bar at the top of the screen.

Hmm, yeah. Possibly this calls for a couple of different instructions, depending on what kind of view the user is in when they encounter the messages:

If they're viewing a message list where the messages from that topic are interleaved with other messages -- could be the message list for the whole stream, or could be search results or one of the special views at the top of the home screen, namely "all messages" or "@-mentions" or "starred messages -- then every time a message appears that isn't to the same conversation as a message immediately above it, there will be a "recipient bar" introducing it, saying where that block of messages were sent. When it's a stream message (so has a topic), one might call that a "topic bar". When you long-press on that, you get the long-press menu for that topic, including the option to mute it.
If they're viewing the message list that is for that topic, then there are no recipient bars. But that's because the app bar at the top of the screen can do the job of a recipient bar (because all the messages are to the same place): it shows the stream's name and also the topic's. And if you long-press on that, you again get the long-press menu for that topic.

In particular, there's no screen where both of those are available: if you have topic/recipient bars, then the app bar is broader than the topic, and long-pressing it won't give the topic menu.

Both of those feel like pretty plausible situations for a user to be in when they decide they want to mute a topic -- basically depending on whether they prefer to read Zulip topic by topic, or in interleaved views, and I think we have significant swaths of users who prefer each of those.

gnprice · 2022-06-10T19:14:11Z

I think one thing that might be helpful as a follow-up is to put together an article that describes the mobile app in general. Besides serving as an intro, it would give us a way to name all the key screens and components, and refer back to that page any time the terms might be unclear.

Yeah, that's a good idea. As the discussion in this thread illustrates, e.g.:

the main "inbox"/"unread" screen

we don't currently have consistent names even amongst ourselves for those key screens and components 🙂 and it'd be good to work out conventions for them.

gnprice · 2022-06-10T19:15:37Z

OK, done with comments. Thanks @duncan64 for writing this up! I especially appreciate the good set of questions at the end.

duncan64 · 2022-06-12T03:16:44Z

I think one thing that might be helpful as a follow-up is to put together an article that describes the mobile app in general.

I agree, I think it would be helpful to have an article like this! 👍

duncan64 · 2022-06-12T03:36:27Z

When reviewing the PR that added the macro (#22158), I recall thinking that we might want to have it say "Press and hold the topic name" rather than "Press and hold the topic bar," though it looks like I forgot to raise that question.

What do folks think about making that change to make the language more generally applicable?

It looks like there are a few different wordings of this macro that make sense in different contexts:

Press and hold {a / the} {topic bar / topic name / top bar} to access the long-press menu.

The macro is only one line long, and there’s not a clear-cut version that works everywhere. So how about this approach: write the sentence out each time according to context, revisit after a few more mobile articles have been written, then decide if there’s a general wording that will work across all the articles?

duncan64 · 2022-06-12T03:42:55Z

Mm, this question got me to dig in a bit to understand more about how the instructions vary based on how you access them.

Thanks for digging into this! That’s really helpful, I hadn’t realized this macro renders differently based on the domain name.

The message recipient bar instructions are now contained in a tip block, as suggested in zulip#22178. This will allow adding mobile instructions to the article.

Fixes zulip#22146.

duncan64 · 2022-06-12T05:06:58Z

I edited a commit message to add Fixes #22146 as suggested by @zulipbot (and rebased while I was at it). Sorry for resetting everyone’s review status!

zulipbot · 2022-09-10T00:59:56Z

Heads up @duncan64, we just merged some commits that conflict with the changes you made in this pull request! You can review this repository's recent commits to see where the conflicts occur. Please rebase your feature branch against the upstream/main branch and resolve your pull request's merge conflicts accordingly.

doehyunbaek · 2022-12-12T04:16:48Z

Hi. Is there anything I could help to move this PR forward? I was looking for this exact feature and consulted zulip doc but couldn't find the relevant info and found at this issue instead.

alya · 2022-12-13T02:44:37Z

@drrosa I haven't reviewed the discussion above in any detail, but based on the comment above, I think we can make #22146 a priority among the mobile documentation issues.

alya · 2023-02-24T19:16:37Z

#22146 has been resolved via #24039. Thanks for your work on this, @duncan64 !

zulipbot added the size: M label Jun 9, 2022

duncan64 force-pushed the docs-mute-topic-mobile branch 2 times, most recently from 68f1556 to 8ce5817 Compare June 9, 2022 23:44

duncan64 changed the title ~~[WIP] help-docs: Document "Mute/Unmute topic" mobile app feature~~ help-docs: Document "Mute/Unmute topic" mobile app feature Jun 10, 2022

duncan64 marked this pull request as ready for review June 10, 2022 01:49

alya reviewed Jun 10, 2022

View reviewed changes

timabbott reviewed Jun 10, 2022

View reviewed changes

duncan64 added 4 commits June 12, 2022 17:03

help-docs: Consolidate "Mute a topic" instructions into one list.

adee730

The message recipient bar instructions are now contained in a tip block, as suggested in zulip#22178. This will allow adding mobile instructions to the article.

help-docs: Add mobile instructions to "Mute a topic".

c498b4c

Fixes zulip#22146.

help-docs: Bold and capitalize button labels in "Mute a topic".

f8a90ea

help-docs: Refine wording for unmuting topics on desktop/web.

6cfb994

duncan64 force-pushed the docs-mute-topic-mobile branch from 9856b1b to 6cfb994 Compare June 12, 2022 05:05

drrosa mentioned this pull request Jun 17, 2022

help-docs: Document "Resolve/Unresolve topic" mobile app feature. #22256

Merged

12 tasks

zulipbot added the has conflicts label Sep 10, 2022

drrosa mentioned this pull request Jan 12, 2023

help center: Add mobile instructions to "Mute a topic". #24039

Merged

7 tasks

alya closed this Feb 24, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

help-docs: Document "Mute/Unmute topic" mobile app feature #22221

help-docs: Document "Mute/Unmute topic" mobile app feature #22221

duncan64 commented Jun 9, 2022 •

edited

Loading

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya Jun 10, 2022 •

edited

Loading

gnprice Jun 10, 2022

duncan64 Jun 12, 2022

gnprice Jun 14, 2022

timabbott Jun 10, 2022 •

edited

Loading

duncan64 Jun 12, 2022

drrosa commented Jun 10, 2022 •

edited

Loading

gnprice commented Jun 10, 2022 •

edited

Loading

gnprice commented Jun 10, 2022

gnprice commented Jun 10, 2022

gnprice commented Jun 10, 2022

gnprice commented Jun 10, 2022

duncan64 commented Jun 12, 2022

duncan64 commented Jun 12, 2022

duncan64 commented Jun 12, 2022

duncan64 commented Jun 12, 2022

zulipbot commented Sep 10, 2022

doehyunbaek commented Dec 12, 2022

alya commented Dec 13, 2022

alya commented Feb 24, 2023

help-docs: Document "Mute/Unmute topic" mobile app feature #22221

help-docs: Document "Mute/Unmute topic" mobile app feature #22221

Conversation

duncan64 commented Jun 9, 2022 • edited Loading

Rendered docs

Testing

Writing choices

Remaining concerns

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya commented Jun 10, 2022

alya Jun 10, 2022 • edited Loading

Choose a reason for hiding this comment

gnprice Jun 10, 2022

Choose a reason for hiding this comment

duncan64 Jun 12, 2022

Choose a reason for hiding this comment

gnprice Jun 14, 2022

Choose a reason for hiding this comment

timabbott Jun 10, 2022 • edited Loading

Choose a reason for hiding this comment

duncan64 Jun 12, 2022

Choose a reason for hiding this comment

drrosa commented Jun 10, 2022 • edited Loading

gnprice commented Jun 10, 2022 • edited Loading

gnprice commented Jun 10, 2022

gnprice commented Jun 10, 2022

gnprice commented Jun 10, 2022

gnprice commented Jun 10, 2022

duncan64 commented Jun 12, 2022

duncan64 commented Jun 12, 2022

duncan64 commented Jun 12, 2022

duncan64 commented Jun 12, 2022

zulipbot commented Sep 10, 2022

doehyunbaek commented Dec 12, 2022

alya commented Dec 13, 2022

alya commented Feb 24, 2023

duncan64 commented Jun 9, 2022 •

edited

Loading

alya Jun 10, 2022 •

edited

Loading

timabbott Jun 10, 2022 •

edited

Loading

drrosa commented Jun 10, 2022 •

edited

Loading

gnprice commented Jun 10, 2022 •

edited

Loading