Re: [style guide] Tone section

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> 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>:
>
> [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*