Re: [style guide] Tone section

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.

###

Received on Thursday, 13 July 2017 15:05:24 UTC