EVO Workbook Options July 28 2011

Current Status

The workbook content lives in CVS and anyone can update those pages.  Admittedly, all content is in HTML and those desiring to edit can do so via any simple editor or may prefer using something like Dreamweaver.  Those who wish to suggest changes without actually doing the editing can contact Jim, Joanne, and Heather.  To actually post the updates to the web, requires updating the copy of the workbook located on the V: drive.  

The content in CVS is used by Berrie to create a mirror of the workbook.  As Tony notes the use of pure HTML was chosen due to:

a) Chuck's preferred way of working
b) Makes it easy to create download-able workbook
c) Makes it easy to mirror site with no particular requirements on remote site

Richard has noted that having an exportable workbook is helpful when SLAC is down..similar comments could be made about the mirror.

Some options for improvement:

move the web server to a unix environment to avoid the need to log onto a windows box to make content "go live"

Find a way to avoid working directly in pure HTML to make updates easier.

Some Options

Going Confluence

Rob has suggested migrating the workbook over to Confluence to allow a larger group (with adequant oversight) to maintain the documentation.  

We would not be able to maintain some of Chuck's nice navigation features, such as keeping the workbook header at the top of the screen while scrolling.  The nearest equivalent in Confluence would be the creation of an expandable  tree which persists on the left side of the page.  A strong editorial board would prevent entropy.  We would also need to carefully consider the top level structure.  Could perform some analysis of chucks' links to see what nodes map to top level trunks of a tree in Confluence.

Concerns:

Making sure that the workbook stays organized and written clearly.

Django

Jim had some ideas aobut DB driven tools like django:

Since these are static pages and since the formatting is entirely boilerplate (especially for the tool parameter pages, which I have edited most commonly), it should be possible to have the content saved separately in plain text files (or some db) and have the static pages generated by populating a web page template with the desired content.  The Django framework does this to generate web pages dynamically, and it can also produce static pages.   I'd be in favor of starting out generating at least some of the static pages this way, such as the tool parameter pages.  It would be a big job to convert all of the workbook to this framework, but it could be a start of moving towards 21st century web technology.

This could also help start cleaning up our cvs repository for the workbook, since the contents would be the files with the text entries and a small set of templates, instead of having the same html replicated slightly differently for each page.

sitemesh

Tony had some comments concerning sitemesh:  
The general idea of making the workbook more maintainable (with less effort) seems like a good idea.  Certainly the same could be achieved using sitemesh which we already use for all the Java pages and the decorator.