Instructions for Teachers at SpiritAndTruth.org

This document provides recommendations and requirements for teachers who have been invited to publish teaching materials at SpiritAndTruth.org. Recommendations are optional suggestions intended to help the teacher be more successful at publishing content. Non-optional steps which are required for either doctrinal or technical reasons.

NOTE: This document and related files may be viewed online at https://SpiritAndTruth.org/teaching/0.htm.

Why This Document?

Although the length of this document may seem a bit intimidating at first, it really isn't very complicated to publish material on the website. In fact, it is possible to publish material without being aware of many of the concepts and procedures this document describes. However, a little time invested up-front in understanding the procedures and issues will go a long way in making publishing routine and providing high-quality content with a professional appearance. However, it is recognized that not all teachers will be as comfortable with the technical aspects of what is described here. If you feel that is the case, please contact the www.SpiritAndTruth.org website administrator (contact@SpiritAndTruth.org) and we can probably arrange a compromise approach involving less responsibility on your part. But if you can follow the guidelines here, it will give you more flexibility and save considerable time for all involved.

Review the Doctrinal Statement

Although SpiritAndTruth.org offers bible study aids which, although orthodox, may differ from our doctrinal statement, this is not our policy concerning new teaching materials which we provide on our site. Therefore all teachers must review and agree to our doctrinal statement. If you disagree with a minor aspect of the doctrinal statement, please contact me (contact@SpiritAndTruth.org) and we can talk about it.

Great importance is attached to the doctrinal position of our teachers so that students who utilize our materials have confidence in knowing exactly what they will encounter, especially from new teachers who they are unfamiliar with.

Capturing Teaching Content

Most teachers will be publishing documents or audio recordings. When producing your teaching materials, keep in mind that most students have a relatively slow connection to the internet. Therefore, emphasis should be placed on keeping teaching materials as small as possible. We recommend that all audio recording be produced in a compressed format such as MP3, real-audio, or similar. To capture audio recordings, I use a handy portable MP3 digital recorder made by Pogo Products (the “ripflash trio,” www.pogoproducts.com).

As far as publishing documents is concerned, teachers can publish material in any format. However, please keep the following considerations in mind:

1. Some students will have very limited computing resources. They may be using old computers or, due to cost considerations, be limited to using free or open source software.¹

2. Everyone who views the teaching materials, whether over the internet or on a CDROM, is guaranteed to have a basic web browser. Therefore, HTML is the preferred publishing format for documents. You may want to offer other formats as well, but please try to offer at least HTML so that students can immediately view your content without having to obtain and install other special reader software.

3. Keep in mind that there are many different computing platforms and operating systems available. As time goes by, an increasing number of students (especially international ones) will be using non-Windows operating-systems (such as linux). Therefore, do not assume that Microsoft-centric documents are always easily read by all students. This is especially true for documents with complicated layout or unusual characters (e.g., Hebrew or Greek). For these documents, you should consider publishing in Adobe Acrobat format (www.adobe.com).²

4. At this point in time, video content is discouraged. It consumes a great deal of storage space and does not provide enough value in relation to the complications of dealing with it and the long download times.

Providing Biographical Information

As a teacher at SpiritAndTruth.org, we need two things from you (besides the material you are publishing):

• A photograph suitable for presentation on the front page of our website and with all course material you publish. Please try to provide a JPG file (or similar format) using an aspect ratio of appoximately 1.3-to-1 (height-to-width). You can see an example at www.SpiritAndTruth.org/teaching/teachers/tony_garland/image.jpg.

• A short biographical description to accompany the file.

Content Publishing Framework

When viewing the teaching materials at SpiritAndTruth.org, you will notice a common table-based presentation of the courses and their individual sessions (or classes). Each course by an individual appears in a top-level table (www.SpiritAndTruth.org/teaching/index.htm). From there, each course has its own sub-table (for this course: www.SpiritAndTruth.org/teaching/0.htm) which lists individual class sessions.³ Each individual class session then lists the files and resources associated with that class.

