Internal Technical Memorandum ITM-1998-01
A New Series of Technical Documents:
Internal Technical Memoranda (ITMs) and
User Information Reports (UIRs)
D. Soderblom, J. Younger, M. Asbury, A. Koratkar, and D. Golombek
September 30, 1998
Concurrence: G. Miller
ABSTRACT
A new series of technical documents is described. Internal Technical Memoranda (ITMs) are
intended solely for distribution within STScI by electronic means, and may be used to describe
policies, procedures, other documents, and for other purposes where it is worthwhile to provide a
written record. User Information Reports (UIRs) are intended to be read by the outside community
as well as inside STScI, they therefore must meet higher standards of preparation and presentation.
This first ITM describes procedures for including a new document in either series and a short
description of this template.
1. Introduction
Instrument Science Reports (ISRs) continue to be an effective means of documenting critical
information about HST’s science instruments and for making that information available to the user
community. Recently the ISR series was split to create a less formal complementary document that
is intended solely for internal purposes (the Technical Instrument Reports, or TIRs), recognizing
that some information needs to be documented for the record, or prepared somewhat differently if
it is leading to another report that will later encapsulate results for users.
The two series of reports described here are intended to fill similar roles for Presto and the rest of
STScI. One series is Internal Technical Memoranda and the other is User Information Reports.
UIRs will be posted on public web pages as PDF documents and made freely available to anyone.
ITMs will be posted on web pages that can be accessed only from within STScI. Neither should
supplant a web page as such if users or STScI staff need access to the type of information best presented with HTML. Instead, ITMs and UIRs should provide a focussed discussion or source of
information on a fairly narrow topic.
Some examples may help to clarify the usage of different means of presenting information:
• Basic rules and procedures for filing HOPRs should be readily accessible on the web in
HTML. Details on those rules would be appropriate for a UIR that a GO can download and
read. An administrative report that summarized HOPRs for the past year and their disposition would be an ITM.
1
Internal Technical Memorandum ITM-1998-01
• It may be helpful to prepare a brief report summarizing policies and procedures used for
Cycle 8 Phase I proposals, say, for future reference so that consistency can be maintained.
That would be intended for internal use and would be an ITM. A list of accepted programs
and the panel members would make a good UIR, or could be put into HTML, or both.
• Special policies and procedures that have been applied to the end of science for NICMOS
could be documented for future reference as a ITM. Portions of that may be appropriate for
a UIR.
2. Templates and Their Use
FrameMaker templates have been created for both report types. They may be found under “STScI”
after activating the “OPEN” button in your Framemaker tool.
Both templates are identical except for the header.
2.1 The header and document number
The document number (e.g., ITM-1998-01) gets entered once on the Master Page of the first page
of the document. The two digit trailing number will be assigned at the time the preparation of a
specific report is assigned (see “Procedure” on page 4.).
2.2 Title
The document should have a concise title that lets the reader know whether or not the document is
likely to contain the information they seek. “HOPRs” is too cryptic, “Policies and Procedures for
Filing HOPRs” is better, and, if appropriate, “Policies and Procedures for HOPRs in 1998” is even
better.
2.3 Authors and Date
The date gets set automatically to today’s date, so remember to change it to text when you are done
with the report.
2.4 Abstract
Again, conciseness is important, but so is pertinence. An abstract that states “This document presents currently applicable policies and procedures for filing HST Operations Problem Reports”
could probably have been inferred from just the title. “Policies and procedures for HST Operations
Problem Reports are presented, including ones specific to NICMOS end of science. This document
supersedes ITM-1998-02 and is valid through December 31, 1998” provides a lot more
information.
The “Abstract_end” paragraph type should be used for the last paragraph in the abstract so that the
bottom rule is produced. It could also be the first paragraph is there’s only one.
2.5 Headers
Paragraph styles for headers are 1Head, 2Head, and 3Head, of which the first two are numbered.
2.6 Lists
• Bulleted lists are done with “BulletList.”
1. Numbered lists start with “NumList1”
2
Internal Technical Memorandum ITM-1998-01
2. then go to “NumList.”
2.7 Figures
Use the “FigureAnchor” paragraph type and place the text cursor there when you open an
anchored frame. The “FigureCaption” paragraph should go under the figure as explanatory text.
Make the anchored frame taller than the figure itself, place a text box at the bottom of the frame,
and then put your caption in that box. That forces the caption to remain with the figure.
2.8 Tables
As for figures, there are “TableAnchor” and “TableCaption” paragraph types. For wide tables,
there is a landscape-oriented page layout that can be applied to the table.
Sample table:
Table 1. X Offsets from the center of 4.3 arcsec aperture (in arcsec) and the corresponding
pixel shift in data points (1/4 diode units).
X-Offset
Pixel Shift
-1.464
-19
-0.925
-12
-0.385
-5
0.000
0
0.077
1
0.231
3
1.310
17
2.9 Asides
Note: This paragraph style, called “Aside,” can be used to point out particularly critical information.
2.10 Fonts
Most of the fonts in the template are standard for Framemaker. “Change_Bar” leaves text unaltered but adds a cyan change bar in the margin, as shown in the next subsection. Use
“Change_Bar” to highlight any text that has been changed from the document’s previous version.
“Xref” leaves text unaltered except to change it to blue. Apply “Xref” to any text that is a crossreference; cross-references are transformed to hyperlinks when Frame creates a PDF file, and
showing them in blue lets the reader know where such a link is.
2.11 Revisions to Documents
Sometimes new information supersedes what has been published in an ITM or UIR. If the change
is minor, the same document number can be retained, but the altered text should be reformatted
with the “Change_Bar” character format, as has been done with this paragraph. The document
3
Internal Technical Memorandum ITM-1998-01
should then have its number appended with “v2” (or higher) to make it clear a change has taken
place.
If the changes are significant, a new document should be written with an entirely new document
number. A sentence in the Abstract should have a statement of the form “This document supersedes UIR-1998-01.”
3. Procedure
We want to keep the administrative effort for these reports to a minimum while ensuring they are
useful and accessible. For the present, submit reports to Patty Cox by indicating where she may
access the FrameMaker file. David Soderblom will have responsibility for editing and overall
coordination.
4