On 15 Oct 2010, at 21:25, Ross Gardler wrote: > On 14/10/2010 13:38, Scott Wilson wrote: >> I just had a look at what documentation we have and where to see what >> needs to be done for the release. > > Really useful. Thanks for this. Some comments inline. I'm afraid I have no > cycles to help do any of this at this point, so feel free to ignore my > suggestions and take a different path. >> >> Documentation in SVN >> ================== >> >> readme_coppercore.txt : This is kind of useful for a few people but is >> pretty obscure stuff. I suggest moving this to the CopperCore project >> instead. It should not be included in the release. > > +1
I've put it in docs/legacy for now > >> readme_tomcat.txt : This is no longer consistent with the "Downloading >> and Installing Wookie" wiki page and hasn't been updated in a long >> while. I suggest deleting this. > > Alternatively we could put a step in the release process to pull the most > recent content from the wiki and update this readme. Personally I prefer > install instructions to be included in the binary release rather than require > a visit to a web site. This is because I often experiment with new software > on trains/planes and other places with little or no Internet. > > If we do this we probably want to rename the file install_tomcat.txt > >> readme.txt : This has similar content to the "Downloading and Installing >> Wookie" wiki page but is not identical. I suggest we merge the content >> of this into the wiki and write a new README.txt specifically for the >> release. > > Same comment as above, i.e. make it part of the release process to update > this document from the wiki just prior to the release build. > > I agree with merging any useful content from here into the wiki page > regardless of whether we do the above. > > [we can probably automate this extraction of content from the wiki in the > release build targets in Ant] For now I've merged the contents of the readme.txt with the wiki page and then updated readme.txt. As the readme contains the tomcat instructions anyway I've deleted readme_tomcat. >> /tutorials/firstWidget.odp : A tutorial for use with sample code. Needs >> testing. > > +1 > > we probably want to make this available in the release as a PDF too, many > windows users have no idea what .odp is. Even better would be to turn this > into an HTML slideset. But lets not delay this release for such an objective. TODO >> /docs : Both .doc files in here are really old - we might repurpose some >> of the content for future documentation but they should not be in a >> release as they will really confuse users. > > I assume these are the docs you suggest moving "somewhere else" in your > preamble. +1 for doing so. Perhaps "legacy/docs" I've put them in docs/legacy and added a README explaining why they are there >> /connector/README.txt : Very brief, just a description of what the >> connector framework is, and a link to the Embedding Wookie Widgets wiki >> page. >> /connector/ruby/README.txt : Very brief installation information. Needs >> a link to the Embedding Wookie Widgets wiki page. >> /connector/php/README.txt : Very brief installation information. Needs a >> link to the Embedding Wookie Widgets wiki page. >> /connector/flash_flex/README.txt : Just a sentence on what it is. Needs >> a link to the Embedding Wookie Widgets wiki page. > > Here I think it is OK to link out to the wiki. Building a new connector is > pretty advanced stuff. we don't want to make the release process have too > many steps. Done - all connectors now have a consistent README.txt > > >> Documentation online >> ================= >> >> * Downloading and Installing Wookie: All sections look complete; >> needs testing. (The section on "Running Wookie with a security >> manager" is likely to be out of date since we stopped using Hibernate) > > +1 TODO >> * Wookie Server Administrators Guide: This has a lot of placeholders >> and needs more work. > > lets do as much as we can during the release cycle, but having gaps is OK - > just make sure we warn readers that the doc is in development and we welcome > questions via the dev list. I've put a note on this one. > >> * Embedding Wookie Widgets: There are a few sections here that are >> missing, but the main material on the connector framework looks >> OK. Needs testing. >> * Building Widgets : All sections look complete; needs testing. > > +1 TODO > >> * Using Wookie's W3C Widget Parser in other Applications : The >> stylesheet has made the code samples unreadable; content also >> needs testing as I suspect not all parameters are documented. > > As above re incomplete docs. > > Need to fix the stylesheet. I suggest we take the stylesheet used by the > Comdev project (http://community.apache.org) as this is itself a copy of the > sheet from the main apache site and thus pretty complete. We should modify it > sufficiently to give Wookie an identify - but that would probably just need > some colour and logo changes. TODO >> * Integrating Wookie with Shindig : Looks pretty complete. Needs >> testing. >> * FAQ : This looks to be in good shape. >> * Wookie REST API : Needs testing - some of this may no longer be >> 100% up to date. > > +1 TODO >> Documentation Missing from Wiki? >> =========================== >> >> The Bondi Camera feature doesn't have any documentation or a link to any >> documentation. It may also benefit from having a README.txt in SVN. > > +1 (suggest putting the content in the wiki then extracting to a readme as > above - we really should automate the readme extraction) Good plan. TODO >> Documentation Missing from SVN? >> =========================== >> >> I noticed that while the other connectors have readme files, these >> don't. May be worth adding for completeness, even if its just "This is a >> Wookie connector written in {python|java}. For more information see >> {Embedding Wookie Widgets URL}" >> >> /connector/python >> /connector/java >> /connector/CSharp > > +1 Done - see above. -S
smime.p7s
Description: S/MIME cryptographic signature
