Re: [style guide] Tone section

On 26 Jul 2017, at 2:44, 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 ;)

… And then write those 1000 words in the alt text of said picture ;-)

I think we should have pictures/graphics on our main resources first and 
then roll them out for other pages. We don’t have many participants 
with graphic skills in the group, but many who have strong opinions on 
graphics ;-)

We sure have to figure out what graphics we need so Alicia can start 
with drawing them.

>   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.

I really like that summary. Only one addition: I’d like to link to 
http://www.hemingwayapp.com – a free (as in free beer) tool that also 
checks for passive wording, complicated sentences and highlights issues. 
It also displays the reading level. I think this can be an important and 
powerful tool to check for issues.

Eric

> 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





--

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

Received on Wednesday, 26 July 2017 08:08:13 UTC