TRACKING: Improve hotkey descriptions, categories & accuracy

[neiljp]

Description

The current help is organized into categories, with each hotkey falling into one of these, with a matching description.

As hotkeys have developed over time, they have been placed into best-fit categories, and the placement and categories themselves have been slowly reworked in the past as hotkeys become more widespread. We've now reached a significant set of documented hotkeys, where placement and description has become in need of reworking to improve the utility of the help system.

Improving hotkey category placement has benefits for the general help menu. Hotkey description improvements also have long-term benefits for supporting development work on the contextual help system (#515, #290), with which this work may overlap.

• Find hotkeys missing or not listed in the help
  • urwid-readline keys (Improve the handling of editor actions as a help category #1494)
    • Lint for missing hotkeys
    • POSSIBLE adjusting autocorrect hotkey?
      (ctrl f=autocorrect, overriding right; ctrl b not documented)
  • narrow and composing/replying from user list (Add new help categories to remove parentheses (context) from help texts #1515)
  • narrow from left panel (buttons, not search)
    (POSSIBLE to combine button activation with hotkey COMMAND?)
• Indicate/lint hotkeys whose presence in keys.py is for help only
  • urwid-readline [library handles all of this] (External hotkey commands: tagging, linting and checking sync #1498 ?)
  • exiting app via ctrl c? [implicitly handled by signal-handler]
  • DISCUSS linting generally for COMMANDS not directly used?
• Clarify hotkeys which are too general
  • 'Enter' [Do-search vs New-line vs Trigger-widget] (Break down the generalized ENTER command #1497)
  • 'Esc' [Clear-search vs Exit-compose vs Exit-popup] (Break down the GO_BACK command into separate commands #1514)
• Use unambiguous consistent verbs/nouns in descriptions (possibly similar to web app?)
  • Migrate away from confusing API-specific narrow (noun) + narrowing (verb) usage
  • Capitalize Nouns (Standardize hotkey help text #1496, )
  • Related work: Glossary to support use across ZT ('popup' vs 'menu', user card/profile?, panels?, Compose 'box'?)
• Add categories: limit users reading long disconnected category lists, avoid parentheses
  (avoid too many very short categories (< 4 items))
  • Editing/urwid (Improve the handling of editor actions as a help category #1494)
  • "Narrowing" commands (Group narrowing commands and improve descriptions #1516)
  • "Entering compose" commands (Create new help categories related to opening compose box #1520)
  • DISCUSS Per-popup categories (remove popup parentheses) (Add new help categories to remove parentheses (context) from help texts #1515)
  • DISCUSS right-panel (remove user-list parentheses) (Add new help categories to remove parentheses (context) from help texts #1515)
  • DISCUSS left-panel (for narrowing)
• DISCUSS allowing hotkeys to appear in multiple categories?
  (raised by Niloth via Add multi-category support for key bindings. #1519)
• DISCUSS prioritizing presence of text-entry commands in help, or not?
  • backspace (not present) demonstrates behavior of ctrl h (present)
  • enter (present) demonstrates behavior of multiline text entry (vs enter-to-send)
• Improve synchronization with urwid widget hotkeys
  • Indicate space activates/triggers widgets (Break down the generalized ENTER command #1497)
  • POSSIBLE integration of urwid commandmap's? (can we benefit from them?)
• POSSIBLE key adjustments
  • Remove S? (no longer in web app?) Retain command but hide, for existing users?
• DISCUSS Include contextual vs next-unread narrowing in descriptions?

NOTE:

• Initial discussion in zulip-terminal > Re-Categorization of Hotkeys started by @Niloth-p
• The above tasks/aspects are inspired by the above discussion and subsequent related PRs
• As work progresses, tasks may be added/removed/edited/closed as-appropriate
• DISCUSS is intended to suggest this (or sub-tasks) likely needs further discussion
• POSSIBLE are more speculative points
• Due to the above points, not all tasks will likely be completed before this issue is closed

---

Further summarized points to ensure are integrated:

1. from @Niloth-p's follow-up points: (Group narrowing commands and improve descriptions #1516 (comment))

• All Messages -> Combined Feed everywhere
• All DMs -> your DM feed or equivalent
• Replace "narrow" with "message view" or others in user-facing documentation like the user tutorial (similarly "narrowing", in some way)
• Consider casefix changes to parts of the UI like - All Messages and Direct Messages, possibly when starting to use "feed" terminology
• Add a new key binding mentioning that 'Enter' activates narrowing buttons, vs current ACTIVATE_BUTTON
  (maybe in a context, since it doesn't fit in an obvious category? See #zulip-terminal>Restructure Key Bindings and Supporting Help Multi-categories #T1519).

2. Also clarify s/S work in stream/topic, but while s zooms in with DMs, S does not zoom out - this is a benefit of z.

3. Possible FAQ entry for different hotkeys from web app, explaining history/why?

[zulipbot]

Hello @zulip/server-hotkeys members, this issue was labeled with the "area: hotkeys" label, so you may want to check it out!