Re: [style guide] Tone section

Thanks, James!

I added a new whole section that includes Readability:
 https://www.w3.org/WAI/EO/wiki/Style#Simple.2C_Plain_language

We need to be thoughtful about listing specific tools. Please give me a little time to figure out issues and suggest solution.

Thanks,
~Shawn



On 7/25/2017 7:44 PM, Green, James wrote:
> 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 <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/ <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/ <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/

Received on Wednesday, 26 July 2017 16:22:30 UTC