Guidelines for contributors
This is a web version of the APiCS Guidelines for contributors, the PDF version of which comes with the APiCS Questionnaire 2008. Please read these Guidelines carefully, because they will help you to work smoothly and efficiently with the APiCS database. (See also Guidelines for survey chapters for the texts.)
Managing the vast amounts of data for the Atlas of Pidgin and Creole Language Structures (APiCS) is a demanding task for both the editors and the contributors. In order to facilitate data collection and organization, we used the computer programme FileMaker Pro 8 (a widely used commercial database application that runs on both Macs and Windows) to prepare a computer-based questionnaire into which the data can be entered directly.
If you have never worked with FileMaker Pro (or a similar application) before, it may take you a while to get used to the questionnaire. But we are confident that, after a short familiarization phase, you will discover that it is not so complicated after all, and quickly start to enjoy its benefits. If you are familiar with FileMaker Pro or similar applications, you can probably skip sections 3-4 and continue reading with section 5.
This guide is intended to give you a basic introduction to the functionalities of FileMaker Pro, and explain the various fields of the APiCS Questionnaire. You can also take a look at the FileMaker video tutorials.
Getting your questionnaire
You get your APiCS Questionnaire by downloading it from the APiCS Database page, which is managed by our database expert Bradley Taylor.
If you have FileMaker Pro 8 or 9 installed on your computer, you can work with the smaller template version (4 MB). Please open the file "APiCS_data.fp7".
Otherwise, please download the larger runtime version (24-34 MB). It contains a file ("!open_APiCS") that is in effect a stripped-down version of FileMaker Pro. It allows you to enter, export, search and sort data, just as the real programme. The data that you enter are contained in another file, "APiCS_data.USR". This file contains all your data and is the only file in the runtime folder that needs to be sent when sharing or submitting your database. (but see this note)
Your active "APiCS_data.USR" file should always reside in the same folder as its runtime programme files. (To open the runtime, please click on "!open_APiCS", and do not try to open the data file directly.)
More details on the process of downloading your questionnaire are given on the APiCS Database page.
When you first open the questionnaire, it should look structurally similar to the picture on the left (click on it to enlarge). Screenshots are taken from the Mac version of FileMaker Pro, but Windows users will recognize the elements.
If you are completely new to FileMaker and/or to APiCS, it may be best to start with the Guided Tour, accessible via the blue Help button in the top section.
Do not be confused if your screen displays more empty fields – it is a questionnaire, after all. The picture shows one into which some data has already been entered.
The white and light yellow fields await your input: While the white fields are for required information, input in the yellow fields is optional.
The light orange fields contain information provided by the editors. You cannot alter the content of these fields. If you want to make a comment on these fields, please leave the editors a comment in the separate "Questions/comments for editors" field. If you encounter a field where the content could not be fitted into the box in the layout, you can click on it to have it all displayed.
Please be aware that any changes that you make will take effect immediately, i.e.
- you do not need to save anything manually (unlike in the best-known word-processing programmes, there is no File > Save command), and
- it is recommended that you make regular backups of the file with which you are working.
Next to the fields for storing information, you find field labels (in grey colour) that summarize each field's function. If you place your mouse over the field labels for more than two seconds, you get more information on the nature of the field.
The blue elements are buttons that let you carry out some action ( go , view , add lect , Backup ! ). All of these are explained below.
Records and layouts
A record of the database consists of the information in all the fields in one database table. The total number of records in a given table is shown in the status bar on the left side of FileMaker's layout. The database contains four tables: the main table, the examples table, the references table, and the segments table. For each database table, there is a separate layout.
In order to fill out the whole questionnaire, you will have to switch between layouts. Some fields, however, appear in more than one layout. In these cases, information you have entered into a field in one layout will automatically be displayed in other layouts containing this field; you do not need to enter anything twice.
The central layout is the Main Layout depicted above, in which you enter your name, the language for which you are providing information and assign values (together with a level of confidence that your assignment is correct) to each of the 120 features, and indicate the source of the information. The Print Layout shows much the same content and should be used if you want to make a printout of the questionnaire. (If you want to make a printout of other layouts, e.g. the examples, please contact the editors.)
In the Examples Layout, you enter glossed examples from your language that illustrate the features and the values, and you indicate the type of the example together with a source from which the example is taken. Each example is a separate record, linked to the relevant feature and value.
The References Layout stores bibliographical information on the sources that you give for your data. As in the Examples Layout, each reference forms a separate record, linked to the relevant features and examples.
The Segments Layout is a separate questionnaire about phonological segments (i.e. phonemes) that occur in your language. We ask which of 96 phonological segments that are frequent in the world's languages occur in your language as well. For each segment there is a separate record. The IPA Chart Layout shows an overview of the segments in the form of a phoneme chart and thus provides easy access to the Segments Layout.
How do I…?
Data input starts with a click in the appropriate field. Most fields take text entry, so you will see a blinking cursor upon your click and can just start typing. In some fields your click will open a drop-down list from which you can select a value. For the Value Choice, you have to choose one of the two radio buttons "true" and "false".
switch between layouts
The easiest (and probably most convenient) way of switching to a different layout is by clicking on the corresponding blue buttons in the top part of the layout.
Alternatively, you can use the drop-down list under "Layout:" on the sidebar.
switch between records
To switch from one record to another, e.g. if you want to proceed to a different feature (in the Main Layout), use the navigation elements on the sidebar. Clicking on the right page of the booklet symbol will take you to the next record, clicking on the left page to the previous record. If you want to skip more than one record at a time, you can drag the slider below the booklet symbol to move through the database. The field under "Record:" displays the number of the record at the current slider position. In case you know the number of the record that you want to jump to, entering it into this field and pressing the Enter key will take you directly to that record.
search the questionnaire database
To search the database for some particular content of a field, you will need to switch to FileMaker’s Find Mode by clicking on the magnifying glass symbol on the sidebar, or by selecting View > Find Mode from the menu bar. You will then see an empty questionnaire form into which you can enter the search information. This may be either text that you entered yourself or text in the fields that the editors provided. Then click the Find button on the left (or simply press Enter). The programme will return to Browse Mode (the ordinary view in which you can view and enter data; pencil symbol) and display only those records that match your search criteria. The number of such records is then indicated under "Found:" on the sidebar. To view all records again, select Records > Show All Records from the menu bar (this is an important command that you should by all means remember).
A powerful tool for searching the database are so-called wildcards. These are special characters that serve as placeholders and allow you to search for unspecified elements. For example: Entering only an asterisk (*) into a text field in Find Mode will return all the records in which this field is filled with anything. Entering only an equals sign (=) will return all the records in which this field is (still) empty.
After you performed a search, the records are arranged in a different order, and the last line in the sidebar will say "Unsorted". To sort the records, ctrl-click (or click with right mouse button) the field by which you want to sort the records, and select Sort Ascending (or Sort Descending, depending on what you want to do) from the menu. (Alternatively, you can select Records > Sort Records from the menu bar and then specify a field by which the records should be sorted.) You will need the sorting function primarily to sort the records by the feature number, and to make this easier, we added a sort button to the right of the feature number field:
change the size of the window
Note also that FileMaker allows you to have several windows open simultaneously (e.g. if you want to see the Main Layout and the Example Layout on one screen). Select Window > New Window to do this.
The contributor-filled fields
Every APiCS contributor is asked to provide data on the 120 structural parameters ("features") that were selected by the editors, in the pidgin or creole language of their expertise. There are about 12 obligatory fields per feature, and you can enter more data into many further optional fields. Most importantly, you are asked to choose one (or more) values for each feature, and to provide at least one example for each feature.
First task: enter language name
Before you can do anything else, you have to choose the name of your language in the "Language name" field, and enter your name into the "Contributor name" field. Then click on set lang(uage) . This makes sure that each record that you work on is linked to the right language (the process may take several minutes). Read this if your language does not appear on the drop-down list.
The obligatory fields
With each value, you are requested to give information on the degree of reliability of the information ("confidence", with five values: very certain, certain, intermediate, uncertain, very uncertain). This allows you to provide also information that you are not totally sure of. You are also asked to provide a source for the information ("Feature Source"). This source may be "own knowledge" of the language, but it may also be written (published or unpublished) work on the language (by yourself or by someone else).
The optional fields
You may provide prose comments in a number of comments fields ( in light yellow ). These are explained here.
In the normal case, you should provide at least one example for each feature. If you select several values, then you should give at least as many examples as values. The examples are linked to the values, so if you select only one value and give only one example (probably the most frequent case), the example will be linked to this value. This means that in the Main Layout it will appear to the right of this value, in the same line.
The full examples appear in the Examples Layout, and on the Main Layout only the example number and the first few words of the primary-text field are shown.
To see the entire example related to a given value, click on the go button. When there is no example yet, the "go" button creates a new empty example record with a new (automatically generated) example number. The various example fields are explained in the Examples section.
The number in the orange field just to the left of the examples shows how many examples should be ideally given for the value in question. There is also a special field (Example request) above the examples that tells you more about the kinds of examples that are requested here.
For each feature, we ask you to provide a bibliographical reference, which simultaneously indicates the source of the information and directs the APiCS user to a place where further information could be found. This reference consists of Author-Year information and a page number. Since you will work with a fairly limited number of references, you can select the Author-Year combination from a drop-down list. To view the full reference corresponding to an Author-Year combination, click on go . To create a new reference record, click on go , and provide the required information on the new reference.
Alternatively, you may switch to the References Layout via the blue button and create a new record (Records > New Record) there. The References Layout is also handy if you need to modify a reference you already entered (e.g. to complete its bibliographical information).
Choosing a value
The most important part of the questionnaire is the choice of a value for every feature in the Main Layout.
In the simplest case, only one value may be chosen. For example, in feature no. 49 ("Tense-Aspect Systems"), four values are proposed:
- Purely aspectual (system)
- Purely temporal (system)
- Mixed aspectual-temporal (system)
These four values are exhaustive, and selecting several simultaneously would make no sense. The message above the value choice radio buttons therefore tells you: "Please select only one value". So here all you need to do is to select one of the three values by clicking the green Value Choice field next to it ("true"). For all the other values, the red "false" field is automatically chosen. The Relative importance fields are irrelevant. About half of all features are of this type.
If you want clear the value selection and start over, you can click on the button Clear true/false selections beneath the value choice fields.
In the other half of the features, you may select several values, because a given language may have several of the proposed possibilities. For example, feature No. 5 ("Order of Demonstrative and Noun") has the following six values:
- Demonstrative word precedes noun
- Demonstrative word follows noun
- Demonstrative prefix on noun
- Demonstrative suffix on noun
- Demonstrative simultaneously before and after noun
Here the message just above the value choice radio buttons tells you: "You may select several values".
If your language has just demonstrative words that always precede the noun (like English), then you select just one value, by clicking "true" for the first value, and "false" for all the others. (Choosing several values is never obligatory.)
However, some languages have flexible order of demonstrative and noun – sometimes the demonstrative word precedes, and sometimes it follows the noun. If your language is like this, then you should select "true" for both 1 and 2. Likewise, if different demonstratives in your language behave differently (say, 'this' preceding, and 'that' following the noun), choose "true" for both values, and "false" for the others.
The Relative importance fields
If you choose several values, then the Relative importance fields come into play, because the different possibilities may not be equally prominent in the language. For example, where word order is flexible, it may still be the case that one order occurs far more often than another order. And where different demonstratives behave differently, it may still be the case that the great majority of them precede, while only a single demonstrative follows the noun.
Determining Relative importance (in terms of frequency of occurrence in texts) in an objective way is of course not easy. When filling in these fields, it should always be borne in mind what its primary purpose is: To inform APiCS users about an imbalance between two possibilities that both occur in the language, but to quite different extents.
In the Main Layout, Relative importance is indicated in a rough way using the following categories:
pervasive (90%) majority (70%) about half (50%) minority (30%) marginal (10%)
Since the Relative importance has to be comparable across languages and features, we will need to translate the verbal descriptions into percentage figures (given in parentheses above). Of course, APiCS users will be aware that these figures are very rough, and that the APiCS authors cannot be held responsible for them. All we ask of you is to give your impressions of the Relative importance, i.e. it is explicitly recognized that this information is impressionistic. We feel that it would not serve the field well to ignore such impressionistic information in the APiCS database, because we do not ignore it in other contexts either (impressionistic statements of relative importance are made in grammatical descriptions all the time, and readers normally find them very useful).
If you happen to have more precise information (e.g. frequency information from a corpus), or your impressionistic judgements permit more fine-grained distinctions, you may switch to a slightly different version of the Main Layout, using the numeric button. This shows you the same information, except that Relative importance is indicated by numeric percentages. There are two percentage fields for each value, a white and an orange field. You may fill in only the white field. The grey field shows the percentage that is eventually recorded for the APiCS database, and it is taken either from the verbal descriptions, using the correspondences shown above (if you do not make use of the numeric layout), or from what you enter into the white percentage fields (the latter takes precedence).
Note that it is not necessary that the percentages add up to exactly 100. We will eventually adjust the figures. Thus, if you say for a feature that three values are "true", two occurring "pervasively" (=90%) and one "marginally" (=10%), the eventual percentages will be 47 (= 90/[90+90+10]), 47 (= 90/[90+90+10]), and 5 (=10/[90+90+10]).
Commenting on a feature
On the right-hand side of the Main Layout, there are three comments fields for each feature. The most important field ("General comments on value assignment") is for comments that are intended for the APiCS users. This should be formulated explicitly (without assuming too much contextual knowledge), without cross-references to feature numbers and without abbreviations, and eventually it will have to be carefully edited (no typos etc.). The other comments fields are internal to the project and may have typos and all sorts of other imperfections.
The field "Questions/comments for editors" is intended only for the editors. During the review process following the submission of your finished database later in 2008, the editors will carefully read all the comments/questions and answer them, so that at the revision stage you will have a better basis for preparing the final version of the questionnaire.
The third comments field, "Comments (private)", for notes written by you for yourself or for your assistant, concerning the nature of the data entry process (e.g. "Need to check with informant", etc.). The content of this field will not be read by the editors.
If you cannot give a value for a given feature, please specify one of the reasons for missing information in the field "Select if no information available". If the language is extinct and the information is unobtainable because of the limited corpus, select "information unobtainable". If the information could in principle be obtained but you happen not to have it, select "information lacking". (This is acceptable as long as not more than a handful of features are affected.)
In the normal case, you should provide information on a single, reasonably homogeneous variety (= lect) of your language, consistently for all the features (this is called "my default lect").
However, in some exceptional cases, you may want to provide information on more than one lect, e.g. if you happen to know that for one feature the older generation uses a different construction, or rural speakers differ from urban speakers, etc.
If you want to give information on two different lects systematically for all features, you should provide several complete questionnaires – which we'll be very happy to accept! – but of course we don't expect this.
What you need to do if you want to give information on another lect is to duplicate the record for the feature by clicking on the add lect button in the lower right corner of the Main Layout. This creates a new empty record for the current feature, which you can then fill in in the usual way. Please specify the kind of lect in the field "Lect" below the button. The lect that you normally describe is called "my default lect". The additional lect can be given any name (the names "written" and "older generation" are just examples). The drop-down menu is editable and you can add any number of further lect names to it.
You can add as many lects as you wish for each feature. These are listed in the box below the Lect field, and you can switch between them by clicking on the view button to the right of the current lect name. An arrow symbol on red background indicates the lect that you are currently viewing. (You can use the "Lect count" field to search for all features for which you have entered multiple lects, by putting ">1" into it in find mode.)
(Please note that new records are always appended to the end of the data set, so in order to return to the record that you started out from, you may have to switch several records back. Alternatively, just search for the record you desire.)
For each example there are nine fields, of which six are normally obligatory: (i) The Primary text field, (ii) the Gloss field (which gives a word-by-word gloss, or a morpheme-by-morpheme gloss), (iii) the Translation field, (iv) the Example Type field, which gives information on whether the example is elicited, spoken, written, etc., (v-vi) two Example source fields (Author-Year and page information). In addition, there is an optional field for an analyzed version of the text an optional field for a translation into a language other than English, and an optional field for any kinds of comments.
- The Primary text field contains the example text, as it would be written in any grammatical description, or as it was written in the example source. The transcription should follow the usual conventions for the language (standard spelling, or most widely used spelling, or most widely used transcription among linguists), or if you have good reasons for choosing a less widespread transcription, you may use this as well. Phonetic transcription is not necessary, not even for the phonological features. The most important part of the example may be highlighted by boldface.
- For many of the features, the example will not be a complete sentence, but just a phrase or a single word. For very short examples consisting of a single word (e.g. a pronoun), it is possible to put several examples in a single example record, separated by semicolons.
- The optional Analyzed text field may contain a version of the example text with morphemes separated by hyphens, thus allowing a morpheme-by-morpheme translation in the Gloss field. This field can also be used for a different orthographic representation of the text in the Primary text field.
- The Gloss field contains a word-by-word or morpheme-by-morpheme translation of the example text. Spaces and hyphens should match exactly between the gloss and the text. If there is both a primary and an analyzed text, the match must be between the analyzed text and the gloss. (When the example is a single word, the Gloss field is of course redundant, but please fill it in anyway, for consistency.)
- Please use CAPITALS (not small capitals) for morpheme abbreviations such as FUT or PROG. A list of standard abbreviations is included in the Leipzig Glossing Rules (included in the questionnaire file under "Help"; also available online). These conventions should also be observed with regard to morpheme break issues.
- The Translation field contains an idiomatic translation into English. It may sometimes be useful to give a translation into the main contact language as well. The optional Other translation field is intended for such translations into another language (another possibility would be a translation into the main lexifier language, which may be useful for comparison).
- In the Example type field, we ask you to specify whether the example was (i) elicited from a speaker, was taken from a naturalistic (ii) spoken or (iii) written text, or (iv) was constructed by a linguist. (Since there may be more possibilities that we did not think of, the value list is editable, i.e. you can add more values.)
- In the optional Comments field, you can enter any kind of comments on the example. You can also link an audio file to each example. Please click on the blue button Link audio file and follow the instructions. The audio files are stored in the "audio" folder that comes with your questionnaire. (note on audio files)
- Finally, the two Example source fields should be filled by information on the source. If this is a written work, you should fill in the Author-Year field (e.g. "Keesing 1988") and give page numbers in the Pages field. If the source is your own knowledge of the language, select "own knowledge". If the example is from a personal communication, write "María González, p.c." (or similar). If the example is from your unpublished materials, you may describe these materials in some way and treat them as bibliographic entities of some sort, or alternatively simply write "own data, own materials, etc." The conventions are thus very similar to those concerning the feature source. But it is important to keep the two separate: The general feature source gives the source of the value assignment, while the example source give the sources of the example (recall that an example can be used for multiple features).
If you make use of special characters, it is essential that you use Unicode encoding. Three widely used special-character fonts with Unicode encoding are Arial Unicode (which is part of Microsoft's Office package and is therefore available on many computers), Lucida Grande (widespread on Macs), and SIL Charis (available for free from SIL International's website). The Example Layout contains three character pads that allow you to easily enter some of the most widely used special characters.
In the lower right part of the Example Layout, you see an "Incomplete fields" box that lists all the obligatory example fields that are not filled yet. When all are filled, you get the message "Complete!".
Finally, note that the example numbers are generated automatically and cannot be modified. If you generate an example but delete it later, there will be a "hole" in your numbered list of examples. This should not worry you, as the numbers only serve the purpose of identification. They are not the final numbers for the published version (so please do not refer to these numbers in the comments fields).
In the Main Layout, too, there is an "Incomplete fields" box that that lists all the obligatory fields that are not filled yet. When all are filled, you get the message "Complete!". (Of course, you can still add more information to complete records, e.g. add more examples or fill the optional fields.) Sometimes the incomplete fields do not disappear from the box immediately after you fill the relevant field, but only after you click somewhere else.
When you click on Progress report , you get a list of all feature records showing just the feature number, feature name and incomplete fields. This gives you an overview of what you still have to do.
Data on phonological segments
In addition to the 120 main features (which include a few phonological features, but no segmental features), we ask you to provide information on the phonological segments (or phonemes) of your language. Since the segment inventory of a language is fairly limited, we thought it was not asking too much to request a complete list of all segments. This list should be entered into the Segments Layout, which is best accessed via the IPA Chart Layout. This is very large, so it has a number of navigation buttons, such as zoom in/out , move down , move to top right .
Each of the segments shown on the IPA Chart Layout corresponds to a record in the Segments Layout. Clicking on a segment sends you to the corresponding record, where you say whether the segment exists in the language (as a major allophone, only as a minor allophone, only in loanwords, or not at all), and where you are asked to give one example word (with gloss). You can also make a comment and link an audio file of the example word.
At the beginning, all segments appear in white, and once you provide information about their presence in the language, they change their colour. If you start with the segments that exist in your language, you can finally click on set all Unspecified to Does not exist to say for all the others that they don't exist, without having to go to each segment record separately. You are done when no unspecified (=white) segments are left on the IPA Chart.
If your language has segments that do not appear on the chart, you can add new segments by clicking on one of the white custom fields (bottom left) and filling in the segment feature information (especially segment name and segment symbol). Note that our segments chart does not contain diphthongs and affricates, so these will have to be added as custom segments.
Help and sample data
The Help pages
The upper right corner of each layout contains a Help and a Backup ! button. The Backup button allows you to export all your data to a text file (reimporting will require help from the editors). It is advisable to do this periodically, in addition to maing backups of the entire file.
The Help pages contain four items:
- the Guided Tour (for absolute beginners)
- a version of these Guidelines (so you don't have to open another file to read them)
- the Glossary (which gives further explanations of important grammatical terms that occur repeatedly in the feature annotation texts)
- the Leipzig Glossing Rules (for the morpheme-by-morpheme glosses)
Editor's e-mail and WALS No.
In the top right corner, you find the e-mail of the editor in charge of the current feature. Feel free to ask us if anything is unclear.
The field "WALS No." tells you the corresponding feature in the World Atlas of Language Structures, if there is one. For features that are identical to WALS features, the feature description in WALS is often even more detailed than our feature annotation, so it may make sense for you to consult WALS (at www.wals.info). If the corresponding WALS number is in parentheses, this means that the APiCS feature is similar to a WALS feature, but the feature values are different.
The sample data
The folder that you download contains not only the file which you fill with your data, but also three sample data sets for the data in the Main Layout (Seychelles Creole, Principense, and Batavia Creole). This gives you a concrete model for filling in the questionnaire. When you click on one of the three buttons Batavia , Seychelles or Principense , a new file ("sample_data") opens, showing the same feature that you were looking at before. You can switch between the model data sets by clicking on the buttons. When you click on My file , you are sent back to the data file ("APiCS_data") into which you are entering the data.
A technical note for this manual
Text in this typeface refers to a command you can access through the menu bar at the top of the screen. So, File > Print…, for instance, would mean: Click on the File menu, then select the Print… command.
Creating a new language record
If your language is not on the drop-down list (or if you want the name of your language to appear in a different form), you need to create a new language record. You do this by browsing to the Languages Layout (in the drop-down list on the side-bar, cf. this section) and creating a new language record (select Records > New Record to do this). In this record, fill in the "Language name" field. Then go back to the Main Layout, select your language from the drop-down list (to which your language has now been added), and click on set lang(uage) .
→ see Sending audio files
Please note that you have to copy audio files into the "audio" folder manually before linking it to your example. Use formats like MP3 to keep the file size little. If you submit any audio files, please remember to send them to us as well (e.g. by making a ZIP archive of the audio folder) because they are not stored in the database.