Wow guess I struck a nerve....a good nerve ;) I agree with everyones points, in fact when I was starting my journey into OpenSocial I had the same thoughts and same hopes. Unfortunately I was never really every to build great documentation. Fact of the matter is that as with any open source project, interest comes and goes. We all have day jobs and I assume most of us become involved in open source projects because they relate to our jobs and it is a mutually beneficial relationship. As peoples jobs change their commitment to the projects change and a vibrant community of contributors is needed to pick up the pieces. I myself had this happen recently, I no longer work on OpenSocial and Shindig in my day job anymore. I think the fact that we have outdated and missing documentation is because people have moved on to other projects and we haven't had the contributions from the community to pick up the pieces. I think this is just the flow any open source project goes through.
As far as trying to address the documentation needs across all OpenSocial related sites, I think that is too big of a task to tackle (again it comes down to active contributors). To be honest I am not sure how active the OpenSocial Foundation is these days. I know they were contributiong pieces of the spec to the W3C org, not the whole thing and not the gadget portion of the spec, but I have no seen any information about this communicated to the community. I would prefer to tackle one thing at a time, and the only thing this community controls is the Shindig documentation. @Chris, I hope you are still willing to help out even though I don't think we can address all of your concerns. I think Matt's idea about having a getting started guide is also a great idea. However I would like to keep both the implementation guide and the getting started guide on the website instead of the wiki. Here is what I propose. 1. We use the Shindig site as the place to keep the documentation. It is CMS based [1] so no need to know how to write HTML. 2. We create a getting started guide, containing the minimal set of steps to get someone up and running. 3. We create a detailed implementation guide that addresses how someone would extend Shindig to build their own implementation. 4. In the process of doing this we cleanup/consolidate the Shindig site and the wiki. What does everyone think? [1] http://www.apache.org/dev/cms.html On Tue, Sep 16, 2014 at 9:29 AM, Raj Janorkar <raj.janor...@gmail.com> wrote: > Hi All, > > When i started 1 month back i was totally fucked up, still i am fucked up > because of lack of documentation. (sorry for bad words). > > Still trying to understand few things, for those no documentation. I am > doing my own research for everything. > > I am really thankful to Ryan who helped me lot. > > its really good idea to have good documentation. > > Regards, > Raj > > > > On Tue, Sep 16, 2014 at 10:08 PM, Ryan Baxter <rbaxte...@apache.org> wrote: > >> I think it has become clear that we should really be providing an >> implementation guide for those who want to consume Shindig. Those of >> us that have gone through the pain of implementing Shindig know that >> there are a lot of gotchas along the way, and it is not entirely >> obvious which pieces of Shindig are production ready by default and >> which pieces should be replaced with your own implementations. It >> would also be good to enumerate which configuration options need to be >> changed in order to properly secure Shindig (locked domains). What >> does everyone think? This will need to be a true community wide >> effort as I am sure everyone has their own tips and tricks. >> Appreciate any feedback, as well volunteers to help. >> >> -Ryan >>
