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.


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