From e860d22d6172db02069c1cb66003885021ae3a9a Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Mon, 29 Aug 2022 17:24:32 +0200 Subject: [PATCH] docs: Update tutorial section on documenting keyboard shortcuts. Updates the tutorial in "Writing help center articles: Writing style" for using `` HTML elements when documenting keyboard shortcuts in help center articles. Also, adds section about the keyboard tip macro/syntax. --- docs/documentation/helpcenter.md | 35 ++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/documentation/helpcenter.md b/docs/documentation/helpcenter.md index 6d1e9dc3b6..5c7eb7e8ec 100644 --- a/docs/documentation/helpcenter.md +++ b/docs/documentation/helpcenter.md @@ -226,18 +226,19 @@ and used liberally. ### Keyboard shortcuts -Use backticks for each keyboard key in the shortcut (e.g. `Enter` or `R`). -For shortcuts with more than one key, add a plus sign (+) surrounded by -spaces in between the keys (e.g. `Ctrl` + `K`, instead of `Ctrl + K` or -`Ctrl`+`K` or `Ctrl` `K`). +Surround each keyboard key in the shortcut with `` HTML element start and +end tags (e.g., `Enter` or `R`). + +For shortcuts with more than one key, add a plus sign (+) surrounded by spaces +in between the keys (e.g., `Ctrl + K`). Any shortcut for +an arrow key (↑, ↓, ←, →) will also need the `"arrow-key"` CSS class included +in the `` start tag (e.g., ` ↑`). Use the labels one sees on the actual keyboard rather than the letter they produce when pressed (e.g. `R` and `Shift` + `R` rather than `r` and `R`). -**Note**: The existing help center documentation is inconsistent about this -([see this UI redesign issue](https://github.com/zulip/zulip/issues/21753)). -Therefore, if there are already some keyboard shortcuts in the existing help -center article, then it is more important to be consistent with those than -with the global style. +For symbols, such as `?` or `@`, that are produced through key combinations that +change depending on the user's keyboard layout, you should use the symbol as it +appears on a keyboard instead of any specific combination of keys. Use non-Mac keyboard keys; for example `Enter`, instead of `Return`. Zulip will automatically translate non-Mac keys to the Mac versions for users with a Mac @@ -247,6 +248,13 @@ change `has_mac_keyboard` in `/static/js/common.ts` to always return `True`. Then when you view your documentation changes in the development environment, the keyboard shortcuts should be rendered with Mac keys where appropriate. +If you're adding a tip to an article about a keyboard shortcut, you +should use the more specific keyboard [tip macro](#tips-and-warnings), +`!!! keyboard_tip ""`. In general, all keyboard shortcuts should be +documented on the [keyboard +shortcuts](https://zulip.com/help/keyboard-shortcuts) help center +article. + ## Markdown features Zulip's Markdown processor allows you to include several special features in @@ -380,6 +388,15 @@ users. instructions on how to reset it. ``` +A **keyboard tip** is a note for users to let them know that the same action +can also be accomplished via a [keyboard shortcut](#keyboard-shortcuts). + +```md +!!! keyboard_tip "" + + Use D to bring up your list of drafts. +``` + A **warning** is a note on what happens when there is some kind of problem. Tips are more common than warnings.