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

Comments

Projects
None yet
7 participants
@afercia
Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Contributor Author

afercia commented Mar 5, 2018

See also #4411 for some more shortcuts.

@nic-bertino

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link
Contributor

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 afercia added the Needs Design label Mar 7, 2018

@afercia

This comment has been minimized.

Copy link
Contributor Author

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 modified the milestones: Merge Proposal, Merge Proposal: Accessibility, WordPress 5.0 Apr 12, 2018

@karmatosed

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link

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