TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Kathleen Holscher reports a problem with a complex naming
scheme for Oracle files.
<<My problem is that the name of the file could be unique on
every system.>>
Variable, yes, but probably not as bad as you're thinking.
From your description (below), it sounds like there is a very
simple sequence of actions that the software uses to assign
prefixes and suffixes to the root word for the file name.
(There's no indication that the file names are assigned
randomly, which would be a challenging problem indeed.) If
I've misunderstood this sequence, you should be able to get a
better handle on it by sitting down with the SMEs and asking
them to describe how the names are constructed.
<<If the user installs Oracle and uses all of the defaults they
will get a file called initorcl.ora. If the user installs Oracle
and specifies their own files names, for example, prod, the file
will be called initprod.ora.>>
That defines the starting point in your description:
All "initial" files created by Oracle begin with "init" and end
with the file type ".ora". The software names the initial file
"initxxxx.ora", where xxxx is replaced by orcl (i.e., the file is
initorcl.ora) if you use the default values suggested by the
software; if you specify your own filename (e.g., prod), then
replace xxxx with that filename (i.e., the file name becomes
initprod.ora)."
<<To make this list of file names even more complex, there
are some file names that are assigned unique numbers for
one of two reasons. So they may have files called
data1orcl.ora, data2orcl.ora, etc. And of course, if they
specified their own names the files may be data1prod.ora,
data2prod.ora, etc.>>
That defines the second step in describing the file names:
The initial file you created will be either initorcl.ora or
initxxxx.ora (where xxxx represents the name you chose for
the file). Oracle also creates numbered data files by adding
"data1", "data2", and so on, to the initial file name. Thus, if
you chose the default initial file name (initorcl.ora), the first
data file will be "data1orcl.ora"; if you gave your initial file
the name "initprod.ora", the first data file would instead be
"data1prod.ora" instead.
<<this name that they may or may not specify is known by
two different descriptions - an instance name or a SID.>>
Using two words to refer to the same concept or object is
almost always a bad idea in documentation. My
recommendation would be to pick the most user-friendly of
the two and stick with that consistently throughout the
documentation. If you absolutely must use the two names
(and you'll have to convince me that's necessary!), then get
rid of the word "or", which suggests a choice between two
different things rather than the use of synonyms:
<<This column lists each file name using the default instance
name or SID assigned during a default Oracle installation.>>
Revise as: "... using the default instance name (the SID)
assigned..." This is shorter (no more "ors" anywhere) and
clearer (using "the" sends a clear message that what we call
the default instance name is what the techies call "the SID").
I've done this the wordy way to illustrate the principle behind
solving your problem, so you'll have to revise and polish the
text to better fit your style and needs. But hopefully it gives
you a starting point for solving your problem. Good luck!
