yadis doc feedback

[Ernst Johannes]

Thanks for the feedback. It would be great if you could put it into  
the "discussion" pages on yadis.org -- that way, everybody can see  
all the comments in context, and agree or disagree with them in context.

It might be most productive if you suggested specific language to  
replace the various items you disagree with.

I think I agree with most of your comments, by the way. This is all  
definitely work in progress -- e.g. the doc was started before we  
realized that we built something more general than integrating OpenID  
and LID ...


On Oct 29, 2005, at 10:18, Evan Martin wrote:

> David gave me a copy of this doc weeks ago but I didn't get a chance
> to send my feedback before it was too late.  Sorry!
> These comments are all negative because I'm interested in helping the
> spec improve.  In general, I think it's great that you're looking to
> cooperate.
>
> Meta-comments:
> - Agree with the rest of the list that the positioning is confusing.
> Everything is described in terms of LID / OpenID rather than the
> general discovery protocol that it is.  I'd rather that everything
> regarding one of {OpenID,LID} be in its own section.  You're also
> running into the N+1 problem with names of things -- people have
> enough trouble understanding OpenID/LID and now we have a new name?
> How do you expect Joe Random user to understand all this, given the
> confusion we've already seen with OpenID?  That's a pretty fundamental
> problem though and I can't think of any solutions.
>
> - How sure are you that this is gonna work with (insert identity
> system of the month here)?  I'd like some assurances this can extend
> beyond the two cooperating groups.
>
> - There's a lot of extraneous text in sections 1-3 that only serves to
> hide what's going on.  For example, in section three, "We have found
> it is easiest to understand an architecture if it explicitly lists its
> assumptions; so here you are." doesn't provide any information.  Much
> of section 3 sounds like marketspeak (which is why I imagine people
> thought 6A was responsible): "We firmly believe that innovation is a
> good thing" is an empty phrase -- who would openly state their
> opposition to innovation?  The shorter the better when trying to
> convey information.
>
> - While some people thought this was a 6A document, it was clear to me
> it was written by the LID fellow because there's a definite bias in
> the presentation.  The first paragraph says, summarized:
> "LID was invented first, and is decentralized, URL-based personal
> digital identities.  Then OpenID came along which is for some blog
> stuff."  Why not begin with something more plain like "There are many
> incompatible blah blah blah."?
>
> Specific comments:
> - The motivation for URLs as identifiers is weak.  (I'm not opposed to
> it, I'd just like to see it better motivated.)  The second paragraph
> in section 3.3 indicates (paraphrased) "search engines find blog/home
> pages therefore URLs are good identities".  Is that really the
> fundamental reason?  Many people don't have URLs (see videntity.org,
> etc.), and maybe that deserves a comment.
>
> Protocol comments:
> 5.1.  (Discovery is documented as GET MYID?meta=identity.)
>  - Should other URL params be allowed?  What if MYID already contains
> a question mark?
>  - Especially if MYID is allowed to contain a question mark, isn't
> "meta" a pretty generic CGI param, that could describe many things
> other than identity metadata?  Why not pseudo-namespace this with a
> name like yadis.meta?
>
> 5.1.1.  (Links in HTML head.)
> HTML documents can be more than text/html; need to document that you
> allow all the XHTML flavors.  The example HTML snippet should indicate
> that the XHTML trailing slash in the tag is ok.  (This is especially
> when people write regexp-based parsers after reading the spec.)
>
> 5.3.  (Profile data exchange.)
> - Seems like spec bloat.  Do you really expect everyone who implements
> YADIS to implement the LID profile exchange mechanism?  For example,
> you're pulling in a hard XPath dependency in a spec that up until now
> was defined in terms of text-based formats.
> - There's also a bit which describes how to append CGI arguments that
> gets a bit convoluted ("if BobURL already contains a question mark,
> ... ampersand instead of question mark") that might be worth
> documenting up front and reusing here.
>
> 6.1 (x-meta-identity format)
> - Vital that you document the allowed encodings of text -- can I put
> UTF-16 here?  (People really do have URLs that contain non-ASCII; it's
> especially common in Asia.)  How about IDN (domain names)?  I think
> it'd be fine to simply require UTF-8.
>
> - End of line character needs to be documented -- \r\n, whatever.
>
> - Must capability names be URLs or can they be URNs?  (I hate this
> stuff but it's good to get it right to begin with.)
>
> - That "all versions of the capability that are supported must be
> listed individually" scares me a bit, though I can see why you did it.
>  I wonder if you could soften this at all.
>
> Editorial comments:
> - 4.1 is missing a period at the end.
> - 5.1 has a typo "thye".
>

Johannes Ernst
-------------- next part --------------
A non-text attachment was scrubbed...
Name: lid.gif
Type: image/gif
Size: 973 bytes
Desc: not available
Url : http://lists.danga.com/pipermail/yadis/attachments/20051029/aef95579/lid.gif
-------------- next part --------------
  http://netmesh.info/jernst