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
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]
/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.
/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"
/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.
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
* 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.
* 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
* 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.
* 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
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)
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
Ross
