Documentation Tab

The Documentation tab causes the documentation fields to appear in the window of the CAPI Designer. This tab is typically used in the Documentation phase after data collection, but before data dissemination to public users. It is, however, not limited to that phase. In the case of Select All, Date, and Matrix question types, where after data collection, additional questions and variables are generated to document the codebook, Web Investigator, user guides, this tab can used to 'customize' these generated records.

As opposed to the Design tab, that describes a question's fields in the design phase before data collection, the documentation phase causes the documentation fields to appear in the window of the CAPI Designer. The documentation fields have nothing to do with running the survey, but are used by post-data collection programs to make a codebook, Web Investigator variable, and user guide files that are to be released to the public.

Documentation Fields
The two fields at the top of the table below and shown in parentheses ( ), "question name" and "question text", are for identification and display only and cannot be edited from this screen. The table below list and describes the other fields that can be edited in this mode. At the very bottom of this window is a sample documentation screen.

Document Tab fieldsDescription
(Question Name) Non-editable field from this screen
(Question Text) Non-editable field from this screen
Title Formerly, keyword in context (kwic) title -- up to 100 character long. Used by the Codebook and Investigator software
Short Title Variables labels for the SAS/SPXX jobs that can be created in the Investigator
Report FlagsContains a string of text that tells the documentation programs to ignore certain "errors" for this variable. Presently, the only options that appear here are:
  • "FREQCHECK:NO_DATA_OKAY", which suppresses this variable from showing up because it has no data, and
  • "DISPLAY_NO_FREQS", which suppresses this variable from showing up as an error because it is numeric and has no range.

    • Other options are possible. This field is meant to be flexible, so if archivists decide they've checked out a certain problem and want to mark the variable as "okay", an appropriate phrase can be decided on, implemented, and used without changing the Designer at all.

    Document checkboxTells the post-processing software if the archivist wants this variable to be included in the Codebook documentation.
    Security Tells the post-processing software if the archivist considers this question 'private', for internal Investigator use only; or 'public', which gets published on the CD ROM.
    Investigator Allows the archivist and/or survey designer to limit the number of non-necessary variables (e.g., intermediate variables used to calculate a final variable's value) displayed in the Web Investigator to a more manageable number. The archivist/designer can toggle a variable's display to 'Hide' it in the Investigator. Default is 'Show'. See the window below. In the Web Investigator a user has the opportunity to toggle the hidden variables back to display.
    Ref Number The reference number, or rnum, that may or may not be filled in. In most cases, the archivists allow the documentation programs to assign these numbers, but sometimes archivists will assign a few of these numbers by hand.
    PAPI QName The old paper and pencil question name which, if it exists, is used in the codebook in place of the question name.
    Pick A drop-down menu that contains the names of pick lists that appear for the appropriate question types and from which the archivist/designer can select a different pick list than the one chosen in the Design phase. The choice this field offers means the Documentation pick list may be somewhat different from the one used by the survey program. This choice is useful in a longitudinal sense when new response categories are added to Documentation pick lists due to 'coded items'. A 'coded item' results from choosing the 'other specify' option frequently for the same question, and then specifying the same response repeatedly. In version 2.1.11 and subsequent, if the pick list is the same for the Design and Documentation modes, this field will display (SAME_AS_DESIGN_PICK). See the window below.
    Year The survey year in which this question appears.
    Max Doc Loops This field should contain an integer and should only appear on the STARTING question of a loop (the REPEAT question, or one of the new loop control functions). This integer causes the documentation programs to only document loops 1 through the number. If the archivist decides that only 25 household members should be documented the a '25" in this field to control would limit the loop to that number.
    Comment A field to contain an archivist's comment that would appear in the codebook.
    Areas of Interest An index of 'topical subjects' used by the Investigator software to group variables of like-interest.
    User Guides Textual phrases used by the Web Investigator software to form hyperlinks among variables, questions, and documentation in the User Guide(s), Codebook, and Web Investigator.

    Sample of Documentation fields under the Documentation tab