[Top] -- HTML Documentation Table of Contents -- Catalog Division Home Page

HTML Technical Documentation

Standards for Princeton University's Cataloging Documentation

The goal of the computerized version of Princeton University Library's Cataloging Documentation is to utilize the advantages of the computer system while being fully aware of its disadvantages. At the same time, we want to acknowledge the positive and negative points of the paper documentation.

Comparison of Paper and Computerized Documents

Advantages
P
A
P
E
R		 Easy to read (reflected light).
Therecan be a great deal of information printed on a single page. This allows for good general overviews.
Staffcan add their own information and examples.
Staffalways know precisely where they are in the documentation (they cannot get "lost").
Staffis used to reading documentation on paper.		 They are very easy to update.
Thesame document can be viewed by everyone simultaneously.
Withhypertext links, any see references are very easy to find.
Imagesare very easy to make.		C
O
M
P
U
T
E
R
Disadvantages
P
A
P
E
R		 Hardto update. Readers often don't know if they are looking at the latest information.
Moreexamples increase the bulk of the documentation, which makes it more imposing.
Referringto related documentation can be bothersome, so there is a certain amount of duplication of information which is covered more fully in other places. When this information changes, it can be very complex to change it everywhere.
Tofind a specific answer to a specific question, the only way to find the information is to memorize where the answer may be in the documentation, ask someone else, or as a last resort, search through everything.
Informationon some topics is scattered throughout the documentation (e.g. CAS)
 Itis harder to read a computer screen than a piece of paper (directed light).
Thereis not much space available on a single computer screen as compared with a piece of paper. Scanning a long file by scrolling down a computer screen can be confusing. With big files, it is very easy to get "lost".
Onlythe system administrator can update the documentation.
Informationin the computer can be exceptionally difficult to find.
Thesystem can crash.		C
O
M
P
U
T
E
R

Purpose of
Princeton's Cataloging Documentation		     Based on a review of the above considerations, it becomes clear that the undoubted advantages of paper become disadvantages when translated into computer documents without revision. For the online documentation to be successful, it must solve the following problems.
  1. The difficulty of reading computer screens.
  2. The problem of finding information buried inside long documents.
  3. Getting lost in the documentation.
  4. The online documentation must be easy to use.
  5. It must be easy to find information in the online documentation.     We have also noted that staff rarely read a procedure from beginning to end. Much more often they consult it to find a small part of the entire procedure. For example, if catalogers are having trouble with a reference for a personal name series, they do not normally begin by reading in depth from page 1, The Definition of a Series.

        To deal with these problems, Princeton's on-line documentation has followed a set of standards (each will be discussed more thoroughly below).

Overview of Standards
  1. Break the documentation into separate topics, each topic written in an independent manner and clearly labelled as to content.
  2. Use of a standardized display so that staff members cannot get lost.
  3. The liberal use of hypertext links to bring similar topics together. The purpose of each link to be clearly explained.
  4. Two types of tables of contents. One type is a normal table of contents which brings similar topics together. The second type provides an intellectual overview of a procedure which gives general information and any explanation of further links.
  5. The creation of an alphabetized index to provide quick access to individual topics when a general overview is not desired. The general overview is always available with a single click, however.
  6. Whenever a staff member requests a link or addition, it can be added easily.
This illustrates how the documentation is created.
Individual
Topics		     Each procedure is broken into separate files. Each file comprises a single topic. The purpose of this is to have a complete and consistent index (discussed below), while allowing staff members to always know where they are in the documentation.
Example     Here is an illustration. Staff members should be assured that when they search the Index, they are searching the entire documentation for that information.
     For this example, all the information for the Notes fields in the Cataloging with Copy section has been combined into a single file. Included are the fields 502, 504, 505, 534 and 590.
    To index the information concerning the 534 Field, there are three choices:
    1. Link to the top of the file.
          This is confusing because the staff member wanted 534, but got 502. He needs to scroll down into the document to find the information.
    2. Link inside the file.
          This is also confusing, since the staff member is now lost in the documentation. He needs to scroll to the top of the file to discover he is in Princeton's Documentation, Cataloging with Copy, with the added links of the hierarchy.
    3. The only other possibility is not to index the information, but in this case, the staff member must memorize the place in the documentation for the information, just as in the paper documentation.

Illustration of the Problem of Indexing

    The solution is to keep a single file for a single topic, and link only to the top of the file. This way, the index point is clear, users know exactly where they are, and any links to further information is immediately available.
Example
    To find the information on Series in the Retrospective Conversion Procedures:
Determining a
Single Topic		Two questions should be considered when determining what constitutes a single topic:
  1. Would someone wish to get directly to the information?
        Referring to the example above, it was determined that someone would want to read information about the 534 field without dealing with the other 500 fields.
  2. Does it help to make the index complete?
        If you find that there are are index points related to your topic, and that, in order to make the index complete, you would have to make an internal link, you should seriously consider making a separate topic.     In the document labelled NOTIS Searching, there are topics: Comparison of search indexes, Searching hints, Search commands and displays. These should be revised and considered as separate topics.
        See: NOTIS Searching
