Style Guide for ilog entries LIGO-T000037-01-D David Shoemaker 22 March 00 ============================ First, some general notions: ---------------------------- An entry must serve two related functions: it must communicate to your audience, and the information must be accessible by someone using the available search tools. To communicate well, the entry (or group of entries) must have a lead-in sentence or phrase which orients the reader -- what is the subsystem or system under study, and what was the goal of the measurement. The data should be complete enough to recreate the experiment; a pointer to a previous set up is fine (if not better). The entry also should, if possible, draw a conclusion or indicate how the data are to be used. Ideas on interpretations and speculation are also very useful (but should be clearly indicated as such!). A series of entries in one series of experiments (on a given day) may be introduced in the first entry and conclusions left for the last entry to reduce the overhead and repitition, but each shift should be self-explanatory (perhaps by pointing to a previous shift introduction). Before making your first entries, read one month's worth of entries in the log -- it will give you a sense of what works, and especially what does NOT work (what is that graph about? what did they hope to achieve? what is that list of numbers for?). Try the search tool to see what kind of entries make it easy to find information. PLEASE re-read your entry the next day, and feel free to comment on it (using the facility in ilog to put the comment within the original entry); your insight is uniquely valuable. More specific points: --------------------- FIXED-WIDTH TYPE: if alignment of text is important (and it usually is), enclose the entry in 
  ...text... <\pre>    -- this will
make the text appear in normal Courier typeface, and so aligned
columns etc. will remain so. 

TABLES: Tables for repeated entries should be identical in layout, if
possible; this is best achieved using a template prepared in another
application (e.g, Word), and pasted (in text mode) into the ilog
window. The table title (don't forget one!) should be exactly
identical between occurrences to allow searches (and is best pasted in
with the template). Whevener possible, use cut-and-paste to get
quantities of numbers or long strings into the ilog to reduce the risk
of error (and frustration).

FIGURES (embedded objects in general): A caption, including the word
'figure', is important. Give axis labels, number of averages, tool
used if appropriate. pdf files are strongly preferred to other graphic
formats; ascii text is best for words. Exceptions are ok for special
cases. Try to orient the figure for easy viewing. If the figure is
very large (>200kb) please indicate in the text.

POINTERS TO DOCUMENTS: All pointers to documents outside of the ilog
should be to documents in the electronic DCC. This is to ensure that
documents are not moved, changed, etc. rendering the ilog pointer
useless. 

OPERATIONS vs. DETECTOR LOG: The Operations log is intended to carry
operator information, responsible persons, alarm conditions, changes
in state of the site, the site physical installation, vacuum system,
the data acquisition system. Changes in the detector installation
should go in the detector log, along with all measurements and
analysis.

ILOG vs. DCC: For some documentation, the DCC (Document Control
Center) is a more appropriate environment. In many cases, information
will be first logged in the ilog, and then collected and/or analyzed
and then assembled into a report which should have a DCC number and be
electronically available there. Examples are the development of
procedures, or measurements of resonances of suspended optics. In this
case the DCC number should be added to the original entry as a comment
to lead the reader to a definitive document. An ilog entry might just
indicate that the data have been incorporated in a new revision of an
existing document, and point the reader there. 

POST-DATED ENTRIES: It is best if associated information lies
together, and so if e.g., some spectra of measurements are made on the
day following the experiment, it is best to put them in the log on the
actual day of the experiment. An alternative, when there is evolution
in the interpretation, is to put a comment in referring to the later
analysis. 

KEYWORDS: An entry should carry one or more keywords (in the pull-down
menu) which describe the focus of the work. People will use the
keywords to narrow a search; try some searches yourself to see how the
concept can help if used judiciously. For all work including the
complete set of subsystems, please use '2km' (or '4km' as appropriate). 

ABBREVIATIONS AND ACRONYMS: Please use the standard TLAs (yes, Three
Letter Acronyms) for the subystems in any text (including 'IOO' for
the Input Optics Optics). The search tool is powerful, and so
reasonable abbreviations which leave out no consecutive letters are
fine; for example, a search for 'interf' will find interferometer,
interferometric, interferometers, but will NOT find 'ifo' (so this
latter should be avoided). A search for 'boot' finds 'boot', 'reboot',
'booted', 're-boot', etc.

MATH EXPRESIONS: Use any standard ascii characters that get the idea
across; no actual subscrips or superscripts are needed. 1.6e-19,
10^13, Hz/rHz, sqrt(f), etc.