C What Technical Writers Should Know About Configuration Interviews

Technical writers can greatly contribute to the quality of a JavaTest configuration interview — think of the text in a configuration interview as being equivalent to an application's user interface; the better the text, the easier the test suite is to run. There are two areas where a writer's contribution is extremely important:

The careful construction and phrasing of the question text
Providing extra help and examples in the More Info pane

Question Text

Interview questions should be written as concisely, consistently, and clearly as possible. Any amplification, clarification, or examples should be included in the More Info pane.

Not all questions are really questions; some "questions" are written as statements that instruct the user to specify, choose, or select an item of information.

To see an example interview, run the JavaTest tutorial in Chapter 2. The tutorial uses the Demo TCK that is part of the JavaTest Architect's release.

Question text is kept in a Java properties file associated with the interview class files; you get the path to the properties file from the interview developer. Every interview question is identified by a unique key. The key is based on a name assigned by the developer and should uniquely identify the question with the interview. Keys are of the form:

interview_class_name.question_name

The following is a snippet from the Demo TCK interview properties file:

title=Demo Interview Configuration Editor
.
.
DemoTCKParameters.cmdType.smry=How to Run Tests
using a JavaTest Agent?computer (using a separate JVM), or to run them on another computer DemoTCKParameters.cmdType.text=Do you wish to run the tests on this 
DemoTCKParameters.cmdType.agent=Using a JavaTest Agent
DemoTCKParameters.cmdType.otherVM=On this computer
DemoTCKParameters.data.smry=Test Configuration Values...
local settings of some parameters required by some of the tests.DemoTCKParameters.data.text=The following questions determine the 
DemoTCKParameters.desc.smry=Description
identify the configuration you are creating here.DemoTCKParameters.desc.text=Please provide a short description to 
.
.

The file contains the following types of elements:

The title of the full interview
A title for each question of the form: question_key.smry
The text for each question of the form: question_key.text

Additional entries for choice items that are localized

Note:

Do not type carriage return or linefeed characters within entries in a Java properties files. This causes an error when the interview is built. Use the "\n" characters to specify line breaks in question text.

More Info

As a technical writer, you can really add value to a test suite in the configuration interview More Info pane.

Figure C-1 The JavaTest Configuration Editor: Question and More Info Panes

Description of "Figure C-1 The JavaTest Configuration Editor: Question and More Info Panes"

The text displayed in the More Info pane is formatted using HTML 3.2 tags and provides a reasonably rich environment for formatting text. Although the text can be created using a WYSIWYG HTML editor, most More Info text is short and simple and is easy to create manually using a text editor.

Typically, the developer who creates the configuration interview creates the basic More Info system, seeding it with empty HTML files that you can fill in with text.

Experience has shown that it is best to create one HTML More Info file per interview question. It is also a good idea to name the More Info HTML files after the property names of the questions they describe. For example, in the snippet in the previous section, you can see that the DemoTCKParameters interview contains a question named cmdType — you should expect to see a corresponding More Info file named cmdType.html.

Formatting Styles

The following tips can be helpful when formatting your More Info topics:

Your More Info topics should link to the style sheet included in this package named moreInfo.css.

Use only HTML 3.2 tags because of limitations in the HTML viewer
Section 508 accessibility rules may apply
Do not create hypertext links to other More Info topics or other external documents
Do not add any <p> tags between the <body> tag and the initial paragraph
Use the <i> tag for variables in command lines — use the <em> tag for emphasis
All file names and code examples should be formatted in the fixed-width font using the <code> or <pre> tags
The style sheet (moreInfo.css) contains a "tight" class that you can use with <li> tags for lists in which you want less vertical space between list items. For example:
<li class="tight">This item is closer to the previous list item</li>

Indent path names and code examples using the <p class="code"> tag. The code class indents the lines 8 pixels and has no top margin. For example, the following HTML:

<p class="code">
   <i>jdk_install_dir</i><code>/bin/java</code>
</p>
<p class="code">
   <i>jdk_install_dir</i><code>/jre/java</code>
</p>

Produces the following output:

jdk_install_dir/bin/java

jdk_install_dir/jre/java

Usage and Conventions

The following list describes some conventions that have proven useful for writing More Info text:

Use the present tense when possible. For example, instead of:

"The following questions will gather..."

use:

"The following questions gather..."
When reasonable, provide examples in both Unix and Microsoft Windows format