Re: [style guide] Tone section

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

Received on Tuesday, 25 July 2017 15:22:02 UTC