Development and Design | Documentation | Contents | Tutorial | Submission Information
The following is a brief overview of style and format requirements for Physics Academic Software user's manuals and software. Physics Academic Software strives to retain the individual flavor of each software packages while maintaining high standards of consistency among all PAS titles. Therefore, when developing your package for submission, please follow these guidelines closely.
Successful educational software must aid the learning process, not add to it. Since a software program will most often be used for only one course, or one section of a course, it must be easy to use or it may not be used at all.
When designing your program, structure it for inherently intuitive operation. Guide the user through the program with prompt messages, option menus, pop-up windows, on-screen command lists, and context-sensitive help screens. Protect the user from inadvertent loss of data and provide easy recovery from drive and printer errors. Use accurate numerical techniques and correctly model the physics concepts.
If your software includes a program with a copyright holder other than yourself, you must send us a copy of your license agreement for that program.
Much has been written on the development of quality educational software. One valuable source of information is "A Practical Guide for the Creation of Educational Software," by Ruth W. Chabay and Bruce A. Sherwood. To obtain a reprint of this material, write to the editor of Physics Academic Software.
As a general rule, write your documentation in the active voice and imperative mood. Address the student-user in the second-person singular form as "you," and address the instructor-user in the preface and instructor's guide sections only. Use vivid, concise language, and include graphics and a tutorial.
Unless otherwise noted herein, follow the style conventions of The Chicago Manual of Style and the American Institute of Physics Style Manual for rules regarding grammar, spelling, mathematics, reference material, and scientific abbreviations.
All PAS user's manuals contain three sections: a front, a body, and a back. Within these sections, information is grouped into chapters, sections, and subsections. Key words may appear in the margin to highlight specific concepts or points covered in a subsection.
The front section
A standard template is used for the front section of all PAS documentation. Appendix B contains a copy of this template. If you submit a package for publication, simply "fill in the blanks" with the appropriate information for your program and include it with the body of your documentation. It is important to note that material covered here need not be repeated again in the manual.
The specific components of the front section are always as follows:
Keep in mind that the Preface text should motivate students and teachers to use your software. Prospective users will read this section first to learn about your package. It should be strong and informative and contain explicit reference to the highlights and benefits of your program.
The body section
The body of your manual should include, in the following order, these specific components:
The back section
The back section of our documentation is also derived from a standard template and, like the front section, remains basically the same regardless of the program. Only the index is specific to the software, and this section is generated at the very end of the production process.
The specific components of the back section are always as follows:
Your documentation should include a tutorial that both orients the novice user with the features of your software and encourages further exploration and use. When writing the tutorial, choose your words and phrasing as if you were speaking directly to the student. Address particular functions and explain how they are used in the program. For example, what does Save do? Give enough information to familiarize the user with the functions, and explain how to operate them.
To inform the user how to operate the function, choose one of the following phrases:
To save, press <S>
Press <S> to save
Select save
For tasks that require more than one step, list each operation separately. Each step should use only one or two lines. For example:
The next prompt asks for the initial value of x
Type 2.21 and press <ENTER>
Press <+> to add this value to the list that is currently displayed on the screen
To save the value, press <A>
Where more information is necessary, insert the additional instructions between the steps in full-sentence form. For example:
The next prompt asks for the initial value of x.
Type 2.21 and press <ENTER>
You can now add this value to the list of initial values. The current value will be placed last on the list.
Press <+> to add this value to the list
To keep this value in a file for later use, you can save it.
To save the value, press <A>
If there are options within one function, describe the options in a single paragraph, ending with the words, "Do the following:"
To (option 1), type (word) and press <ENTER>
OR
To (option 2), do the following:
1. (First step)
2. (Second step)
When several detailed steps are required, they should be numbered.
See A Model Tutorial as an example.
If your package is accepted for publication, we will request a double-spaced hard copy of your manual; 8-1/2" x 11" originals of all figures used in the manual (Pict or Tiff files are highly desirable as well); screen printouts showing on-screen prompts, dialog boxes, labels, etc.; and text printouts of all help files for editorial purposes. We will also request an electronic version of your documentation. We use Word 5.1 for the Macintosh; anything that can be translated into Word will suffice.
Existing PAS manuals are, by example, excellent sources of references for format guidance. If you have a major format question, please contact the PAS editorial office for assistance.
For information on submitting the software, refer to the Electronic Submission page.
Send submissions to:
Dr. John S. Risley
Physics Academic Software
Box 8202
North Carolina State University
Raleigh, NC 276958202