I like your idea of identifying the audience and their needs clearly. Do the readers have any "why" questions? The "what" question is answered.
K On Thu, Aug 13, 2009 at 3:31 PM, Kevin Brown<[email protected]> wrote: > That's a lot of words. How about: > > "Apache Shindig is a reference implementation of the [link] OpenSocial > specification". > > I imagine that there are two groups who will ever read that overview: > > 1. People who have no idea what Shindig is. This one liner explains that it > is a reference implementation of the linked specification. > > 2. People who already know what Shindig is and want to know details. For > those people, you can't explain everything in an overview and you need a > complete explanation anyway. > > Explaining that shindig "renders gadget XML" is meaningless to the first > group, and woefully inadequate for the second. > > On Thu, Aug 13, 2009 at 3:10 PM, K Wong <[email protected]> wrote: > >> I'm no expert on Shindig, but I'd approach this by stating what it is >> very directly (What is it? Why is it useful and worthwhile?). Other >> projects like Apache state the project goals first then what the >> project is producing. From a user perspective (ie. a social network >> web site operator), I think that I'd want to know what it is before I >> learn who is making it and what they want to achieve. Example follows. >> >> --- >> >> Apache Shindig is server-side software that allows social networks to >> add functionality using OpenSocial gadgets. Shindig renders gadget XML >> files into html and javascript and provides an implementation of the >> OpenSocial API. Shindig provides reference implementations of >> OpenSocial containers in both PHP and Java. >> >> The Apache Shindig project eases the adoption of the OpenSocial API as >> a way to improve the portability of social applications among social >> networks. >> >> >> >> >> On Thu, Aug 13, 2009 at 2:09 PM, Kevin Brown<[email protected]> wrote: >> > Wow, that is pretty bad. I am by no means a literary master, but I might >> > take a crack at it if I get some free time. Something simple would be >> good. >> > >> > On Thu, Aug 13, 2009 at 1:56 PM, Chris Chabot <[email protected]> >> wrote: >> > >> >> Someone pointed out this typo to me: >> >> >> >> From: http://incubator.apache.org/shindig/overview.html >> >> <http://incubator.apache.org/shindig/overview.html>*Apache Shindig, a >> word >> >> meaning party, was originally started by Google in 2007 as a reference >> >> container for hosting OpenSocial compatible widgets in any website. >> >> Originally a port of Google's iGoogle gadget container, with Brain >> >> McCallister's PHP code, Apache Shindig through off it's egg shell, and >> >> showed that Google was serious about making OpenSocial accessible to a >> >> larger number of sites. Since December 2007, Apache Shindig is now an >> >> Apache >> >> project. >> >> * >> >> The "through of it's egg shell" should probably be "threw of its egg >> shell" >> >> >> >> While this comment is completely correct, looking at our overview page I >> >> really think we can do a better job altogether. The references to Google >> >> are >> >> not very Apache, and brian's PHP code hasn't been a part of the project >> for >> >> a a very very long time either. All in all this intro doesn't tell the >> >> reader very much about what Apache Shindig (-incubating) is about. >> >> >> >> Is anyone feeling creative and willing to try to write a better intro >> for >> >> us? >> >> >> >> -- Chris >> >> >> > >> >
