Re: [style guide] Tone section

To follow up with another thread to keep conversations on target…

Shawn, I'm glad you sent out the Intro to Accessibility draft<https://w3c.github.io/accessibility-intro/> so early because based on the edits I saw, it may be possible that we are not at all on the same page with regards to exactly how much we should be simplifying and tersifying our documents.

You did remove 2 unnecessary sections, but otherwise only removed about 10 words, added about 80, and actually raised the reading level a tiny bit.

I was hoping you were just cleaning up grammar etc. on a doc that you didn't intend to actually edit down because I left it out of the IA I sent out before I went on vacation, suggesting that it can stay where it is and we should put our effort into https://www.w3.org/WAI/intro/accessibility.


Unfortunately, your issues on github make me unsure.  Again, I suggested we leave https://www.w3.org/standards/webdesign/accessibility alone and add any good stuff from it to https://www.w3.org/WAI/intro/accessibility after we cut that one down by about half.

Let's talk through this!

Regards,
James


From: James Green <jgreen@visa.com<mailto:jgreen@visa.com>>
Date: Tuesday, July 25, 2017 at 7:44 PM
To: Sharron Rush <srush@knowbility.org<mailto:srush@knowbility.org>>, Eric Egert <ee@w3.org<mailto:ee@w3.org>>
Cc: Shawn Henry <shawn@w3.org<mailto:shawn@w3.org>>, wai-eo-editors <wai-eo-editors@w3.org<mailto:wai-eo-editors@w3.org>>
Subject: Re: [style guide] Tone section

Hey Shawn, to help me try to get on board, could you please share your reasons for having issue with 10th grade reading level? I included a testable guideline (more lax than AAA's 9th grade requirement) because without that, each editor must decide what "plain language" means.

Given that one of our 3 primary goals is to reduce the "wall of text effect", It seems fair to ask people to run the current pages and their resulting drafts through a Readability Test Tool<https://www.webpagefx.com/tools/read-able/> as part of their analysis. Will they hit 9th or 10th grade every time?  No, but it can help them decide if they are done simplifying.  Maybe it was Grade 17, but they got it down to 12?  Also, readability testing tools provide stats like number of words and sentences, meaning their use can also help editors see if they made much progress at tersifying.

To add clarity to my perspective, in the July 7 Survey<https://www.w3.org/2002/09/wbs/35532/EO-Weekly-7-Jul-2017/>, many of my comments were added to the style guide, but the following was not*: "This needs to be mentioned … so editors are clear that their primary job is to try to cut half of the sentences and half of the words…"

A couple notes on that:

  *   *I don't expect that phrase to be added to the style guide, but I do want some kind of CLEAR communication of what we are really trying to do so we get consistent results that make a difference.
  *   I said "try to cut" not "must cut" since we have to do what works, but we need a goal to start with.
  *   It's not just a normal style guide for writing new content, but an editor's guide for cutting down text.
  *   The style guide is well written and actually quite readable, but there's so much there, I don't think any of us could succinctly summarize the main goals if asked.  If we can't do that, we can't keep them in our heads while editing.

I think we need to be able to keep a summary of the style guide in our heads while editing. Perhaps we put a summary at the top that reads something along the lines of:

Editors, these are your goals (in order of importance):

  1.  SIMPLIFY & TERSIFY: Make content as simple and brief as possible. Cut words! Cut Sentences! Cut comma separated lists! Check with a Readability Test Tool<https://www.webpagefx.com/tools/read-able/>.
  2.  BULLETS & GRAPHICS: Break up passages when possible and appropriate.  Cut 1000 words and then make them a picture ;)
  3.  FRONT LOADED ACTION!: Put actions at the beginning of sentences, use active voice, and action statements!
  4.  VOICE & TONE: Voice and tone will vary, keep in mind for your document
  5.  SPELLING & PUNCTUATION: Follow WAI style guide for punctuation, spelling, grammar, etc.

Sorry if I seem to be holding us back at the style guide when everyone want to move on to editing, but I'm pressing these points because I think EO needs to get the style guide right and everybody be clear if this huge effort is going to be worth our time.

Regards,
James

From: Sharron Rush <srush@knowbility.org<mailto:srush@knowbility.org>>
Date: Tuesday, July 25, 2017 at 10:34 AM
To: Eric Egert <ee@w3.org<mailto:ee@w3.org>>
Cc: Shawn Henry <shawn@w3.org<mailto:shawn@w3.org>>, wai-eo-editors <wai-eo-editors@w3.org<mailto:wai-eo-editors@w3.org>>, James Green <jgreen@visa.com<mailto:jgreen@visa.com>>
Subject: Re: [style guide] Tone section

