Re: editorial comments on authoring guidance

Hi, Fred–

Thanks for the comments.

On 5/25/16 10:36 AM, Fred Esch wrote:
> Doug,
>
> Editorial comments on the SVG Authoring Guide. These are all
> wordsmithing and don't change meaning.
>
> *Abstract*
> Do you want to use the word performant? It is used in a few W3C docs,
> but performant is generally not considered a word (outside of use as
> reference to a performance).

First hit on Google:
  https://en.wiktionary.org/wiki/performant

As a general approach in languaget, I prefer being descriptive vs. 
proscriptive, so even beyond the use of jargon (which we use all the 
time in tech), this word follows the rules of composition in English, 
and has a clear meaning, so it's a valid word even if it weren't common 
(which it is).

If we want to quibble, maybe I should also stop using the word 
"accessible" since the meaning we have for it, "providing an affordance 
for people with physical or mental disabilities" isn't an unqualified 
definition (and is commonly misunderstood by laypeople):

  http://www.merriam-webster.com/dictionary/accessible

:D

(Short answer: yes, I do want to use the word "performant".)


> *Introduction*
> You avoided using the term normative (actually non normative). Is this
> intentional so it is easier to read?

W3C Notes are never normative, they are inherently informative. I guess 
I could add that, but I'm not sure if that would just confuse people…


> The list of attributes all have the/able/ suffix. Can we rewrite it to
> avoid using the suffix? Something like
>
> /Specifically, this document demonstrates practical techniques for
> making SVG documents that you can:/
> /restyle/
> /animate/
> /resize/
> /navigate/
> /read with a screen readers/
> /use as a component in other SVG/
> /search and index with a search engine and other text-based applications/

Good note. I've done this.


> /use in different authoring and viewing applications/

I kept "round-trip", since that has specific meaning.


> The last paragraph I would suggest replacing
> /These are some techniques that are generally/ with /This guide uses
> techniques that are/
> and replace /Some techniques/ with /And some techniques /so the updated
> paragraph would read
>
> /This guide uses techniques that are applicable across different use
> cases, including document structure, document order, navigation, and
> text and text alternatives. And some techniques are unique to specific
> use cases, such as icons complex images, data visualizations, animated
> pictures, interactive applications, or text-heavy images, each have
> their own optimization./

I've updated this text.


> *Definitions*
> replaced element has stuff like image tags that are not showing up in
> the text

That was a copy-paste error, removed.


> *General Techniques*
> I assume this is placeholder text. It doesn't make sense the way it is.

It seemed clear to me, but I modified it; let me know if this works.


> *Structure*
> You need hierarchical headings under structure. Shape Composition,
> Grouping and Nesting

The document is structured, but the new style sheet doesn't seem to 
style different headings differently (e.g. <h3> and <h4> seem 
identical)… I don't know why, but I'm looking into it.

Regards–
Doug

Received on Wednesday, 25 May 2016 15:58:36 UTC