W3C home > Mailing lists > Public > wai-eo-editors@w3.org > June 2017

Re: [style guide] Thoughts on approach

From: Eric Eggert <ee@w3.org>
Date: Fri, 30 Jun 2017 19:45:56 +0200
To: "Shawn Henry" <shawn@w3.org>
Cc: wai-eo-editors@w3.org
Message-ID: <6CF811F9-66A3-4D42-90C5-448FCE95DF3E@w3.org>
Probably best ignore my previous message, the discussion has moved on 
and into so many threads that I’m unable to follow it.

I reviewed an already updated document.

Sorry for the confusion.

Eric

On 30 Jun 2017, at 19:43, Eric Eggert wrote:

> On 30 Jun 2017, at 18:40, Shawn Henry wrote:
>
>> Thanks for getting this going, Sharron!
>>
>> I think that we want this Style Guide to be as short and 
>> easy-to-consume as feasible. If so, we'll want to be thoughtful about 
>> what we include and what not to clutter it with. For example, maybe 
>> we don't need to include obvious things, and certainly we don't want 
>> to recreate general writing best practices.
>
> I disagree. I should be able to find answers to most questions in a 
> style guide. Also “general writing best practices” might differ 
> from experience. We can fall back on the W3C Manual 
> (https://w3c.github.io/manual-of-style/#Editorial) and don’t need to 
> describe what is in there. It itself does not have a fallback style 
> guide (AP or something) besides being relatively bare-bones.
>
> (It is noted in the “URI, not URL” only, I think we could put it 
> more prominently.[^1])
>
> [^1]:  Side note: I think nobody knows what an URI is, but URL is a 
> quite common term, so I prefer the latter even if it is technically 
> inaccurate.
>
>> An example of a questionable item is: write out abbreviations on 
>> first reference. I'll start a separate thread on that point 
>> specifically...
>
> I think following [WCAG technique 
> G97](https://www.w3.org/TR/WCAG20-TECHS/G97.html) makes sense.
>
> Eric
>
>> Another point is that we want this Style Guide to be for all of the 
>> WAI website, and for Understanding WCAG at least. For some aspects, 
>> we might have different styles for different types of 
>> resources/documents/pages.
>>
>> Thanks,
>> ~Shawn
>>
>>
>> On 6/30/2017 10:14 AM, Sharron Rush wrote:
>>> I am thinking about how this will be presented and would like to 
>>> suggest this format.  Sarah and Shawn, if you agree I will format 
>>> the wiki to reflect these sections:
>>>
>>> *Introduction* – What the guide is meant to do, how it will make 
>>> our job easier, and how to use it.*
>>>
>>> Voice* – Can we make a statement about what we want the quality of 
>>> the voice to be? I am thinking about some of the adjectives we used 
>>> to describe how we wanted the web site to be.  Some words that will 
>>> suggest rhythm, and maybe a list of voice qualities to avoid. Each 
>>> statement could then be explained it in more detail and examples 
>>> provided for how to put it into practice*.
>>>
>>> Tone* – This seems a bit trickier and might entail how to use the 
>>> voice we agree on with different tones. There will be variation 
>>> depending on different scenarios, do you agree?  This may be a place 
>>> to reference our personas.
>>>
>>> *Style* – After introducing the guide and setting voice and tone, 
>>> that's when I think we get into the style guide items that Shawn and 
>>> Annabelle started and Sarah expanded on.
>>>
>>> *Specialist language* – Since this is a specialized filed, should 
>>> we include any guidance on how to reference disability, W3C process, 
>>> referencing materials or anything else that is super-specialized for 
>>> our environment?
>>>
>>> Throughout I strongly believe that we should use as many examples as 
>>> possible and be specific to our own stuff, as the first set of 
>>> guides has done. Is this an approach we can agree on? or have I 
>>> overlooked or misunderstood any of it? This is new to me so don't 
>>> hesitate to let me know.
>>>
>>> Thanks,
>>> Sharron
>>>
>>> -- 
>>> 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)





--

Eric Eggert
Web Accessibility Specialist
Web Accessibility Initiative (WAI) at World Wide Web Consortium (W3C)
Received on Friday, 30 June 2017 17:46:11 UTC

This archive was generated by hypermail 2.4.0 : Tuesday, 23 June 2020 20:41:51 UTC