Re: [style guide] Thoughts on approach

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)