Re: [style guide] Tone section

yes, fine with me for you to make that change

On Tue, Jul 25, 2017 at 10:21 AM, Shawn Henry <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>> 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*