Recent text for review:

<dt>Improving accessibility</dt>
<dd>Drupal's built in WYSIWYG editor (CKEditor) comes with a number of <a href="http://docs.ckeditor.com/#!/guide/dev_a11y">accessibility enhancements</a>. CKEditor comes with built in <a href="http://docs.ckeditor.com/#!/guide/dev_shortcuts">keyboard shortcuts</a> which can be beneficial for both power users and people who do not use mice. The integration of CKEditor eliminates common barriers so that most users should be able to benefit from it. The HTML markup that CKEditor generates supports accessibility.
<p>Examples:
<ul><li>Can be set up to generate semantic HTML5</li>
<li>Tables can be configured with table headers, caption/summary elements</li>
<li>Alt text required on uploaded images (can be overridden)</li>
<li>Default HTML5 figure/figcaption generation</li></ul></p>
<p>Note that some configuration options can be enhanced to make it easier for authors to create accessible content.
<ul><li>Adding the Format toolbar allows users to add a header</li>
<li>A language toolbar button can be added to CKEditor to improve the accessibility of multilingual documents</li>
<li>If the author is pasting in text from another editor, consider adding the Paste from word button or paste text to strip out unwanted code</li></ul></p></dd>

To help author more accessible content (according to ATAG 2.0) adding specific documentation on D8's accessibility will help people learn what is. In ATAG A.4.2 they outline in more detail best practices in "document the user interface, including all accessibility features."

So on the help pages here /admin/help/ckeditor we could add a section at the bottom, something like:

<p>CKEditor strives to be one of the most accessible WYSIWYG editors available, which is one of the reasons it was selected for Drupal Core.</p> 
<ul>
<li>We have configured CKEditor so that Alternative Text (alt text) is required by default when uploading images.</li>  
<li>When tables include headings, the editor appends scope/id variables so that it is easier for assistive technology devices to navigate. </li>
<li>By default CKEditor buttons comes enabled with more semantic options like <strong>, <em> and <h1>-<h6>.  This ensures that it is conveying proper meaning to your users.</li>
</ul>

I expect that there are more elements that can be included.

Brief beta evaluation This only changes hook_help() documentation so is fine at this stage.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

There are, in my opinion, several problems with the proposal here:

a) "strives", "why it was chosen", etc. -- this is marketing language, not help, and does not belong here. It may belong on an Accessibility Overview of Drupal 8 or Accessibility Updates to Drupal 8 page on drupal.org.

b) The guideline you linked to asks that "For each authoring tool feature that is used to meet Part A of ATAG 2.0, at least one of the following is true: ... Described in the Documentation: Use of the feature is explained in the authoring tool's documentation".

So, we should be describing how to use accessibility features -- either features that (from the other guideline) "make the authoring tools themselves accessible" or ""help authors create more accessible web content".

c) We need to respect the structure of the hook_help() page. There is an About section and a Uses section.

In About, the first sentence currently says:

The CKEditor module provides a visual text editor and adds a toolbar to text fields.

I think it would be appropriate to add "accessible" to this, maybe:

The CKEditor module provides a highly-accessible, highly-usable visual text editor and adds a toolbar to text fields.

We could also add an additional paragraph, something like this:

The HTML markup that CKEditor generates supports accessibility. Examples:
- (talk about semantic markup)
- (talk about table stuff)
- etc.

Note that if we add an additional paragraph or UL list to About, the "For more information..." sentence should also be split off into its own paragraph and put at the end of the About section.

d) In Uses, each section should start with an -ing verb in the header, and should describe how to do something with the header. This is where to add information about how to use the accessibility features. I am not sure if there are CKEditor features that need their own sections added here?

But whether there are new sections to be added or not, we probably need to add to the Configuring section, a note like:

Note that some configuration options can be used to prompt or enable content authors to make more accessible content. Examples:
- The image plugin should be configured (as it is by default) to require an alt tag on all images.
...

Wim Leers’s picture

Title: Document accessibility features in ckeditor » Document accessibility features in CKEditor
mgifford’s picture

Issue summary: View changes
mgifford’s picture

Issue summary: View changes
mgifford’s picture

