We would like to encourage all users of the SCRC analysis software to
share with others the techniques they've developed for performing specific
analyses. The best way to do this is to write a tutorial, in the format
we've developed here, so that even a novice can pick up on the techniques
you use and go from there to apply these to their own data analysis.
This guide should help you in this task, by explaining the approach
we used here to write our tutorials, and giving you some recommendations
to follow for making your tutorial consistent with the others on this site.
You may even want to keep this guide open in your web browser as you
write your tutorial, so you can refer to it often and make use of the
links provided below.
The first few decisions you'll face will be what to write about, and
what software you'll use to write it. You'll also have to decide at what
level you should be writing, or what your target audience is. Below are
several general pointers to help you with these choices.
Write about what you know... or need to know.
The best tutorials are the ones that solve concrete problems. If you've
just solved a problem, just worked out a technique for analyzing something
that wasn't immediately obvious, it may be worth sharing your newfound
knowledge with others. Even for problems you're still in the process
of solving, it would be useful in any case to document your steps as
you go along, so you may want to consider taking the extra step of
writing it up for others to use as well.
Don't reinvent the wheel.
Take a little while to familiarize yourself with the
tutorials already on our site so you don't
end up writing something that's already covered in another tutorial.
Also please let us know before you begin writing one, so we can assign
a tutorial number to your work, and so we know which tutorials are in
the works.
Assume some prior knowledge, but not much.
The tutorials can build on techniques and terminology covered in earlier
tutorials, but don't assume the reader
is very comfortable with the analysis program and some of the techniques
you may routinely use. These tutorials should be written at a beginner level.
Ideally, a complete novice should be able to go through the tutorials
in sequence without getting bogged down in a level of detail not explained
previously. When you refer to a technique covered in an earlier tutorial,
include references in your work. E.g. "Set the cycles as described in
sections 3.1 and 3.2 of Tutorial 3" or "Delete the frames using
the frmsel program as described in Tutorial 9, section 9.5."
Also introduce and explain any scientific jargon you use in your tutorial,
as the reader may be unfamiliar not only with the software, but also with
techniques or terms you commonly use.
Use the tools you're comfortable with.
Here at the SCRC, we use WordPerfect quite extensively because it it
readily available, easy to use, and attractively priced for the academic
version. It also has built-in PDF export capability, so we don't need
additional software to make the PDFs for publishing our tutorials to the web.
This is the tool we recommend using.
However, if you'd rather use Word, or some other word processor,
that's entirely up to you. We don't want to discourage you from writing
a tutorial by imposing unfamiliar software on you. We do ask, however,
that you make your document available as either a Word or WordPerfect
document, as well as a PDF, so that others can easily edit or add to
the document later without requiring the installation of some special
software.
You don't need to be a web expert to write one of these. If you're
familiar with web editing tools, and would rather write up your work as
an HTML document, we can deal with that too. Most likely, though, you'll
want to use some sort of word processing software and leave the rest to
us. That's fine too. We will make the HTML cover page that we have for
each tutorial, linking to the document and data you contribute. If you're
not able to make your own PDF version of your document, we'll do that too
provided your document is in a standard format we can read.
Rather than just documenting a general technique, your tutorial should
walk the readers through an example they can try themselves, and compare
their results to yours. For this reason, you should make the data files
available with the tutorial. Ideally, you should build your tutorial
around our standard
sample run data files,
especially the c08-01 run. Please browse through these files and try your
analysis on them to see if they will do the trick. However, if none of these
are suitable for the technique you wish to demonstrate, please provide a
reasonably sized sample data set to add to our archives for this purpose.
Similarly, if your technique involves the use of shell scripts,
please submit these to us as well so we can add them to our
shell script archive
for others to use. Even if you can't find the time to write a tutorial
right away, or ever, if you have a shell script that you feel may be
useful to others, please send us a copy. Make sure you include some
comments in your script that describe what it does and how it is used.
In either case, include with your submission a list of the data
files and shell scripts used by your tutorial, so that we can add links
to these on the cover page we'll make for the tutorial.
You should walk the reader through the analysis, step by step, explaining
each step as you go along. Each step should include the actual commands and/or
keystrokes used to accomplish that particular task, so that the reader can
follow and try it out without a lot of searching around trying to figure out
how to set a particular parameter. As much as possible, you should refer to
parameters and
analysis methods
by the same names as they are given in the analysis program, to avoid confusion
and ambiguities. Follow these two links to get at the lists of names for each.
You can also use these lists to check your keystroke sequences.
Make the keystroke sequences stand out.
You should show the keystrokes and commands in a bold font, so they stand
out from the rest of the text. It would also help to use colour to highlight
them, but use a dark colour so the text will print legibly on a black and white
printer. For analysis menu selections, you should show the keystrokes as
capital letters, or as capitalized words separated by slashes.
E.g. <Esc>SCIDorSet/Cycles/In-phase/Delay.
Show single keystrokes that must be represented by a multi-letter word or code
within angle brackets, e.g. <Esc>
for the Esc or Escape key, and <CR>
for Return or Enter key (CR is carriage return).
Italicizing these also makes them stand out from the rest of the keystrokes.
Use the same approach for so-called "modifier" keys (Shift, Ctrl, Alt),
e.g. "Use <Ctrl>C
to cancel." Try to be consistent in this to avoid confusion.
Explain the reasons for each step.
While it's important to walk through all the steps, the goal should be for
the reader to understands the purpose of these steps. When you recommend
setting a parameter a certain way, explain why such a value should be used,
and how that parameter will affect the final results. It may be helpful
to demonstrate the effect of different values for a given parameter.
It's one thing to explain what an analysis will do, but a few
well chosen figures will likely communicate the message much more
quickly and effectively. Fortunately, making these figures can be
very easy. A few screen-shots may be all that's needed, or perhaps
a final plot file from the analysis, rendered as an image in your
document.
End off with a final figure,
which shows the intended end result of the tutorial. This will serve as the
figure on the cover page, as well as the thumbnail on the tutorial index page,
so that you can tell at a glance from the tutorial index which one will
yield the graph you want, or something close to it.
As well, you should include any screen shots of intermediate
results which you feel are relevant, as well as samples of
any visual parameter setting steps you describe.
There are a number of different screen grabbing techniques you can use
to get screen shots to illustrate your tutorial.
Your choice may well depend on which system you use to display the analysis
while running it. If you're familiar with Windows-based tools, and run
an X Window display program on Windows, you may want to use Windows-specific
solutions to getting and manipulating your screen shots. Otherwise, there
are some UNIX-based tools you can use.
If you're running a
remote X11 session under
Microsoft Windows, you can use Windows-based screen grabbing tools:
Corel Capture (part of Corel Draw) lets you select a
portion of the screen that you want to capture, or you can use the
<PrtScr>
(print screen) key to copy the whole screen image to the Windows clipboard,
for pasting into a window in Adobe Photoshop or Corel PhotoPaint.
You can also use
<Alt><PrtScr>
to copy only the active window, including its border.
If using the PrtScr key, pay close attention to what gets pasted into
your photo editing application. I noticed some wierdness with the PrtScr
key after doing more than two of them, and pasting into Adobe Photoshop
LE. I found the paste operation was giving me the 2nd screen shot over
and over, rather than the 3rd, 4th, etc. If I quit the application and
started over, it worked again for 2 more shots. It seems to be a bug in
Photoshop LE, as Corel PhotoPaint doesn't seem to have that problem.
If you're not using Windows for the analysis, but are working right
on a Linux or other UNIX system, there are tools you can use on any
platform that supports the X Window system.
The sdump
program that's included with the analysis software does provide limited
capabilities for getting screen shots saved as files, but these images
are black and white only, so you may find them lacking for illustrations.
However, you can use this if black & white images are acceptable.
First, you need to set
sdump's options
to save files, e.g.
"sdumpopt -save sd0001",
and then you can use
<Ctrl>B or
Plot/Video
from analysis, frmsel, etc.,
to get your screen-dump files as sd0001, sd0002, and so on.
You can then convert these to GIF as
"ras2xbm sd0001 | xbmtopbm | ppmtogif > sd0001.gif".
Alternatively, for colour screen dumps you can use the improved
sdump
script from our
shell script archive
to get a screen dump saved directly to a colour GIF file.
This improved sdump script is included in release 20070626 or later
releases of the software.
Using it on older releases will require installing this script in place of
the existing sdump
program, if you want to run it directly from analysis as above.
Then all you need to do is run the
sdumpopt command as above,
but include the .gif file
name extension on the filename you give with the -save option, and this
will cause the screen dump to be directly saved as a colour GIF image.
Both of these techniques just grab the inside of the window running the
program, without the borders or title bar. If you want a screen shot that
includes the whole window, frame and all, or even the whole screen, you can
do that too, with a variation of the command in the sdumpgif script above.
Running a command like the following, either in a shell script or directly
from the command line, will grab the whole screen after a 5 second delay
to give you time to bring forward the window you want:
If all that is getting too technical, there are some simpler techniques
you can use to get screen shots.
On Linux systems running the GNOME desktop, you can use the
<PrtScr>
(print screen) key to copy the whole screen image to a PNG file, for which
you are prompted to enter a file name and location.
GNOME also lets you use
<Alt><PrtScr>
to copy only the active window, including its border.
Under KDE, you can use the KSnapshot utility to capture a region of the screen
to the clipboard, then paste into another application.
If your system has the GIMP
image editor, you can use
FileAcquireScreen Shot...
If your system has the xv
program installed, you can run it in the background, and use the Grab
button on the xv controls window to get a screen shot. Similarly with
xpaint you can get a screen shot from the XPaint tool
window using FileTake Snapshot...
Either way, you have the option of selecting a region of the screen to grab
using your mouse.
If you're working on a Mac, there are numerous techniques for getting
screenshots covered in this article:
Screenshot Hacks for Mac OS X.
However, the quickest and easiest way to grab a whole window onto the
clipboard, so you can paste it into a document, is to use
<Command><Ctrl><Shift>4
then hit the space bar to select the window you're working on, and
click on that window. (The Command key is the one with the Apple logo and/or
clover symbol on it.) You can then go to your Word document and paste
the graphic into it.
Whatever technique you use to grab the screen shots, you may decide to
do some cropping or other editing using whatever image editor you're
comfortable with. You may not need to do any editing at all, but if you're
grabbing shots of the whole screen, it may be preferable to crop these so
they include only the relevant window in the image you end up embedding
into your document. You may also want to do some resizing of images in
an image editor if the word processor you're using doesn't to a good job
of resizing them.
For final output from analysis, a screen shot may still do the trick
for your tutorials. However, if you prefer a more uncluttered rendering
of a plot file produced by the program, here's a simple way to convert
it into an image of the size you want.
There's a new program in the 20020426 release of the analysis software, called
hpgl2gif,
that gives more optimal results for analysis
plot files than what some other conversion tools might produce.
(It's what's used by the rawwfplt program that makes "movies" of run
data, as a series of GIF frames.) Here's an example of its usage:
hpgl2gif -w 600 cbc0201.plt > cbc0201.gif
Use "hpgl2gif --help" to get a description of its options. The
-w option specifies the width in pixels, and the height will
change proportionally. 600 is an ideal width for the cover page images.
We also recommend setting the Data pen to 2 and Markers pen to 3, in the
Plot menu, before plotting to a file, so you get a bit of colour in the
final graph.
It shouldn't be necessary to get fancier than that with the final plots,
unless what you're trying to show in the tutorial is how to pretty up your
graphs. For instance, a tutorial on how to prepare graphs for publication,
using Corel Draw, could include the original plot file rendered as above,
followed by screen shots showing what it looks like when first imported
into Draw, then at various stages afterward. This is a hint, by the way,
of a tutorial that would be worth writing, if you're looking for ideas.
So you've written up your tutorial, complete with data files, step by step
explanations, and all the figures you need to get the point across.
What's next?
Proofread it.
Check it over carefully for spelling errors and for anything that might be
unclear. Walk through the examples to make sure they work as promised, without
needing any additional, undocumented steps.
Make a PDF.
In WordPerfect 11, use
FilePublish ToPDF...,
and use ZIP compression in the Objects tab for simple graphics (line art),
or JPEG compression with a quality factor of 106 for photos. JPEG compression
is really designed for photo compression, whereas ZIP (a.k.a. LZ or LZH
compression) and LZW are designed for lossless data compression and tend
to do better with line art with limited numbers of colours and large
areas of the same color, especially large horizontal runs of one colour.
JPEG compression on line art tends to put a "haze" around the lines
or the text. The procedure is similar in WordPerfect 9, except that you use
FilePublish to PDF...,
and select the compression type from the Details tab.
There's also a quirk in the compression in WordPerfect 9: unless
you always click on the Details tab before making a PDF, it will default
to using no compression, not to the last compression type used.
If you're not using WordPerfect, then you should install the full
Adobe Acrobat package, and print from your word processing software to
the Acrobat Distiller pseudo-printer to generate the PDF.
Under Mac OS X, PDF is a native format, so any application has the ability
to produce PDF files.
There are other PDF generating tools available as well. Use whatever
works for you.
Upload the .wpd (or .doc) and the PDF versions of the document.
At the SCRC, we currently store these tutorials in the directory
dave2:/home/exp/dave/tutorial/cd/, as well as
in cliff:/data/tutorial/cd/, as
tutorial_number.wpd and
tutorial_number.pdf,
where number is the assigned tutorial number.
If you have access to these systems, please upload the files there
yourself. Putting them on cliff will directly update
the web server's copy. If you don't have access to these systems,
please make them available to us in some other way, either by placing
them on another web server or ftp server, or by e-mail.
In any case, let us know that you've copied the new files or updates,
and where you put them, so we can do any follow up work that may be needed:
moving them into place, updating or making new cover pages, and updating
the tutorial index page.
Upload the image for the cover page,
if you have one, as
tutorial_number.gif.
For new GIF images for the cover pages, put them in the same directory
on dave2. You can also put them on cliff, if they're the same size
as the ones they're replacing (in pixels, rather than in bytes which
is less important), or if these are images for a new tutorial.
We recommend images of about 600 pixels wide for the cover pages, but
anywhere from 400 to 700 pixels will do. Use what's needed for a clear
image. If you want to make a thumbnail image too, please do.
We put these in the same directory, as
tutorial_numberthumb.gif.
These are to be exactly 120 pixels wide, and no more than 98 pixels high.
We usually make these by shrinking, and possibly cropping, the cover page
image, to get something of the size we want. Slightly blurring the image
before shrinking it can help make it clearer in its shrunken form, if
your image editor doesn't do "anti-aliasing" when shrinking images.
If you'd rather not have to make the thumbnail image yourself, you can
leave that job to us. We can also make the cover page image too, if you
tell us which figure we should extract from your document as the most
representative final result of the tutorial.
Upload any new run files the tutorial needs,
into the same directory on both dave2 and cliff. These can be uploaded there
right away, as no further action is needed on our part.
The showrun.cgi
program on our web server will find them
there and include them in its index.
Similarly, any new or updated script files can go in
/home/exp/scripts/ on both systems, and they'll automatically
be found by the
viewscript.cgi
program on our web server.
Again, if you don't have access to our systems, please make all images,
data files and scripts available to us in some other way,
either by placing them on another web server or ftp server, or by e-mail.
Do some usability testing.
Enlist the help of a few novice users (new students, technicians)
and ask them to walk through the tutorial. This should help sift out
any problem areas, which need further clarification or more elaboration
of the steps to follow.
E-mail us to let us know
of the tutorials you've just uploaded, so we can update the tutorial index page.
Let us know where you put them, and what follow up work might still be required.
We appreciate any contribution you can make, including producing the PDF files,
cover page images, and thumbnails. However, we will gladly make these if you
can't. The most valuable contribution is the source document itself, and the
knowledge that went into it. Please also let us know which data files and
scripts your tutorial uses, so we can include links to these on the cover page.
Keep it up to date.
After the tutorial is up on the web site, you may find errors you missed before,
or think of a better way of doing something. It may also be that changes in
the software in the future will require updates to some tutorials. Please
let us know of any updates they need, or better still, update them yourself.
You can submit updated tutorials in the same way you contribute new ones.
Again, just let us know what follow up work may be needed, such as updating
the cover page, index page, thumbnail, data file links, or anything else.
We gratefully welcome any contribution you can make to aid in this effort.