[proposal] Tutorial docs as s5 presentations on website and as widgets

[Ross Gardler <rg...@apache.org>]

The eagle eyed amongst you will have noticed I've created an s5 widget 
template. This allows us to create widgets that are HTML presentations.

My plan was to change the existing ODP presentations in the tutorial 
directory into s5 widgets and deploy them along with a vanilla install. 
This would mean Wookie would carry basic documentation in all releases.

However, my concern about this approach is that it would duplicate 
documentation content across the wookie-site and the presentations widgets.

To resolve this problem I wondered if we could write our documentation 
in the form of s5 presentations, with copious speaker notes. We could 
then use the same source for the main website and the widget versions.

To demonstrate what I mean I have created an installation tutorial and 
moved it to the (in development) CMS site. I've set the default view as 
"outline" which means that a visitor sees the "outline" view, with 
speaker notes by default.

See http://wookie.staging.apache.org/wookie/docs/tutorial/installation.html

If you click on the little icon in the upper right you will see the 
presentation view which would be the default view in the widget and 
would also be useful when, well giving presentations.

We could use svn:external to pull the content from the website and into 
the tutorial widgets, this would allow them to be edited in either 
location in a checked out project.

There are a few issues at present with this, for example, at present 
there is no navigation added for the tutorial stuff. I'm sure this can 
either be resolved in the CMS templating or the CSS.

However, we are constrained in the way we write our docs. For example:

- we'd have to write this portion of the site in HTML not markdown 
(Actually there are some tools for converting markdown to slides, so 
this could be resolved).

- we have to write our tutorial docs in the "summary bullets" followed 
by "details" style.

What do people think? Do you see any problems with us writing the 
documentation in this way?

Ross