AIRS Style Guide – Resource Specialist Version
Final: August 2012
COPYRIGHT 2007, 2009, 2010 and 2012 by the Alliance of Information and Referral Systems (AIRS). All rights reserved. No part of this publication may be reproduced in any form or by any means without the express written permission of AIRS, except for the nonprofit purpose of education, and scientific advancement.
AIRS Style Guide
Scope of the AIRS Style Guide
Benefits of the AIRS Style Guide
Principles of AIRS Style Guide
Software Variations
I&R Database Structures
Changes in XSD references in this 3.1 version of the Style Guide
Data Structure: Agency
Data Element: Agency – Unique ID Number (Key)
Data Element: Agency – Record Ownership Code
Data Element: Agency – Agency Name
Data Element: Agency – AKA (Also Known As) Names
Data Element: Agency/ Phone Number(s) including Extensions, Phone Types and Phone Functions
Data Element: Agency – Internet Resource
Data Element: Agency – Website(s)/URL(s)
Data Element: Agency – E-MailAddress(es)
Data Element:Agency – Name and Title of the Director or Administrator
Data Element: Agency – Description
Data Element: Agency – Licenses or Accreditations
Data Element: Agency – IRS Status
Data Element: Agency – Federal Employer Identification Number (EIN-FEIN)
Data Element: Agency – Year of Incorporation
Data Element: Agency – Legal Status
Data Element: Agency – Status
Data Element: Agency – Date of Last Interim Modification/Partial Update; Contact for Updating Purposes
Data Element: Agency – Exclude from Website
Data Element: Agency – Exclude from Directory
Data Structure: Site
Data Element: Site – Unique ID Number (Key)
Data Element: Site – Site Name
Data Element: Site – Description
Data Element: Site – AKA (Also Known As) Names
Data Element: Site – Street/Physical Address
Data Element: Site – Mailing Address
Data Element: Site – Other Addresses
Data Element: Site – No Physical Address
Data Element: Site – Phone Number(s) including Extensions, Phone Types and Phone Functions
Data Element: Site – Website(s)/URL(s)
Data Element: Site – E-Mail Address(es)
Data Element: Site – Name and Title of Site Manager
Data Element: Site – Administrative Hours/Days of Operation
Data Element: Site – Physical Access
Data Element: Site – Travel Information
Data Element: Site – Languages
Data Element: Site – Exclude from Website
Data Element: Site – Exclude from Directory
Data Structure: Service/Program (SiteService)
Data Element: Service/Program – Unique ID Number (Key)
Data Element: Service/Program – Program Name
Data Element: Service/Program – Service Group Name
Data Element: Service/Program – AKA (Also Known As) Program Name
Data Element: Service/Program – Service Group Description
Data Element: Service/Program – Hours of Service
Data Element: SiteService/Seasonal
Data Element: SiteService/Not Always Available
Data Element: Service/Program – Phone Number(s) including Extensions, Phone Types and Phone Functions
Data Element: Service/Program – General Eligibility
Data Element: SiteService/Age Requirements
Data Element: SiteService/Gender Requirements
Data Element: SiteService/Family Requirements
Data Element: SiteService/Income Requirements
Data Element: SiteService/Residency Requirements
Data Element: Service/Program – Geographic Area Served
Data Element: Service/Program – Application/Intake Process
Data Element: Service/Program – Documents Required
Data Element: Service/Program – Fee Structure
Data Element: Service/Program – Taxonomy Term(s)
Data Element: SiteService/Resource Info
Data Element: Service/Program – Website(s)/URL(s)
Data Element: Service/Program – E-Mail Address(es)
Data Element: Service/Program – Title of the Service Contact Person
Data Element: Service/Program – Method of Payment Accepted
Appendix A: Preferred Human Services Spellings and Usages
Appendix B: Preferred Language Spellings
Appendix C: Official Post Office Abbreviations
Scope of the AIRS Style Guide
The AIRS Style Guide is a collection of recommended best practices rather than a set of prescriptive (or absolute) solutions and as such may change over time.
If a state/provincial collaborative (or an individual agency) has invested significant resources in setting up their own style guide, there is no reason to change to the AIRS model. I&R agencies are free to extract any portions of this Style Guide that meet their needs and to ignore one that do not.
The AIRS Standards continues to require the use of a style guide, not the use of a specific style guide.
The AIRS Style Guide uses, for a base, the field structure of the AIRS XSD. In a few instances, data elements might not be included in the XSD, or elements may be in the XSD that are not standard I&R concepts but are needed to tie objects together
The development of this Style Guide was overseen by a team of experienced Resource Specialists from across North America. Style is often a subjective matter. In this area, there is rarely a decision that can ever be unanimous. There is often no inherently “right” way to style a certain data element. There is, however, a right way to apply those decisions, once made, as consistency as possible.
Visual inconsistency is often most apparent in service description fields with some agencies using formal sentences and others using point formats. When the databases are merged, it makes it more difficult for users to understand. The AIRS Style Guide attempts to provide some suggestions for the creation of “good” service descriptions.
The AIRS Style Guide includes guidance on organizational naming conventions. However, every “rule” in this area, inevitably results in some local exceptions.
Appendix A includes a “preferred language” guide (for example, when to use drop in and when to use drop-ins; child care instead of childcare; southwest instead of south-west, etc.). This language guide is edited by Georgia Sales in order to align it as closely as possible with the preferred style language within the AIRS/211 LA County Taxonomy.
Appendix B includes a guide to language usage (for example, using Farsi instead of Persian, using Pashto instead of Pushto, etc.).
Appendix C contains a listing of postal abbreviations for states and territories, and Canadian provinces and territories; together with a listing of official abbreviations for mailing addresses.
Benefits of the AIRS Style Guide
There is a need to establish material that clearly outlines quality expectations.
There are not enough dedicated resource managers or skilled resource staff to consistently devise local quality solutions. People need to better understand what is involved. The AIRS Style Guide documents practical suggestions to database editing issues, so that those looking for off-the-shelf guidelines will not have to start from scratch in making those decisions.
As I&R and 2-1-1 grows, access to other databases and the ability to search them effectively becomes more important, especially in disaster scenarios. Consistency of data entry helps.
When promoting public online databases that involve resource material maintained by different organizations, variations in style make the data appear disorganized and confusing. Even if the information is correct, the overall look can diminish its credibility for public use.
Principles of AIRS Style Guide
The following factors are all influences on style issues and decisions, and are listed in an approximate order of importance. All of these factors are important but sometimes they might also be contradictory. For example, a desire for brevity may be countered by the need for clarity of meaning.
Clarity.
Accessibility. Resource information should be understandable to as broad a section of the public as possible. Information should not be only comprehended by people with higher literacy levels.
Ease of training. Training needs must be recognized. The more complicated an option, the harder it will be for people to understand and implement.
Brevity/concision.
Naturalness of language.
Accuracy in the sense of containing enough breadth and depth of information for an informed decision. It is possible to be too concise.
Consistency. But consistency for a purpose.
Relevance. Sometimes a “lesser” field may not be worth a vast amount of investment of time and effort to attain perfection.
Consensus does not mean correctness. Even if a clear majority of existing style guides have made a particular decision about a data element, it does not necessarily mean that this must be deemed as the best solution.
Software Variations
Notwithstanding this Style Guide, every I&R agency will invariably still require their own style manual or similarly named document, as every I&R software program differs in the fields that it provides and the manner that it handles different data elements/database fields.
The most obvious variation concerns the ways in which database records are constructed in terms of the data relationships between agencies, their site(s) and their services/programs.
Internal database administrative policies and procedures may also influence the area of database style.
Data Elements/Data Fields
These two terms are sometimes used (even in this document) interchangeably. But they are different in meaning.
Data elements refer to specific kinds of information (for example, a “mailing address”) while data fields refer to what have been decided as the “containers” in a specific database for one or more specific types of information.
In some cases that “container” (that is, a data field) might contain a single data element (for example, when the data element “mailing address” is contained in the data field “Mailing Address”). In other cases, a single data field may contain more than one data element (for example, the data elements “service capacity” and “source of funds” may both be included within a data field called “Service Description”).
The AIRS Standards only deals with “data elements” (whether required or recommended) and leaves decisions as to how that information is incorporated into a database to the individual I&R agency based usually on the database design of their I&R software.
I&R Database Structures
The AIRS XML Schema is used to facilitate data exchange, particularly among users of different I&R software programs. An I&R provider could export their Resource Data using this format if their software supports this option. The export creates an XML (Extensible Markup Language) document which contains information structured in a certain way so that data can be imported with greater ease than if an XML Schema were not used.
The AIRS XML Schema defines the elements that are expected from a resource database and the format and/or content of the information.
The AIRS XML Schema is structured so that each Agency (usually defined as an independent organization) has at least one Site (a physical location which provides a service), and at least one SiteService (a way to link a service or program to a site).With AIRS XSD 3.0 all Services are tied to the physical location where it is offered. Therefore if and Agency has two site that offer the same service, in AIRS XSD 3.0 the format would be one Agency with two Sites and each Site would have SiteService that described the service.
Changes in XSD references in this 3.1 version of the Style Guide
In 2012, following an in-depth process involving I&R peer subject matter experts and the leading I&R Software vendors, the AIRS XSD was upgraded from 3.0 to 3.1. This document reflects those changes in terms of their impact on the AIRS Style Guide.
The following are the primary differences between this and the earlier version of the AIRS Style Guide:
Data Structure: Agency
Removed
Annual Budget Total
Source of Funds
Added
Internet Resource
Status
Data Structure: Site
Removed
Annual Budget Total
Year of Incorporation (remains in Agency section)
Legal Status (remains in Agency section)
Data Structure: SiteService
Removed
Other Requirements
Aid Requirements
Area of Flexibility
Service Capacity and Type
Added
General Eligibility
Data Structure: Agency
Definition
An agency is a legally recognized organization, either incorporated or a division of government, that delivers services. An agency can be incorporated, a division of government, or an unincorporated group that offers, for example, a food pantry or support group. The agency is the main location of the resource where the administrative functions occur, where the organization’s director is generally housed and where it is licensed for business. An agency may or may not deliver direct services from this location. On occasions, I&R services may choose to designate a middle level of the organization as the agency. For example, a city Department of Human Services may offer hundreds of services but is often recognized by the names of its component programs: Social Services, Health Department, etc. It is acceptable to use those components as agencies as long as their relationship to the larger Department of Human Services is acknowledged in the description or by the way the database is structured.
Summary of Agency Data Elements
AIRS Standards Name / AIRS Standards Requirement / AIRS XSD NameUnique ID Number / Required / Key
Record Ownership Code / Required / Record Owner
Agency Name / Required / Name
AKA (Also Known As) Names / Required / AKA
Phone Number(s) including Extensions, Phone Types and Phone Functions / Required / Phone
(See full information for more details on structure on Phone)
Internet Resource / Internet Resource
Websites/URLs / Required / URL
E-mail Address(es) / Required / Email
Name and Title of the Director or Administrator / Recommended / Contact (See full information for more details on structure of Contact)
Agency Description / Required / Agency Description
Licenses or Accreditations / Recommended / License Accreditation
IRS Status / Recommended / IRS Status
Federal Employer Identification Number (EIN/FEIN) / Recommended / FEIN
Year of Incorporation / Recommended / Year Inc
Status / Required / Status
Legal Status / Required / Legal Status
Date of Last Interim Modification/Partial Update; Contact for Updating Purposes / Required / Resource Info
(See full information for more details on structure on Resource Info)
Exclude From Website
Exclude From Directory
Data Element: Agency – Unique ID Number (Key)
Definition
The record ID number is a unique numerical code that is affixed to every single record within a resource database (whether that is an agency record, a site record or a program record). Although the organization’s name might change, its unique number will remain the same.
AIRS Standards Reference: Unique ID Number (Required Element)
AIRS XML Reference: Agency/Key
Preferred style
For example, between 00001 to 99999
01641
12579
There is no “official” limit to the number of digits that can be used (although five should be more than sufficient).
Additional information
Every record needs a unique number that allows it to be organized, searched and retrieved other than through an examination of its content. Most I&R software systems automatically generate a new number for every newly created database record. An I&R agency may not be able to adjust this system.
Data Element: Agency – Record Ownership Code
Definition
A code that identifies the organization responsible is for maintaining the record. It is used to facilitate combination, in a single consolidated database, of records maintained by different organizations. In some resource databases, the record ownership code may be combined with the Unique ID Number to create one distinct code identifying both the agency and its record owner.
AIRS Standards Reference: Record Ownership Code (Required element)
AIRS XML Reference: Agency/Record Owner
Preferred style
ABCBTI
NYMINN
SDSFLS
NDFARGO
The code should consist of two characters that match the state abbreviation for the record owner’s location (that is, the record itself could be concerning another state, but the “ownership” code is for the agency maintaining the record), followed by a four to eight character string of letters (or numbers).
Additional information
This code allows records to be identified according to ‘maintaining’ or ‘record owning’ agencies within collaborative databases that might contain the merged database records of two or more I&R agencies. In many cases, the operational ownership code will be consolidated with the record ID number for comprehensive identification purposes (for example, ABCBTI001673 or NYMINN017924) as otherwise two agencies are almost certain to maintain different records with the same record ID number (for example, ABCBTI001829 and NYMINN001829). Agencies operating within a consolidated system need to ensure that no two participating agencies share the same code.
Once established, most I&R software systems automatically insert the organizational ownership code into every newly created database record.
Data Element: Agency – Agency Name
Definition
This is the full legal name of the organization that provides the programs/services that are being included within the resource database. In certain cases, rather than the full legal name, a decision can be made to use the name under which the organization is more commonly known or is “doing business as” (such as using YWCA instead of Young Women’s Christian Association).
AIRS Standards Reference: Agency Name (Required Element)
AIRS XML Reference: Agency/Name
Preferred style examples
Abacus Child Care Center
Anytown Parks and Recreation Department
Arizona Department of Labor
Big Brothers and Big Sisters of Anytown
Burton D Morgan Foundation
Evergreen Youth Services
Gathering Place
George D Dodge Intermediate School
Saint Jude’s Emergency Shelter
Saint Vincent de Paul Society
South Carolina Department of Health
Yellow County Social Services Department
YMCA Anytown
Additional information
Strive to use full names without abbreviations and ampersands (for example, Anytown Parks and Recreation Department instead of Anytown Parks & Rec. Dept.). You may understand the abbreviations but a person who is not a native English speaker may not.
Avoid beginning an organization name with the word “The” (such as The Gathering Place). A failure to follow this principle tends to create hard-to-follow alphabetical listings with dozens of agencies called “The this …” and “The that …”.