USER DOCUMENTATION

ABOUT THE MANUSCRIPT SUBMISSIONS TRACKER

Purpose:

I wrote the Manuscript Submissions Tracker (MST) because, as an aspiring writer, I needed a better way of tracking my submissions, acceptances, and rejections than simply relying on memory and scraps of paper. I originally tried to write something in OpenOffice.org Base or Kexi, but quickly found that I really hate designing forms for that tools; thus, I decided to write the thing in PHP and put it up on my website so that I can access it easily from the various different places where I write and manage my submissions.

The software allows you to do the following:

• Track and manage manuscript information, including revision notes

• Track and manage market information, including staff information if desired

• Track and manage submissions

The software is meant to be complete in and of itself, but includes a simple API that developers can use to extend it. See Developer Documentation, below.

System Requirements:

PHP 4.3+

MySQL 3.23+

This software was developed and tested on FreeBSD running Apache 1.33, but should operate just fine in any web environment which supports PHP and MySQL. The dblib.php file can be edited to support any other database, but MySQL is what I used.

Current Version:

As of April 28, 2006, the current release of the Manuscript Submissions Tracker is code-named Tom Servo, and is at version 0.02.

INSTALLATION

To install the Manuscript Submissions Tracker:

1. Upload the tar.gz file to the directory you want to install the Manuscript Submissions Tracker to, and untar it with the command: $ tar xvzf tomservo-0.02.tar.gz

2. Browse to the install.php script in your web browser and execute it. Enter the information requested by the script.

3. That's it!

I recommend installing the MST in a password-protected directory.

USING THE MANUSCRIPT SUBMISSIONS TRACKER

Before any submissions can be recorded in the Submissions Tracker, you need to enter manuscripts to submit and markets to submit to.

Entering and managing manuscripts:

To enter a new manuscript, click on "Manage Manuscripts" at the top of the main page. If any manuscripts are already in the database, they will be displayed in a table on the next page, with the following properties:

• Title. Self explanatory. To retrieve full information about the manuscript, click on the title to bring up a popup window with all information.

• Revision. The most recent version number of the manuscript. Click on the revision number to retrieve the full revision history for the manuscript. See the note "On Revisions", below.

• Date Started. The date you started working on the manuscript, as entered into the database.

• Date Finished. The date you finished the manuscript, as entered into the database.

• Current Status. This field shows the current submission status of the manuscript; either "Available for submission", "Not available for submission", or with a list of markets the manuscript is active at. See the note "On Availability", below.

• Functions. Click on "Edit" to enter changes about the manuscript. Editing a manuscript will update the revision number (see the note "On Revisions", below). You can update a manuscript's availability for submission by clicking on "Remove" or "Restore" (see "On Availability"). Note that you cannot remove a manuscript from circulation if it is currently in submission to at least one market.

On Revisions: A manuscript's revision number in the MST system is not meant to be any sort of official "version" of the manuscript. However, if you revise a manuscript significantly, you may find it useful to know which version of the manuscript you have sent to a market. MST tracks two types of revisions and changes the revision numbers accordingly. Major changes add 1 to the version number (from 1.0 to 2.0, for example), while minor changes add 0.1 (from 1.1 to 1.2, for example). A major change resets the minor revision number to zero (1.2 goes to 2.0). When you click on "Edit" in the manuscript list, the notes you enter in the next page are stored in the database, so that you can keep a history of manuscript changes.

On Availability: Most manuscripts are available for submission when you enter them into the database. You may find it useful, though, to temporarily mark a manuscript as unavailable for submission so that it is still in the database but does not show up in the drop-down list in the submission form. To do this, click on the "Remove" link in the manuscript table. Note that if a manuscript is currently in submission to one or more markets, it cannot be removed. To bring a manuscript that has been marked as "removed" back into circulation, click on "Restore".

Entering and managing markets