Great idea Eric, please do add that link, thanks!

On Tue, Jul 25, 2017 at 10:29 AM, Eric Eggert <ee@w3.org<mailto:ee@w3.org>> wrote:
On 25 Jul 2017, at 17:23, Sharron Rush wrote:

yes, fine with me for you to make that change

+1, maybe link to Understanding SC 3.1.5 as we’re striving for WCAG AAA where possible and there are some good techniques in there to make texts simpler.

https://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-supplements.html


(Of course it will be hard to always conform to this SC due to the technical nature of our content, but let’s include it as our North Star, so to speak…)

Eric


On Tue, Jul 25, 2017 at 10:21 AM, Shawn Henry <shawn@w3.org<mailto:shawn@w3.org>> wrote:

Thanks for the tersification, James & Sharron!

I'm not sure about "with a reading level on average of 10th grade."

Some issue around that, but I don't think it's high priority right now.
Are you OK if we leave that out for now (and leave "use plain language"),
and if folks feel strongly about it, we can revisit it later?

~Shawn


On 7/13/2017 12:28 PM, Sharron Rush wrote:

Updated Tone section and added the example in the Editorial section.

Thanks James!

On Thu, Jul 13, 2017 at 10:04 AM, Shawn Henry <shawn@w3.org<mailto:shawn@w3.org> <mailto:
shawn@w3.org<mailto:shawn@w3.org>>> wrote:

    On 7/2/2017 1:22 PM, Sharron Rush wrote:

        I removed this ''[@@ to do: tersify this paragraph]'' note from
the paragraph as I reviewed it, tried a few things, and finally decided to
leave as is.  Tone is a subtle thing to consider and all of the elements
referenced seem important to help us all arrive at an appropriate tone for
the variety of docs. OK with everyone?


    James in <https://www.w3.org/2002/09/wbs/35532/EO-Weekly-7-Jul-2017/

results#xq6 <https://www.w3.org/2002/09/wbs/35532/EO-Weekly-7-Jul-2017/

results#xq6>>:

    [I feel strongly about the following]

    I think the style guide needs to add strong preference for brevity
and use of bullets over paragraphs along with adding some visual content as
appropriate. This needs to be mentioned specifically in a new section so
editors are clear that their primary job is to try to cut half of the
sentences and half of the words while adding some visual content to create
visual anchors and break things up more. (Remember the 3 issues this
project is tackling are the out-of-date visual design, findability, and the
**wall-of-text effect**.) The style guide itself, much like many of our
resources, tends to try to explain things with many examples, leading to
long, wordy, complex, rambling, unnecessarily verbose sentences.

     >From the style guide: "From Technical Reports and Publications to
How-To guides for implementation to documents that help human beings make
sense of complex technical specifications, the tone of the presentations
may vary considerably. In general WAI documents will have a tone that is
welcoming, encouraging, and even inspiring around web accessibility.
Materials should educate people without patronizing or confusing them and
should be as plain spoken, jargon-free, and straight forward as possible."

    I applaud the obvious goal of comprehensiveness and clarity, but each
of those sentences has a set of 3 comma separated examples. The last
sentence has a second set of 3 things for a reader to parse. Less is more
when writing for the web.

    As an example of what I think the style guide needs to communicate
about the editing tasks ahead of us, I would rewrite the section to say
"Given the various types of documents, tone may vary; however in general,
WAI documents will have a tone that is welcoming, encouraging, and
inspiring. Materials should be straight-forward, and educate without
patronizing, using plain language with a reading level on average of 10th
grade." and even use that rewrite as an example of what we want people to
do.

    If we can pull maybe 5 sentences from existing resource and do that
to them and include that in the new section, it would help a lot.

    ###




--
Sharron Rush | Executive Director | Knowbility.org | @knowbility
/Equal access to technology for people with disabilities/




--
Sharron Rush | Executive Director | Knowbility.org | @knowbility
*Equal access to technology for people with disabilities*





--

Eric Eggert
Web Accessibility Specialist
Web Accessibility Initiative (WAI) at World Wide Web Consortium (W3C)




--
Sharron Rush | Executive Director | Knowbility.org | @knowbility
Equal access to technology for people with disabilities