I would like to see a first Introductory section to the spec (After notations and conventions) that explains at a high level the purpose of the spec and ways it can be used (use cases - although that could be a separate section. Your spec assumes that every already knows the deep technical details of atom and RSS, which is a bad assumption now that the spec if gaining notoriety and traction. As an example, I read numerous online pubs every day and never heard of this spec until yesterday. I have found only one article from SearchEngineLand on the subject from last July and then there was one yesterday that caught my attention - so a lot of folks are about to discover this standard as it starts to percolate out who previously had little focus on it (because Google has suggested they will now implement some form of it) Here are the elements I'd like to see:
Section 3: Overview of the Spec ---------------------------------------------- 1. What is the purpose of the protocol 2. What is the history of its emerging - in other words, someone went out and said "there is a need" - what was their motivation. Section 8.1 covers a tiny part of what I have in mind here - I would expand that section and put it here 2. Who needs it and why? Specifically identify if this spec is intended for me as compared to the general need (e.g. programmer, product manager, publisher) 3. How does it differ from the RSS and Atom protocols. 4. Is it "better" than RSS and Atom - e.g. is it an evolution of those protocols or does it go in a different direction? (I note that it builds on Atom, but does that mean it is an extension or just using it as a way to speed and simplify adoption) 5. Of the existing problem, what portion is this spec focused on solving right now vs what it could solve and what direction will it take toward solving the wider set in the future (again Section 8.1 applies here as well). Section 4: Use Cases -------------------------------- Search Engine Individual Blogger Real Time Web Service Provider (e.g. yourversion as an example) Enterprise Other? (I haven't a clue) I would be willing to write these sections as a way of finally forcing myself to learn all these specs (RSS, Atom, and pubsubhubbbub in detail), but I would ask that the leads be available to interview and for guidance when I have questions. If you wish to see examples of my writing go to my blog at http://www.aboutonlinematters.com
