LIGO Documentation Blue Pages Teaching Documents Technical Documentation Glossary

LIGO Documentation

There is a need for a wide variety of different kinds of documentation for the LIGO e-Lab(s). We cannot hope to create all this ourselves, so we also need a dynamic way to allow for new documents and revision of existing documents from the "right" people, while avoiding bottlenecks or abuse.

There is likely a lot of overlap in the items below, since we have not yet sorted out the best way to do things. Some overlap is fine, as are cross-links. The descriptions below are incomplete at best...

THIS PAGE IS OUT OF DATE

Blue Pages

To prepare for the teacher's workshop at Hanford last August Dale wrote a number of pages of on-line documentation, and also incorporated material from John Kerr, a teacher who worked at Hanford over the summer. Dale chose a blue background and style for these pages, so we have been calling these the "blue pages". You can find them at http://i2u2.spy-hill.net/ligo/

These were all originally prepared using FrontPage. Eric took them apart and put the main body text into separate .htm files, then wrote PHP functions to provide the common "decorations" and navigation menus. That made it possible for Dale to work on editing the contents, while Eric could change the format and navigation functions of all pages just by editing a small set of server-side functions.

The pull-down menus use only CSS :hover. But since :hover is not supported in Internet Explorer 6 (IE6) a separate JavaScript file called csshover.htc provides that functionality. It is only loaded for IE6. Happily, IE7 supports the :hover tag. If you use IE6 with JavaScript disabled the main links still work, just not the pull-downs (verify?), and additionally Dale has been taking care to make sure that there is a primary path of links through the pages which do not rely on the pull-down menus.

Dale's original implementation of the pull-down menus mixed formatting and functionality, which were intermixed in a complicated way. Eric separated the two into purely the pull-down menu functonality, in hovermenu.css, and the document styling, in ligo-doc.css. So we could now use the pull-down functionality in other places, but with separate styles.

Eric has been thinking of a way to allow for editing these kinds of pages with any of a number of tools, or taking in new documents, but keeping the "kernel" of the document to just simple HTML. For right now, however, you log in to a Unix machine either at LHO or Spy Hill and edit the .htm file containg the "kernel" of the document.

Teaching Documents

Dale is working on them now. I'll let him fill this in. Some of the documents from the Blue Pages are being re-cast into the proper form for e-Lab teaching materials on some server somewhere (www13?), and some new documents need to be written. I don't know all the details.

But not all of the Blue Pages fit this description....

Technical Documentation

...such as the Tutorial on how to use the Analysis Tool, overview documentation about LIGO in general and the Hanford Observatory in particular, and likely other things. Since LIGO DAQ is highly technical and we are making data available from a wide range of sensors we will likely want to develop more documentation for anybody working on an investigation.

Glossary

The "glossary" is a wiki which uses the MediaWiki software, the same software used by Wikipedia. This does not mean that it's open for editing by every sap on the Internet. I've investigated how one can control read/write/edit access to the wiki, and I find that it's very easy to manage and very flexible to configure. We can basically implement whatever access policy we see fit, based on a roles-based permission group system. I like it.

I chose MediaWiki in part since I'd already tried Twiki and wanted to see how different something else would be. The main ideas are the same, but there are notable differences in the wiki markup used by the two. (I'm now also using Trac, which includes a wiki, and it is similar to MediaWiki but also has noticible differences from both MediaWiki and Twiki).

I also chose MediaWiki because it's used to run the Wikipedia. This means lots of people may already be familiar with how to use it, there is already lots of helpful documentation (too much, perhaps), and anybody who learns how to use it can then go over to Wikipedia and make a positive (one hopes) contribution. (Positive transfer of knowledge)

I have been adding LIGO technical documentation to this wiki as I go along. I use categories to label things that apply strictly to LIGO, so that it could also be easily used for other e-Labs.

I have created an authentication plug-in for MediaWiki which allows automatic authentication to a wiki based on prior authentication to a co-located BOINC project. That means that if you have logged in to the logbook/discussion site then you can go to the wiki (which is a different software system) and you are already logged in. There is no need for separate accounts or passwords. In other words, you get "single-sign-on" between the two. Details and a link to the code are at http://pirates.spy-hill.net/glossary/index.php?title=BOINC_Authentication . That wiki is itself a demonstration of the authentication plug-in, since it is tied to the BOINC test project Pirates@Home.

I should also note that MediaWiki also has authentication plug-ins for use of SSL certificates, and Shibbolith. Shibbolith is an Internet2 project to provide single-sign-on capability for a collection of software systems, so we might want to look into it further.

I don't know if "glossary" is the right word for this wiki, since it contains more than just definitions of words. The idea is that it would be a dynamic growing repository about information of relevance to the e-Labs, including technical documentation. But I can't think of a better name for it right now. Anybody?

-- Main.EricMyers - 22 May 2007