Writing Style Since a link may be made to any document from any other document, each topic should be written independently of the others.

    Here is a very simple example from the Copy Cataloging Manual.
Readers of paper documentation automatically know what section they are reading since they are physically holding it. This can no longer be taken for granted, and in this example, the information was slightly revised.

Repeating Information The necessity for repeating certain information (mentioned above) is avoided. Rather, all that is needed is a link to the desired documentation. As a result, when something changes, it affects only a single document.
Example    Here is an example concerning our guidelines for determining whether an item is an edition or a printing. There are links from both the Descriptive Cataloging Manual, and the Cataloging with Copy Manual.

Display If staff members are not to get lost in the documentation, and understand everything readily, there should be a standardized display for each file.

Top & Bottom    At the top of every file is a link to the Main Page: (these links do not work)
    [Top]
    followed by the Section Table of Contents (if any)
    [Slavic Cataloging Table of Contents]
    and to any other tables of contents (if any)
    [Personal Names Table of Contents]
These links are repeated at the bottoms of each file.
    The purpose is twofold: one, for ease of navigation, and second, so that the staff members know when they come to the end of the topic.

Hierarchy Each topic has the name of its hierarchy: The section and subsection names, plus it is given a unique title to distinguish it from all other topics. This makes the subject of the topic clear to staff members and additionally, eases the task of creating the Index entries.

     Also, as we link into new documentation, either on the Internet, or locally (Cataloger's Desktop, or LC Classification Schedules), it is important that staff members know they are in our local documentation. To assure this, a standardized image appears at the top of every file.

Readability To make the information on the monitor's screen more easily readable, more care should be given to typography. There should be more use of white space, bold, larger typefonts, etc.

Links Links are the most important part of the documentation. They are used to bring related information together and have a variety of labels: See, See also, Continue with, etc.

    All links leading to a topic go to the top of the document so that the staff members can always see the hierarchy mentioned above. Links that go into the middle of a document result in staff members being lost.

    With very few exceptions, there are no internal links. They are unnecessary since each file contains a single topic.

    The reason for any link should be clearly indicated. Links are not made from individual words selected from a sentence. e.g. in Cataloging and Verifying LC Copy, Artists and Architects, there is the sentence: (this link does not work)

Example
    Cutter numbers:
    • If the artist is the main entry (100 field), the second cutter will be for the first of the 7xx fields.
    • If the artist is not the main entry, cutter for the main entry.

    Do not simply make a link to the Cutter Table from the words Cutter numbers. Such a link is confusing. Does it go to a description of the Cutter numbers? Or to a Cutter table? Or perhaps to a biography of Charles Cutter?

Make an explicit reference.

    Cutter numbers:
    • If the artist is the main entry (100 field), the second cutter will be for the first of the 7xx fields.
    • If the artist is not the main entry, cutter for the main entry.
        See: Cutter Table

Tables of
Contents		 Tables of Contents allow for a classified arrangement of the separate topics.

In the Documentation, there are two main types of Tables of Contents.

Normal
Procedural
Outlines
  • Tables of Contents for Procedures
         These Tables of Contents provide an intellectual overview for an individual procedure. In this type of Table of Contents, there is an overview of the procedure and general information that would otherwise be lost, and any necessary explanation for further links.
    See as an example:

Index The Index allows for a complete alphabetic arrangement of the separate topics.
Purpose and Goal    The purpose of the Index is to allow a staff member to very quickly find all information on any given topic. An ultimate goal of the Index is, if there is nothing in the Index, it can be assumed that there is nothing on that topic in the Documentation.

Key to the Documentation The Index is the key to the documentation. Without it, the individual topics can easily be lost.

    The Index is made by taking the unique name of each topic, modifying it if necessary, and putting it in alphabetic order. Any permuted entries are made based on important keywords in the topic's title.

    If the arrangment of a separate Table of Contents would be reproduced in the Index, it is not made. A single reference to the Table of Contents is all that is required.
     For example, the Series Manual Table of Contents has many documents beginning with the word Series, and would merely be reproduced in the Index.

6. Maintenance Whenever a staff member requests a link from one file to another, it is made automatically. The assumption is, if one person wants a link, others will eventually need it, too.

Added Considerations
  1. Since the complexity and bulk of a procedure is hidden from view, as opposed to paper documents, the number of examples and specific rules can grow without being so imposing.

  2. With the emphasis on one topic per file, staff members can bookmark those parts they find most useful, and thus retain the individual control mentioned above.

  3. There is no need to memorize where something exists in the documentation. Searching the Tables of Contents, or the Index is sufficient for anyone to find topics immediately. For example, where are the guidelines for barcoding unbound volumes? It is now easy for anyone to find.

  4. All updates are immediate and available to everyone.

  5. By finding one piece of information on a topic, staff will find links to all information on that topic.

  6. It provides information more efficiently by helping staff spend the least amount of time searching the documentation for the desired information.

  7. Staff are encouraged to add their own examples and information to the documentation so everyone can benefit.
[Top] -- HTML Documentation Table of Contents -- Catalog Division Home Page