W3C home > Mailing lists > Public > site-comments@w3.org > January 2012

Re: Text poorly written

From: Ian Jacobs <ij@w3.org>
Date: Wed, 4 Jan 2012 16:17:00 -0600
Cc: site-comments@w3.org
Message-Id: <DBF268EE-8B13-4DA9-AF66-6683A2254FAD@w3.org>
To: Michael J McCarthy <mm6@andrew.cmu.edu>

On 4 Jan 2012, at 1:05 PM, Michael J McCarthy wrote:

> Hello Ian,
> 
>   I have provided below the current and proposed paragraph. If you
> would like for me to submit more I would be happy to do so.
> 
> Mike
> 
> 
> 
> Current
> ======
> Service Description is an important part of accessing a service. Most service description languages are targeted at machine consumption, allowing the automatic creation of code skeletons, search and classification of services, but it can be consumed by human, to clarify the use of some parameters or the semantic of operations performed.
> 
> Suggested Edit
> ===========
> A Service Description is an important part of accessing a service. Most service description languages are targeted at machine consumption, allowing the automatic creation of code skeletons, search and classification of services, but it can be consumed by humans, to clarify the use of parameters or to specify the precise semantics of operations.
> 

I've taken a more serious pass:

A Service Description plays an important role in enabling access to a service. Most service description languages are designed for machine consumption, allowing the automatic creation of code skeletons, search, and classification of services. However, people may also find descriptions useful to learn about the use of parameters or the precise semantics of some operation.

How's that?

Ian


> 
> 
> 
> 
> On Wed, 4 Jan 2012, Ian Jacobs wrote:
> 
>> 
>> On 4 Jan 2012, at 12:10 PM, Michael J McCarthy wrote:
>> 
>>> 
>>> Dear W3C,
>>> 
>>>   I am a fan of W3C and was just wondering why we have such
>>> a poorly written web site.
>>> 
>>> 
>>>   For example, under Service Descriptions, we have:
>>> 
>>> Service Description is an important part of accessing a service. Most service description languages are targeted at machine consumption, allowing the automatic creation of code skeletons, search and classification of services, but it can be consumed by human, to clarify the use of some parameters or the semantic of operations performed.
>>> 
>>>  I think that paragraph is almost impossible to read. There are
>>> many paragraphs just like the above.
>>> 
>>>  Do you need a volunteer to write these descriptions in a more
>>> clear and consise way? If so, let me know.
>> 
>> Hi Michael,
>> 
>> I believe this is the URI you are referring to:
>> http://www.w3.org/standards/webofservices/description
>> 
>> I welcome your suggested edits!
>> 
>> Ian
>> 
>>> 
>>> Mike McCarthy
>>> Associate Teaching Professor of Information Systems
>>> Heinz College
>>> 
>>> Carnegie Mellon
>>> 
>>> 
>>> 
>>> 
>> 
>> --
>> Ian Jacobs (ij@w3.org)    http://www.w3.org/People/Jacobs/
>> Tel:                                      +1 718 260 9447
>> 
>> 
>> 
> 

--
Ian Jacobs (ij@w3.org)    http://www.w3.org/People/Jacobs/
Tel:                                      +1 718 260 9447
Received on Wednesday, 4 January 2012 22:17:21 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Wednesday, 24 October 2012 16:21:34 GMT