You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@wookie.apache.org by Scott Wilson <sc...@gmail.com> on 2010/10/14 13:38:20 UTC
Reviewing the doc
Hi everyone,
I just had a look at what documentation we have and where to see what needs to be done for the release. Below are my notes - this is a broad overview, I haven't actually checked the details of any documentation files, just what we have and where we have it, and if it is obviously outdated or duplicated.
I would prefer not to just delete documentation which is not appropriate for the release (such as the old Widget Dev Guide doc in Word), but I'm not sure it really still belongs in trunk - should we put it somewhere else in SVN?
S
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.
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.
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.
/tutorials/firstWidget.odp : A tutorial for use with sample code. Needs testing.
/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.
/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.
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)
Wookie Server Administrators Guide: This has a lot of placeholders and needs more work.
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.
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.
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.
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.
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
Re: Reviewing the doc
Posted by Scott Wilson <sc...@gmail.com>.
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
Re: Reviewing the doc
Posted by Ross Gardler <rg...@apache.org>.
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