To enter new markets into the database or edit existing ones, click on the link which reads "Manage Markets and Editors". If there are any markets in the database, this will bring up a table with all the markets listed. The table shows each market's name, the editorial staff, and an "Edit" function. To view the complete information about a particular market, click on the market's name; this will bring up a pop-up window with the complete information.

To add a new market to the database, fill out the form below the market listing table. The form elements are:

• Name: The name of the market.

• Address 1: The first line of the market's street address, if available

• Address 2: The second line of the market's street address, if applicable and available

• City: The city in which the market is located, if available

• State or Province: The state or province in which the market is located

• Postal Code: In the US, this is the ZIP code.

• Country: The country in which the market is located

• Phone Number: The phone number for the market

• Fax: The fax number

• Preferred Submission Method: Select either USPS or Email.

• Submission Email: If the market prefers submissions to be sent by email, enter the submission email address here.

• Multiple Submissions? Enter Yes or No here. This indicates whether the market will allow a writer to submit more than one manuscript at a time. This information is available in the market's submission guidelines.

• Simultaneous Submissions? Enter Yes or No here. This indicates whether a market will consider a manuscript which is also currently in active submission at another market. This information is available in the submission guidelines.

• Reprints Okay? Enter Yes or No here to indicate whether the market considers manuscripts which have previously been published.

• Notes: Enter any notes here about the market.

To update the editorial staff information about a market, click on the link which reads, "Update Editorial Staff". This will allow you to edit an editor's information or delete them from the database altogether.

Entering and Managing Submissions

Of course, the primary purpose of the MST is to track manuscript submissions. When you pull up the MST, the first page displays all of your current submissions, as well as a form to record new submissions. The drop down box to the left contains the list of all manuscripts in the database which have not been marked as "removed", and the drop-down box to the right contains the list of all markets in the database. The table displays the following information:

• Manuscript. The manuscripts that are currently in submission.

• Market. The market that the manuscript has been submitted to.

• Rev. The revision number of the manuscript that was sent.

• Submission Date. The date that the manuscript was submitted.

• Status. The status of the manuscript -- either "Awaiting Response", or what the response was.

• Turnaround. The number of days elapsed from the submission date to the current date (for manuscript still awaiting responses) or to the response date (if the manuscript has been responded to.)

• Functions. Click on "Update" to make changes to the submission information, such as to indicate that a market has accepted a manuscript for publication.

To enter a new submission, simply select the manuscript in the left-hand box and the market in the right hand box, then click "Proceed". The next screen will allow you to enter more information about the submission, including selecting the specific version of the manuscript which is being submitted.

This screen will also display various warning messages related to the submission, if any apply. If the manuscript has already been submitted elsewhere, the software will generate a warning. It will also warn of simultaneous and multiple submissions, as well as reprints, and let you know the market's terms for those conditions (assuming the information has been input properly into the database).

To update a submission, click on the "Update" link. This will bring you to a form where you can enter information about the market's response to the submission, including the date that a publication contract was signed (if applicable) and the date of publication.

DEVELOPER NOTES

The MST is written with object-oriented programming. A class called Tracker() is used to manage all submission, manuscript, and market information.

The Tracker class has the following properties defined:

Tracker->manuscripts[]

An array of manuscript objects. Each manuscript has the following properties:

id: the ID of the manuscript in the database

manuscript_title: The title of the manuscript

manuscript_date_started: The date a manuscript was started

manuscript_date_finished The date a manuscript was finished

manuscript_summary: A brief summary of the manuscript

manuscript_notes: Notes about the manuscript

manuscript_deleted: A flag indicating whether the manuscript has been removed

curr_rev: The current version number of the manuscript

revisions[]: An array of revision objects indicating changes made

id The id of the revision on the database

tid The id of the manuscript

rev_number The revision number of the manuscript for tracking

rev_date The date of a revision

rev_type The type of revision (Creation, Major, or Minor)

rev_summary A summary of the revision

rev_counter A count of revisions made to the manuscript

Tracker->markets[]

An array of market objects. Each market has the following properties:

id: The ID of the market in the database

market_name: The name of the market

market_add1: The first line of the market's address