Issue summary: View changes
mgifford’s picture

I'm hoping that some of this can come from http://docs.cksource.com/CKEditor_3.x/Users_Guide/Accessibility

Unfortunately, it's way out of date and still referencing the 3.x branch.

EDIT: I filed an issue about this here https://github.com/ckeditor/ckeditor-docs/issues/28

mgifford’s picture

I just got notified that the updates have been done to the main CKEditor site:
http://sdk.ckeditor.com/samples/accessibility.html
http://docs.ckeditor.com/#!/guide/dev_shortcuts

I think we should probably provide a link to docs.ckeditor.com, probably to both Keyboard Shortcuts & Page Navigation Using the "Tab" Key

Including the instruction that Alt+0 opens the Accessibility Instructions dialog window could be useful.

Not sure what other things to highlight from this.

Wim Leers’s picture

Issue tags: +DrupalCamp Ghent 2014, +sprint
Wim Leers’s picture

Issue tags: -sprint
Wim Leers’s picture

Issue tags: -DrupalCamp Ghent 2014
mgifford’s picture

Status: Active » Needs review
FileSize
1.81 KB

How's this as a start. I've decided not to use the link about the tab key. It really doesn't make sense given that the Tab page is mostly for developers.

Too bad it didn't get done in Ghent, but it should be a simple thing to bring in I think.

Status: Needs review » Needs work

The last submitted patch, 12: CKEditor-atag-docs-2308515-12.patch, failed testing.

jhodgdon’s picture

Good start... it seems to be missing a lot of the information that was discussed in the original issue and comment #1 though? Also a nitpick: there is an extra space at the end of the string before the closing '.

mgifford’s picture

Thanks for that @jhodgdon - there's also this link that's just been published:
http://docs.ckeditor.com/#!/guide/dev_a11y

mgifford’s picture

Issue summary: View changes
Status: Needs work » Needs review
FileSize
4.55 KB

From #1
a) removed the marketing language
b) i add a bit more, but I'm not good at this stuff... "The integration of CKEditor eliminates common barriers so that most users should be able to benefit from it. The use of a common editing tool can also help to produce more semantic HTML." - most of the improvements however are documented on the CKEditor pages.
c) Using existing framework.
Adding "The CKEditor module provides a highly-accessible, highly-usable visual text editor and adds a toolbar to text fields."
I broke the examples off into a new paragraph.
d) We've got a "-ing verb in the header"
Added more options of how to add in buttons to improve the editor's accessibility too.

mgifford’s picture

Issue summary: View changes
jhodgdon’s picture

Status: Needs review » Needs work

OK...

I have a few suggestions to make, and/or questions:

a) Are these really "accessibility enhancements" or just "accessibility features"? To me, "enhancements" implies there is an un-enhanced version... Let's just call them features.

b) Grammar/punctuation: "blah blah blah, which blah blah blah" ==> You need a comma before "which" when it is used as a conjunction. Or it should be changed to "that" if it is not really a conjunction.

c) "The integration of CKEditor eliminates common barriers so that most users should be able to benefit from it."
- Integration ... of what into what?
- common barriers ... to what?
- "it" at the end -- what does this refer to?

d) We generally don't want the HTML markup to be put into the translatable string. And we also don't want PHP code lines that start at position 0 in the middle of functions. So the line breaks in the string, and the UL list markup, are kind of a problem.

e) Markup: Here is the structure you've created:

<dd> ... some text ... <p> ... text ... <ul><li>...</li>...</ul></p> <p>...</p> </dd>

This is all mixed up. If you're going to use P tags, make sure everything is in a P tag. And UL should not be within P as far as I know. Probably this would be better off split up into several DT/DD sections rather than lumping it all together.

f) Every UL list should have : on the line before it.

g) Really I think that only the section on the options belongs in a section called "Improving accessibility". The rest seems to be describing the generic features of CKEditor, so I don't see how it would count as "improving" -- compared to what? So either the header is wrong or we need this broken up into multiple sections with more accurate titles... and I think (see e) that it needs breaking up anyway. Maybe some of it belongs in a new paragraph in About, rather than Uses?

