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
