Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

User guide and keyboard shortcuts documentation #5420

Closed
afercia opened this issue Mar 5, 2018 · 12 comments
Closed

User guide and keyboard shortcuts documentation #5420

afercia opened this issue Mar 5, 2018 · 12 comments

Comments

@afercia
Copy link
Contributor

@afercia afercia commented Mar 5, 2018

In the Classic editor, there's the Help section with a (limited) user guide about:

  • editing the title and the post
  • inserting media
  • publish settings
  • discussion settings

screen shot 2018-03-05 at 21 08 50

there's also a modal with a list of all the available keyboard shortcuts:

screen shot 2018-03-05 at 21 09 12

To my knowledge, in Gutenberg there's no help or user guide at all, not sure if this was discussed at some point. I'd strongly recommend to start thinking at a user guide. Whether it lives in the admin or on an external page / handbook, it should be easily discoverable.

As per keyboard and screen reader users, they need a well documented list of all the available keyboard shortcuts in Gutenberg, plus a guide to some of the available accessibility features, e.g. the Ctrl + backtick shortcut to navigate through the main editor regions.

We've discussed this during today's accessibility meeting and agreed the list of keyboard shortcuts is essential to effectively use the editor and should be available since version 1.

@afercia
Copy link
Contributor Author

@afercia afercia commented Mar 5, 2018

Related:
#71 and #2980
not the same thing though, since 2980 is about displaying shortcuts within the various menus, close to the related control.

@afercia
Copy link
Contributor Author

@afercia afercia commented Mar 5, 2018

See also #4411 for some more shortcuts.

@nic-bertino
Copy link

@nic-bertino nic-bertino commented Mar 6, 2018

Building on #3218, I think this UI element should incorporate customization as well (per #3218 (comment)), as it keeps that control close to the user.

Choosing where to fold this into the UI might be a bit of a challenge, but for now, it might make the most sense to have it under the post triple dot:

image

Again, I certainly think there are better ways to introduce the keyboard shortcut palette, and I'll continue mocking up some suggestions.

@postphotos
Copy link
Contributor

@postphotos postphotos commented Mar 7, 2018

@nic-bertino , maybe it can be under Tools > Keyboard Shortcuts? It makes sense to have a similar modal, a la Classic Editor.

@afercia
Copy link
Contributor Author

@afercia afercia commented Mar 7, 2018

Considering a list of keyboard shortcuts is mainly meant for keyboard and assistive technologies users, I'd consider to improve the current experience and avoid a modal. Modals are always tricky for those users.

Adding the design label because both the help / user guide and the list of shortcuts need some thinking 🙂

@afercia afercia added this to the Merge Proposal milestone Mar 19, 2018
@karmatosed karmatosed removed this from the Merge Proposal milestone Apr 12, 2018
@karmatosed karmatosed added this to the Merge Proposal: Accessibility milestone Apr 12, 2018
@karmatosed karmatosed removed this from the Merge Proposal: Accessibility milestone Apr 13, 2018
@karmatosed karmatosed added this to the WordPress 5.0 milestone Apr 13, 2018
@karmatosed
Copy link
Member

@karmatosed karmatosed commented Apr 17, 2018

@afercia with regards to the design of this, are there any accessible good examples in other applications we could learn from?

@afercia
Copy link
Contributor Author

@afercia afercia commented Apr 18, 2018

@karmatosed not off the top of my head. In Gmail for example, typing ? makes a list of keyboard shortcuts appear but that's not exactly what I'd like to see in Gutenberg. Maybe we should first consider if we want the Help section in Gutenbreg or on .org.
In the first case, maybe use the "screen takeover" (the one meant for plugins)? Regardless, I'd tend to think the most important thing is that the link or button to access the Help section should be easily discoverable. /Cc @rianrietveld for her experience in documentation 🙂

@rianrietveld
Copy link
Member

@rianrietveld rianrietveld commented Apr 18, 2018

My experience is that not many people discover the help text, as it is now in the classic editor.
So a better icon/text to help text is definitely needed.

Thinking of all the stuff we need to explain, I wonder if we should integrate all the help text inside the Gutenberg editor. That will become a usability nightmare I guess, fitting everything in modals, screen takeover, whatever.

Thinking out load and maybe totally out of context:
All the shortcuts, AT manuals, etc can be placed in documentation on WordPress.org. Why not just have a clear icon for help and link to the docs applicable in the right language? So keep everything on .org (and translate there too) . And don't burden the UI with complicated constructions.

@karmatosed
Copy link
Member

@karmatosed karmatosed commented Apr 18, 2018

My experience is that not many people discover the help text, as it is now in the classic editor.
So a better icon/text to help text is definitely needed.

This is pretty reflective of my own experience.

All the shortcuts, AT manuals, etc can be placed in documentation on WordPress.org. Why not just have a clear icon for help and link to the docs applicable in the right language? So keep everything on .org (and translate there too) . And don't burden the UI with complicated constructions.

@rianrietveld do you imagine it as a link to an external source?

@rianrietveld
Copy link
Member

@rianrietveld rianrietveld commented Apr 18, 2018

@karmatosed

do you imagine it as a link to an external source?

Yes, make it as simple as that

@mtias
Copy link
Contributor

@mtias mtias commented Oct 7, 2018

We now have both the modal listing available shortcuts and "tips" guiding specific areas of the interface. Let's focus any ideas and enhancements on new issues.

@jcklpe
Copy link

@jcklpe jcklpe commented Nov 12, 2018

@mtias Maybe I missed something but didn't there used to be a bunch of extra shortcuts? I don't see them listed in the shortcuts section. Stuff like using markdown style to auto select different blocks etc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants