owner=rezac@ukanaix.cc.ukans.edu (Charles Rezac)
link_delimiter=<


           The University of Kansas Academic Computing Services
                  
               Guidelines for Authoring KUFACTS Documents


    The need to make information publicly available is a driving force
    behind the development of campus-wide information systems (CWISs).
    KUFACTS, the University of Kansas' CWIS, is information stored on a
    variety of computers and maintained by people in many departments.
    There is a software component in the system, but the information
    itself is the key feature of the system and will ultimately
    determine whether the system succeeds or fails.  To succeed, a CWIS
    must provide information that is accurate, relevant, current, and
    interesting.  Given fantastic software with all the bells and whistles
    one could ask for, a CWIS will still fail if it provides no
    information of value to its intended audience.

    The full features of Lynx, the software supporting KUFACTS, are
    outlined in other documents and will not be addressed in detail here.
    Rather, this document is intended to provide guidelines for the
    selection of information to be included in the CWIS, the addition
    of information to the system, and the maintenance of that information
    after it has been included.  The format and development of Lynx
    documents is discussed in more detail in the ACS technical write-up
    <units/acs/General/lynx_user_guide:42>Introduction to the Lynx Hypertext Browser.  Anyone who will be
    adding information to KUFACTS should read <units/acs/General/lynx_user_guide:42>Introduction to the Lynx
    <units/acs/General/lynx_user_guide:17>Hypertext Browser thoroughly.  The document is accessible through
    KUFACTS; hardcopy is available at the consulting window.

    We will begin by reviewing what information is and the forms it
    may take on the CWIS.  Existing and suggested areas of
    responsibility will then be addressed, and suggestions for future
    expansion detailed. After a discussion of the information various
    departments might contribute to the CWIS, guidelines for
    preparing the system's "information components" will be outlined
    and basic standards will be proposed.

INFORMATION

    Information is a record of meaningful observations.  It may be
    data which someone has both collected and processed or a
    photograph of a meaningful event.  Information has content,
    value, and significance which depend upon the data from which it
    was derived, the methodology used to collect it, and its meaning
    both to the person making the original observation and anyone
    exposed to the information rather than the data.

    To clarify, a picture of a broken window is data.  When used,
    whether by lawyers in a civil suit, a security firm for
    advertising purposes, or the Enquirer to illustrate an article on 
    famous poltergists, it becomes information; if put on a CWIS it may
    become information as well, but not necessarily worthwhile
    information.  When preparing documents for inclusion in KUFACTS
    remember that the information should have content, significance,
    and value within the context of a campus information system.

    The information available on CWIS's takes a variety of forms.  The
    following sections summarize each of the forms KUFACTS may
    support.  Text and executables are currently supported and are
    addressed first.  Binary formats such as graphics and sound are
    also discussed even though this method of information encoding is
    not currently supported; sound, picture, and animation support are
    all proposed extensions to KUFACTS.

Text

    At the present time, the majority of the information available is
    provided in the form of text files.  Text files will continue to
    be the primary method of information storage.  There are several
    reasons for this.  Text files are the simplest documents to
    prepare and to process.  Formatting and display options are more
    limited in a text file, but the time required to prepare
    information for KUFACTS is much less than is required for other
    types of information preparation.  Additionally, the file can be
    displayed quickly and easily on any system; special processing to
    handle fonts or other formatting features is not necessary.

    At some point a more complex document format will probably become
    a standard; however, anyone making the decision to abandon basic
    text files should keep in mind the variety of platforms on which
    the information is to be stored and displayed.  The standard
    format should always require minimal processing when being
    displayed, be an efficient method of storing most data, and be
    easily prepared and maintained.

Executables

    Executables are programs which have been compiled to run on a
    specific machine.  While the information in a CWIS is generally
    considered to be documents, there is no reason that programs
    cannot be included as part of the system.  These programs can be
    linked into the structure of KUFACTS and accessed like any other
    information stored in the system.  The Calendar of Events function
    is actually a program which allows a user to select a subset of
    the available information and present it in the form of a
    customized document.  In effect, Events is a simple database
    reporting tool.  There are several advantages to such an approach.

    "Customized documents"  simplify the process of making database
    information available.  Rather than having to extract information
    from productional databases on a routine basis, the information
    provider can provide direct access to the information with a
    custom executable serving as a search agent, buffering the novice
    user from the database.  Additionally, because the user has
    control over the data being displayed, the process of finding
    relevant information is simplified.

    However, adding executables, while simpler for the user, is more
    difficult for the information provider.  It requires more testing
    than adding text.  Adding poorly structured text to the system may
    cause the information to be displayed in an awkward manner or
    make it unreadable, but it won't cause the system to crash.
    However, if the executable being added is not well written, it may
    adversely impact system performance or interfere with the existing
    software components of KUFACTS.  When writing a program for use
    with KUFACTS a programmer should try to implement the Lynx client
    software's manner of using the keyboard and displaying information
    so that a consistent "look-and-feel" is achieved.  The most
    important factor is to make sure that, when the program is exited,
    control is returned to the CWIS and not the host operating
    system.

    Currently the CWIS includes executables to provide telnet
    connections to remote information services, and to provide
    customized documents.  Customized documents use a database engine
    to retrieve selected data, e.g., the home football games, rather
    than all of the events on the calendar.  The concept of the
    customized document is one with many possible applications.

Graphics

    Graphic information includes pictures, maps, charts, and diagrams;
    specially formatted text can also be considered graphic
    information.  Graphics are not supported by all of the currently
    available CWIS clients.  This is primarily because not all
    hardware will support the display of graphics information.  An X
    Window System client is planned and additional clients that will
    support graphics are under development for some personal
    computers.

Sound

    Digitized sound is only supported on personal computers and
    workstations with special hardware.  While most terminals have a
    speaker, they aren't capable of being programmed to make any
    noise, except possibly an attention getting beep.  Such a signal
    is fine for alerting someone to the fact that something has gone
    wrong.  However, in a CWIS environment, the bell is not capable
    of conveying much information and, if overused, can become very
    annoying.

    The quality of the support hardware will determine the quality of
    the reproduced sound.  In general, sound is probably a poor method
    of storing data on a CWIS.  The data is not very portable,
    requires relatively large amounts of disk space for storage, and
    adds little to the understanding of most topics.  Finally, sound
    can be very distracting in offices, labs, and other shared
    environment workspaces.  Digitized sound is a format that will be
    supported on clients in future releases, but it is not a high
    priority item.

Animation

    Animation is a proposed extension to CWIS client software.
    However, because graphics are required before animation can be
    supported, animation is low priority at this point.  Eventually it
    may prove useful for on-line tutorials, building information,
    kiosk-type applications and other functions.  If you have
    information that requires animation, please discuss your needs
    with the CWIS development team.

Providers

    For our purposes an information provider is anyone who has
    information to share with a significant portion of the university
    community.  At minimum, the university community consists of the
    students, faculty, and staff of the university.  While the term
    "university community" is almost as vague as "significant," rigid
    control is not normally consistent with a goal of sharing
    information; currently, anyone who has a computer account or a
    microcomputer that can be set up as a server  may become a
    provider.  As the system evolves, a more stringent definition of
    who the information providers are may develop.

    The following list attempts to identify some of the information
    that could be made available on the CWIS and suggests departments
    with a potential interest in making the data available.  This list
    is not intended as an assignment of responsibility.  Rather, it is
    intended to give an idea of the possible breadth and scope of the
    CWIS.  It may also stimulate thought and discussion about
    additional information that could be added or departments that
    could be involved.

University Departments

    Admissions

    Because KUFACTS is accessible from any university with an Internet
    connection, recruiting and promotional information, admissions
    requirements and timetable information could be made available
    on-line to students at other schools as well as to those enrolled
    here.

Computing Services

    Academic Computing Services provides hardcopy documentation on a
    variety of mainframe and microcomputer topics.  Making these
    available on-line improves access and reduces copying costs.  Two
    publications are currently produced by ACS which are being made
    available on the CWIS.  One of these is scheduled to be partially
    published on the CWIS, i.e., the text will appear on KUFACTS, the
    printed copy will contain only abstracts of the individual
    articles.

KU Info

    The Information Center has access to a wealth of information for
    the asking.  If this information were available on-line it would
    be available for the browsing -- increasing access to the
    information and freeing staff time for dealing with patrons
    requiring personal interaction.

Libraries

    The Libraries could make available information on holdings and
    resources not covered in the on-line catalog and provide an easier
    access method to OCAT for off-campus users.  Holdings records
    could be linked with the names of staff responsible for
    maintaining the material, the faculty member who wrote the book
    being referenced, or reviews of the material in other library
    holdings.  Other information maintained by the library, e.g., the
    translator file, could also be made available on the CWIS.

Museums

    Discussions of the collections and current exhibits could be made
    available on-line.  Hypertext links could reference items such as
    courses in the catalog dealing with a particular style of painting
    or geological era, comments of previous visitors to the museum, or
    related faculty or University Press publications.

Personnel

    Information currently placed on Dial-A-Job could also be placed
    on-line.  Unclassified listings, which do not appear on
    Dial-A-Job, could also be made available on the CWIS.  Other
    materials Personnel might wish to maintain include the classified
    and unclassified employee handbooks, health and safety
    information, and schedules of staff development events and
    activities.

Placement Center

    Student interview schedules and position descriptions as well as
    job fair information, guidelines for resume preparation, and
    documents discussing interviewing techniques could be made
    available by the Placement Center.

Purchasing

    Many departments would find it helpful to have  State Contract
    information available on-line.  They could be sure of having the
    most current and complete information if Purchasing were willing
    to keep these files updated.

University Relations

    Almost everything this department is involved in publishing
    (except for the programs for events like Commencement) would be
    valuable CWIS resources.  Included in this list are such items as
    university calendars, course catalogs for the various schools,
    newsletters and papers, the Research Index, and the campus
    telephone directory.

Academic Departments

    Individual faculty members could make copies of scholarly articles
    or presented papers available and could, if desired, provide
    electronic copies of a syllabus and a required reading list when
    the timetable is published.  In fact, many classic works of
    literature are available as electronic resources.  Courses in
    Shakespeare, Dickens and Western civilization might be able to
    make the texts for a class, and not just the reading list,
    available on-line.  Additionally, fiction writing and poetry
    classes could publish their work on-line and get feedback from a
    much larger audience.

    Minutes of meetings such as the College Assembly could be provided
    and office hours for all faculty and GTAs could be posted
    electronically.  If there were special projects or research in
    which they wanted to stimulate discussion or interest, faculty
    could make pertinent information available on the CWIS.  Academic
    clubs and organizations such as the German Club could publish
    information about their activities.  Academic departments have
    much to contribute to KUFACTS; however, its overall impact on
    instruction cannot be determined at this time.

Students

    When students are given permission to add information, their
    additions to the CWIS would probably be along the same lines as
    that of faculty: organizations with which they are involved and
    special interests.  Authorization to add information to the CWIS
    will probably be granted to students by a member of the faculty,
    an academic advisor or an organizational advisor; this is the
    current requirement for students wanting mainframe access.
    Determining whether the information the students will publish is
    appropriate is the responsibility of the individual authorizing
    access.

    There are a number or student organizations currently publishing
    newsletters, schedules and similar information who could serve as
    information providers.  These include but are not limited to ASK,
    the student lobbying group; AURH and ASHC, the residence hall
    and scholarship hall governing bodies; the Board of Class
    Officers; the Graduate Student Council; Student Senate; the
    sororities and the social and professional fraternities.

Integrating Information -- Standards and Procedures

Adding Information

    Before the information is added, the potential information
    provider must make several decisions.  The first is obviously
    whether or not the information is appropriate to add to the CWIS.
    Information which 1) is not copyrighted or is being added with the
    permission of the copyright holder, 2) doesn't violate any
    University guidelines governing acceptable publication, 3)
    contributes to the educational or research mission of the
    university, and 4) is useful to more than one person at KU may be
    added to the CWIS.

    Commercial use of KUFACTS is not permitted.  Adding "information"
    which consists of advertising, unsolicited product endorsements,
    invitations to participate in pyramid schemes, or related
    documents, clearly not in keeping with the University's goals of
    education and research, would be considered unacceptable.  If you
    have any doubts about how "appropriate" any information is, ask
    before you add it.  Make your inquiry by sending a comment from
    the screen to which you wish to add the information.  If you are
    the owner of the screen you would be sending the comment from, you
    should send the comment from the main screen instead.  This is a
    somewhat complicated method of contacting someone for approval,
    but given the distributed nature of the system, it is the easiest
    method available.

    Next, it is necessary to determine if the person or group about to
    add the data is the most effective administrator of that data.
    For example, the Law School and University Relations both are
    involved in the preparation of the Law School Catalog, but the
    final copy is prepared by University Relations.  If data published
    on the CWIS should accurately represent that published elsewhere,
    University Relations should probably make the data available.
    Alternately, if timeliness is thought to be a more important
    consideration, someone from the Law School might better administer
    the information.  Before any data is added to the CWIS, at least
    one person must be identified as the owner of the data.  The owner
    is responsible for responding to user feedback, input and queies
    and is usually, though not necessarily, responsible for
    administering data files.

    When it has been determined who will own the data, the
    administrator for the data will need to determine where it is to
    be stored.  Data files that are accessed frequently (more than
    twice a minute) should probably be placed on a mid-sized
    workstation or a mainframe.  This is especially true if you are
    dealing with very large files.  Smaller files and less frequently
    accessed data may be placed on a Macintosh or an IBM-compatible
    microcomputer running the server software.

    Related to the storage issue is the maintenance issue.  When
    information is added, the administrator should have a plan for
    maintaining the files.  If they will become obsolete or will need
    periodic review plans for this activity should be in place when
    the data is added to the system.  Maintenance is discussed in more
    detail later.

    Whoever is adding the information needs to be familiar with the
    creation of Lynx documents and the use of a text editor.  Lynx is
    the software portion of KUFACTS; it displays the files which
    information providers have prepared.  Text editors are available
    on all hardware platforms and special Lynx authoring tools may
    also be available for the environment in which you are working.
    Because the majority of Lynx files are text files, the ability to
    use an editor is important.

    Lynx is designed to allow an author to edit and display data
    within the same session.  If you see something that is inaccurate
    or poorly formatted, it can be fixed "on the fly."  Additionally,
    if you want to add links between documents, the links can be added
    and tested immediately.  Avoid the temptation to put in many links
    to files on machines all over campus; doing so increases the
    difficulty of maintaining your information and makes the system
    more complicated for the end-users.

    The final step to take before entering data is to verify it.  This
    is only necessary when you are not getting the information from a
    trusted source.  A trusted source may be considered to be either
    the person with whom you would verify that particular datum or the
    printed version of the information in an official University
    publication.  Unless you can verify that the information you
    are planning on entering into KUFACTS is accurate, do not add it
    to the system.

Dealing with Feedback

    KUFACTS is set up to allow individuals reading the information to
    comment upon what they have read.  If you are an information owner
    you should include an owner_address entry in each of your
    information files.   The owner_address entry is described in
    detail in the writeup Introduction to the Lynx Hypertext Browser.
    This entry will allow anyone using the CWIS to comment on your
    information and e-mail their comment to you.  If you own
    information you should also check your e-mail daily to make sure
    there are no problems with your information.  If you will be away
    for more than a couple of days and you receive frequent feedback
    on information you have made available, you might want to
    designate someone to deal with your e-mail while you are gone.

    Feedback will take many forms.  It can be a comment on the
    structure of the document, its format, spelling, or the actual
    information content of what you made available.  When you get
    feedback consider it advice.  If it requests a format change and
    you consider it reasonable, make the change.  If you don't think
    the request is valid, decide why not.  In either case, please
    respond to the person providing the feedback and tell them what
    action you took regarding their comment and why.  If you get the
    same comments frequently, you might want to create a file of these
    comments and your responses and add the file to KUFACTS.

    If necessary, verify that corrections being submitted are valid.
    Typographical errors won't need to be verified, spelling and
    factual errors usually will.  If the correction is not valid,
    include a citation or the name of the authority who re-verified
    the information for you in your response to the person submitting
    the comment; if the correction is valid, make the change and thank
    the person who notified you that the change was needed.  Keep in
    mind that just because you verified the information when you were
    placing it in the CWIS does not mean it will stay valid.
    Information is almost always subject to change; if it weren't
    there would be much less interest in the CWIS concept.

Maintaining information

    Because change is almost a certainty, information providers should
    be proactive in maintaining their information.  Each provider
    should work with a limited amount of data, just enough so that
    he or she is comfortably aware of what information is being
    maintained and can be alert to real world changes that will impact
    the accuracy of the information.  Providing the information is
    important; maintaining it is equally, perhaps more, important.  If
    it's a full time job for someone to maintain a departmental
    handbook, then it isn't something you should plan on putting on
    the CWIS and forgetting.

    Large sets of data, such as phone book information which must be
    abstracted from existing databases, should be generated on a
    regular basis, especially if the data is undergoing change.  For
    existing databases it will usually be possible to write programs
    to extract data, build links and store the files in a standard
    location.  In such a case the information provider is responsible
    for the format of the extracted data and insuring that the extract
    is performed successfully.  An alternative to building extracts is
    to develop a "customized document" using an executable.  (Refer
    back to the section on executables as information for an
    explanation of this option).

    Modifying information

    If information becomes obsolete or is no longer valid, KUFACTS
    should be changed to reflect the updated or corrected information.
    This is especially true of topical information on events or
    occurrences.  If you know an item is inaccurate or misleading you
    should update it as soon as possible--if someone reads the
    inaccurate information and accepts it as being true, they are
    unlikely to check tomorrow to see if it is still "true".

    Modifying information ordinarily consists of editing a file as
    text.  As a courtesy to individuals using the CWIS please edit a
    copy of the file you wish to update.  After you are finished
    editing the file, replace the old file with the new one.  While
    editing the "live" file should not cause problems, it is still
    safer to edit a copy.  This also avoids problems that could occur
    if your connection to the system is lost or some similar problem
    interrupts your editing session.  When you change data, always
    test it to make sure that the links still work and the formatting
    still looks acceptable when it is being displayed.

    Removing information

    It is necessary to remove information if it becomes obsolete and a
    decision is made not to update it.  When you remove a file you
    should remove all links between your other files and the files you
    will be removing.  This will give other users linked to your data
    time to remove their links before you actually remove the file.

Support problems

    Support for the CWIS software and the systems on which it runs is
    provided by Academic User Services.  However, the only information
    on KUFACTS which User Services is responsible for maintaining is
    information related to academic computing, i.e. on-line
    documentation, schedules of training sessions, etc.  If you have
    questions about how to add information you may call Consulting
    for help between 8AM and 5PM Monday through Friday at 864-0410.

    If you are not an information provider, but have information you
    want someone to add to the CWIS for you, you should contact the
    department or group on campus most likely to be interested in
    providing that information and ask them to make the data
    available. The system is designed so that individuals can maintain
    their own data.  No department is intended to be responsible for
    the whole system and no department is intended to be responsible
    for any information but its own.

    If you have questions or concerns not answered by this writeup or
    its companion document, <units/acs/General/lynx_user_guide:42>Introduction to the Lynx Hypertext
    Browser, you may contact Charles Rezac (864-0460) at
    rezac@kuhub.cc.ukans.edu or Michael Grobe (864-0452) at
    grobe@kuhub.cc.ukans.edu.