To manually produce these tables (with their attendant descriptions, links, and file information would be extremely time-consuming and error-prone. Therefore, an automated conversion system is used. As an author, you provide some very basic information describing the course and its sessions, and the conversion tool (run by the site administrator) automatically produces updated tables for the website.

Naming the Course

This is done by creating a directory name. For example, the directory name for this instructional course is “publishing_teaching_materials”. Several rules govern directory names you can use:

1. No spaces are allowed (use underscores instead).⁴

2. Initial lowercase letters in each word are automatically converted to uppercase.

3. For mixed-capitalization, providing one uppercase letter causes the converter to leave your capitalization as-is.

So, the above directory name results in the course title “Publishing Teaching Materials”. Where mixed-capitalization is desired, this is achieved by specifying one or more uppercase letters in which case the converter preserves your capitalization unchanged (e.g., “Galatians_by_Steve_Lewis” results in the title “Book of Galatians”).

Naming the course must occur prior to publishing any material.

Produce a Course Description

Within each course directory, the conversion tool looks for a file by the name index.txt. This file contains specially formatted text providing important information about the course.

1. Course number – each course has a unique assigned number (in this example 0). This provides a short-cut way to refer to the course when using links on the internet. Course number 0 would be found using the following link: www.SpiritAndTruth.org/teaching/0.htm. (Each session below that course can also be found using a similar abbreviated link. For example, the 2^rd session of this course (#0) would reside at www.SpiritAndTruth.org/teaching/0-2.htm.⁵

2. CD number. This is always initially set to zero. Later, when the course is completed and placed onto a CDROM, it will be changed to reflect the ID of the CDROM containing the course. (Students can later request the CD using this ID number.)

3. Teacher's name (in this example, John Calvin).

4. Relative path to the teacher's biographical file (in this example, teachers/john_calvin/bio.htm).

5. Relative path to the teacher's image file (in this example, teachers/john_calvin/image.jpg).

6. Description of the course (may contain any valid HTML key words).

These fields are separated from one another by the vertical bar character (|). For example:

0|0|John Calvin|teachers/john_calvin/bio.htm|teachers/john_calvin/image.jpg|Description...

All the fields must appear on a single line, but the description can span numerous lines. Any line beginning with the # symbol is considered a comment and ignored.

An index.txt file corresponding to this example course can be seen at www.SpiritAndTruth.org/teaching/publishing_teaching_materials/index.txt. The corresponding published file produced from it can be viewed at www.SpiritAndTruth.org/teaching/publishing_teaching_materials/0.htm.

Name each Class or Session

Name each session. This is also done by creating subdirectory names below the course directory. This session appears below the parent course directory as “publishing_teaching_materials/01_introduction”. Session names follow the same rules as course titles, with one additional caveat: please use an initial sequence number. This sequence number determines the order in which sessions are presented in the course table. If your course will have more than 9 sessions, then a leading zero is required so that “10_” will not appear before “2_” (the initial “1” appearing as less than “2”). If you will have more than 99 sessions (!) you'll need two leading zeros. You might also consider reserving the use of “00_” for introductory material which is not part of a designated session. Similarly, I have used “99_” as a place holder for a “dummy session” which contains entries to each of the audio recordings from all the other sessions.

Sessions do not need to be named in advance. Simply create each session as the class progresses.

Produce Class Descriptions

As you produce each class (or session), you will populate the class subdirectories with an index.txt file describing the class and listing those files in the directory which you desire to publish. The first few lines of the file (as many as are needed) contain the description of the class. Thereafter, a description is given of the files which you want to expose (publish) from within the directory.⁶ These description for each file must reside on a single line (each) and consists of the following fields:

filename|Short Title|Description...

When publishing a single source document in multiple formats, an entry is made for the first format and subsequent formats are listed immediately thereafter with in abbreviated form:

filename.htm|Document Title|Description...
filename.pdf
filename.doc

Only the first entry provides a shared title and description. The subsequent entries which share the same filename (sans extension) provide information for he publishing program so that it will list the file showing all the available formats that are available for access. (The example above follows recommended guidelines in that the HTML version is primary, Adobe Acrobat is the preferred secondary format, and Microsoft Word, if present, follows. You control what formats you want to produce, these are just suggestions. At a minimum, we suggest HTML.)

An index.txt file corresponding to this example class can be seen at www.SpiritAndTruth.org/teaching/publishing_teaching_materials/01_introduction/index.txt. The corresponding published file produced from it can be viewed at www.SpiritAndTruth.org/teaching/publishing_teaching_materials/0-1.htm.

Directory Structure

As you produce your course you will be incrementally populating a small directory tree with the top-level being your course title and each branch (subdirectory) being your class sessions.

Course Directory	Class Subdirectories
publishing teaching materials/	index.txt
	01_introduction/	index.txt
	02_examples_for_download/	index.txt

You control the content below your course directory whereas the SpiritAndTruth.org website administrator takes care of integrating your course directory with the other teachers and courses on the website:

Website Home	Subdirectories	Course Subdirectories
www.SpiritAndTruth.org/
	teaching/
		publishing teaching materials/
		israel_through_the_eyes_of_scripture/
		other_courses.../

As you produce each class, you will be packaging up the new course subdirectory (and its contents) and submitting it to our website. The website administrator will take it from there.

Working with Audio

Assuming that you plan to record audio for your course, you will may find some of the following tips useful.

Portable digital recorder. I use the Ripflash Trio by www.pogoproducts.com. It is slightly larger than a business card, can record many hours of high fidelity audio, and is very easy to set up and operate on your own. I typically put it in my shirt pocket and wear a lapel microphone (often beneath my sweater where it is less obtrustive—you can boost the volume later on if need be).

Audio Editing Software. I prefer the GoldWave program (www.goldwave.com) which costs approximately $40, but is worth much more. Another good program is Sonic Foundry (www.soundforge.com). I prefer the former mainly because it supports saving material at 16Kbps MP3 which is the main sampling rate I use. Although it is possible to record your MP3 material directly and transfer it to the internet without any editing, There are a number of adjustments you are likely to want to make:

1. Editing out errors or sound artifacts.

2. Boosting the volume. Remember, digital recording is very clean so you can get by with a very low record level provided you can adjust the volume upward after-the-fact. Unlike analog recording, you can boost digital levels without any increase in attendant white noise.

3. Adding title, author, and copyright information to the audio file.

4. Shortening the length of the recording. GoldWave works especially well for this using its time warp function which allows you to reduce the time of the overall recording without affecting the pitch noticeably. If any of your class sessions run longer than 74 minutes in duration, it is very helpful to be able to time warp the recording to within 74 minutes.⁷

5. Change the recording quality. It is advisable to make your recording at the highest fidelity setting your digital recording equipment can provide. However, for use over the internet, high-fidelity is prohibitively large and slow. Once you have captured your high-fidelity original (and saved a backup copy), you will want to resample the recording at a lower rate. I recommend 16 Kbps mono. This results in a good trade-off between quality and size.

6. Adding 'check numbers' if and when you provide material to be used for a seminary course such as those offered by www.Tyndale.edu.

Publishing Tools from www.SpiritAndTruth.org

If need be, you can publish material on the website without using any of the following tools. These tools are offered in order to allow you to preview your content (to see how it will look prior to submitting it) and to allow you to directly submit large files to the website without encountering email size restrctions which some ISPs impose.

• makeindex -

• tar, gzip -

• ssh, scp

• bibletag -

Previewing Your Material

After you have put together the necessary directory tree with the course directory as the root and each class as a branch (subdirectory), you can utilize the makeindex program to preview what your teaching material will look like on our website. The makeindex program is supplied both as a Windows executable and as python source. If you are running Windows, you can run makeindex.exe directly as 'makeindex <path_to_your_course_directory>'. If you are not using Windows, then the python version can be run as 'python makeindex.py <path_to_your_course_directory>'.

makeindex descends the course directory tree and produces a set of HTML files corresponding to the directory structure (course title and session titles) and descriptions (in the index.txt files).

[NEED TO TRY THIS OUT AND SEE WHAT FILES ARE PRODUCED WHERE]

Some of the graphics icons will be missing (since you don't have the entire SpiritAndTruth.org website on your local machine), but the output it produces will allow you to:

1. Verify the basic visual appearance and content of the course material.

2. Verify that all the files you list in your index.txt files are actually present and that there are no typos. (This saves the website administrator considerable time having to correct mistakes after-the-fact in the material you upload.)

Submitting Your Material

Zip

email

scp

website admin will do bible tagging

New Formats

Tools You Will Need

Detailed Steps