RE: Manifesto: Rules for standards-makers by Dave Winer

I resisted as long as I could 😊

 

Corollary to ‘Write specs in plain English’:  ‘Don’t write specs that only make sense to people who already understand the spec’

A spec attempts to precisely document something but it is also there to inform others so that they can use the spec and build things upon it. Most specs I’ve worked with emphasize comprehension over clarity, some even seem to take pride in the fact that only a small group of people have the context to really understand them.  I think there needs to be a good dose of both comprehensiveness and clarity. It drives me crazy when I have to read 20 pages of supporting material just to get through the first paragraph.

 

-S

 

From: George Lund <george.lund@digital.cabinet-office.gov.uk> 
Sent: Tuesday, December 15, 2020 2:16 AM
To: Heather Vescent <heathervescent@gmail.com>
Cc: W3C Credentials CG (Public List) <public-credentials@w3.org>
Subject: Re: Manifesto: Rules for standards-makers by Dave Winer

 

Hi all

 

Love this document, and there's little to fault at all. My only critique would be that "It totally doesn't matter what we call it" isn't really a corollary of "Perfection is a waste of time", for me.

 

I'd say that naming things is hard, and one mustn't try to be completely right first time. But the confusion that can persist when something is incorrectly named, and that name is allowed to live on despite actual practice, can be very damaging in the long run. You end up with a situation where something is "obvious" to those with long experience in a field, but commonly misunderstood by those working on the edge of it or engineers (experienced or not) coming new to a topic. A good format (for example) allows a new version to be rename things as needed, with old names marked as a deprecated aliases (or whatever is appropriate).

 

Clarity of language is even more important when communicating with people whose first language isn't English, not less so - the "symbols" thing is just wrong I think.

 

George

 

 

On Mon, 14 Dec 2020 at 22:57, Heather Vescent <heathervescent@gmail.com <mailto:heathervescent@gmail.com> > wrote:

Interesting piece by Dave Winer. What do you agree with? What do you disagree with? http://scripting.com/2017/05/09/rulesForStandardsmakers.html

 

-H

 

-- 

Heather Vescent <http://www.heathervescent.com/> 

Co-Chair,  <https://www.w3.org/community/credentials/> Credentials Community Group @W3C

President, The Purple Tornado, Inc <https://thepurpletornado.com/> 

Author, The Secret of Spies <https://amzn.to/2GfJpXH>  (Available Oct 2020)

Author, The Cyber Attack Survival Manual <https://www.amazon.com/Cyber-Attack-Survival-Manual-Apocalypse/dp/1681886545/>  (revised, Dec 2020)

Author, A Comprehensive Guide to Self Sovereign Identity <https://ssiscoop.com/> 

 

@heathervescent <https://twitter.com/heathervescent>  | Film Futures <https://vimeo.com/heathervescent>  | Medium <https://medium.com/@heathervescent/>  | LinkedIn <https://www.linkedin.com/in/heathervescent/>  | Future of Security Updates <https://app.convertkit.com/landing_pages/325779/> 




 

-- 

George Lund

Senior Developer for GOV.UK <http://GOV.UK>  Verify

Government Digital Service