h) Some of the descriptions say you need to configure something but it doesn't explain how. This is supposed to be the Help page, and more particularly the Uses section, so it needs to be focused on how to do things, and it needs to provide the necessary information on how to do things.

Wim Leers’s picture

http://docs.ckeditor.com/#!/guide/dev_a11y was just announced on the CKEditor blog, but I see that mgifford already reported this in #15. :)

Wim Leers’s picture

http://docs.ckeditor.com/#!/guide/dev_a11y was just announced on the CKEditor blog, but I see that mgifford already reported this in #15. :)

mgifford’s picture

@Wim Leers - I was talking about documentation issues with Anna Tomanek of CKEditor and she let me know it was updated.

Thanks @jhodgdon

a) accessibility enhancements / accessibility features - NP.

b) I think we want which / that - I don't see it as a conjunction.

c) How about "CKEditor eliminates common barriers to users with disabilities so that more users than ever will be able to benefit from the use of this powerful editor."

d/e/f) that can all be cleaned up for sure.

g) Most users aren't going to know about the accessibility features that come with CKEditor. Part of this is to give users an oversight as to some of the improvements made to CKEditor. I'm happy to move some of the content from the Uses section to an About section. Which parts though?

h) Is this in the examples? ie. "Tables can be configured with table headers, caption/summary elements". I'm bad at documentation. So I should describe where to go to enable this? I guess I just wanted to have something short to let them know it was there.

Maybe we should simplify this and mostly point folks to the CKEditor page?

Wim Leers’s picture

I was talking about documentation issues with Anna Tomanek of CKEditor and she let me know it was updated.

Cool :)

Maybe we should simplify this and mostly point folks to the CKEditor page?

Without having been involved in this issue or read the recent discussion — this sounds eminently sensible!

jhodgdon’s picture

Phrases like "more users than ever" and "this powerful editor" to me are marketing, not documentation. Let's stick to documenting what the Drupal CKEditor module and the CKEditor editor do or can do (in the About section), and how to use or configure it (in the Uses section) please.

Links are fine to include, but if there is *essential* information, it is probably best to put it in the hook_help() unless the CKEditor web site is translated into many languages (is it translated at all?). Drupal has many translations, and the hook_help() is part of the translated text.

mgifford’s picture

Status: Needs work » Needs review
FileSize
3.94 KB

Hopefully this is simple enough. I don't know how many languages the CKEditor help text is translated into but I've asked. It doesn't seem translated at all at the moment. Definitely good to prioritize that, but we also don't want to be adding a great deal of text to this.

jhodgdon’s picture

Status: Needs review » Needs work

Looks pretty good, as far as being concise and the content you're presenting!

A few minor things to fix:
- We don't normally want to use the word "Drupal" in help or UI text. So a small rewrite there would be good to leave that out.
- Before "which" you need a comma, or else it should be "that".
- "In the editor, alt text is required by default on images added through CKEditor" -- this seems a bit redundant to say "in the editor" and "through CKEditor"?
- "(Note that this can be easily overridden)" should not have caps here
- Too many uses of "easily". Just say it can be done, or better yet, explain how to do it or where to do it. Or remove the word "easily". It's probably not actually obvious or really easy to do, and saying it's easy without explaining how is kind of discouraging for people.

And one other thing... Although the heading is "Generating accessible content", the paragraph is a mix of information about accessible content and the accessibility features of the editor itself. Split it up into two sections... they're not the same thing.

Thanks!

mgifford’s picture

Status: Needs work » Needs review
FileSize
4.02 KB

Ok, I think I have all of those corrections in place.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Looks reasonable to me, thanks!

jhodgdon’s picture

Issue summary: View changes

Added brief beta eval

mgifford’s picture

Thanks!

alexpott’s picture

Status: Reviewed & tested by the community » Fixed

Committed 1569740 and pushed to 8.0.x. Thanks!

Thanks for adding the beta evaluation to the issue summary.

  • alexpott committed 1569740 on 8.0.x
    Issue #2308515 by mgifford, jhodgdon, Wim Leers: Document accessibility...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.