yadis doc feedback

[Evan Martin]

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".