Consolidate about-this-site branch and refactor-project-documentation…

… branch

docs/about/specification-governance.md

@@ -0,0 +1,27 @@
+Specification Governance
+=========================
+
+Open Referral is the steward of HSDS. Open Referral's role is to facilitate and oversee appropriate maintenance and development of HSDS to ensure that it meets the needs of its users.
+
+Open Referral develops HSDS through facilitating transparent and consensus-based cycles which result in agreed upon technical changes to the specification.
+
+## Versioning and Upgrade Process
+
+When there is sufficient need and resources, Open Referral announces a development cycle, initiates a Technical Working Group, and elicits contributions from the community to set the agenda. The Technical Working Group works alongside the Technical Steward — an appointed member of the Open Referral Core Team — through various channels to provide input and synthesize specific proposed changes to the specification. The Technical Steward then takes all proposed changes that have *rough consensus* (i.e. proposals with no objections and which most people support) and codifies them into a proposal for a version upgrade which is shared with the community with a Request for Comment.
+
+The Technical Steward receives additional input from the community during this period which may result in more meetings of the Technical Working Group if it becomes necessary to seek additional consensus. Upon achieving consent from the community around a proposed upgrade, the Technical Steward implements the changes to the specification, documentation, and guidance.
+
+### Versions
+
+HSDS uses [Semantic Versioning](https://semver.org/) to distinguish between different versions of the standard in the format of `MAJOR.MINOR.PATCH`.
+
+* MAJOR versions introduce backwards compatible changes
+* MINOR versions introduce new features or functionality in a backwards compatible manner
+* PATCH versions make backwards-compatible bugfixes
+
+If a change is backwards compatible it means that data published using an earlier version still meets the requirements of the standard. For example data published using HSDS version `3.0` would be compatible with HSDS version `3.1`. Similarly, tools operating using HSDS `3.1` should not encounter problems with HSDS `3.0` data.
+
+If a change is not backwards compatible it may mean that data published using an earlier version will no longer meet the requirements. Not all HSDS publications use all parts of the standard, so it is possible that some data may still be conformant to a newer MAJOR version but it is not guaranteed.
+
+You can see a list of all the version upgrades in HSDS by reviewing our [changelog](../hsds/changelog)
+

docs/about/users-and-personas.md

@@ -0,0 +1,98 @@
+# Types of User and User Personas
+
+Open Referral recognizes a small set of ways that resource directory data is used – each such type of use is associated with diverse types of users. **These constitute our primary groups of stakeholders** – and this array of perspectives establishes the critical framework through which we conceive, design, and evaluate the products created by our initiative.
+
+**Seeking Help**
+
+_e.g., help-seeker, clients, patients, end-users, consumers_
+
+**Providing help**
+
+_e.g., referrers, service providers, case managers, social workers, librarians, call operators, etc_
+
+**Administering data**
+
+_e.g., resource specialist, database manager, IT staff, the intern who updates an Excel spreadsheet, etc_
+
+**Research and Analysis**
+
+_e.g., researcher, analyst, wonk, community planner, community leader, decision-maker, etc_
+
+
+_The following sections include our User Personas for each of these types of use. A user persona describes a broad category that encompasses many possible ‘subtypes’ of users. The persona articulates general attributes shared by all, including: relevant personal context, what information is needed and why, points of pain in the current system, and description of their behavior. A user story describes a desired action and its resulting benefit._
+
+
+## Seeking Help (i.e. help-seeker, clients, patients, end-users, consumers)
+
+**Help-seekers** (i.e. patients, clients, consumers, victims, survivors, etc.) have some pressing need (or more likely, multiple needs) which might be addressed by services in their community. To realize this possibility, help-seekers must receive accurate, relevant, and easily understandable information about services which they can access and for which they are eligible. Heightened emotional reactions, illness or injury may diminish their capacity for uncertainty and decision-making. 
+
+Help-seekers may not be fully capable of articulating the addressable aspect of their needs. They may have limited media literacy, and limited access to technology. They may not know about the existence of relevant services, let alone the ‘correct’ language to describe those services. They may have difficulty processing and/or trusting information. They may not be able to articulate their needs and may not feel safe. They may struggle with anticipated or actual stigmatization for seeking help. Incorrect information can cost help-seekers time, money, or even conceivably lives. 
+
+Help-seekers might currently look for help by searching the web, or turning to a trusted community anchor like a library, school, or religious institution. They might interface with a service provider (“referrer”) who might help identify addressable needs (through some screening process) and provide them with actionable information about services.
+
+_As a help-seeker, I want to..._
+
+* know that technology is supporting humans who are providing help, rather than replacing them, so that I can still talk to a person in this process.
+* have fewer places to contact and so that the experience of seeking help is not traumatic.
+* have privacy so that friends and relatives don’t find out about my problems.
+* receive simple, step-by-step instructions because when I’m stressed out I give up more readily.
+* quickly find reliable and easy-to-understand information about services through Google and other search engines
+* get consistent information among agencies so that I can trust it (or I won’t use it).
+
+
+## Providing help (i.e. referrer, service providers)
+
+The key point in a referral process is often a person who engages directly with a help-seeker (often in person) and helps them find information about relevant and accessible services. A ‘referrer’ is usually (but not always) a professional or a volunteer who is working for some organization that itself provides a service to its community. They are likely to be poorly paid and poorly trained. Referrers are typically the primary users of resource directory information systems. 
+
+Referrers want to trust the information they provide to help-seekers — trust regarding a) the information’s accuracy, b) the service’s relevance (is the client eligible), and c) the quality of the service. They may rely as much if not more on ‘tacit’ knowledge about services, drawn from their own experience, rather than an information system. They may use printed resources. Or they may use Google or other web searches. They may need to be able to deliver information in multiple languages. 
+
+Referrers often interact with help-seekers in the course of some kind of structured workflow. They likely conduct a screening process which identifies important attributes of the help-seeker’s situation. Referrers then match what information they have about a help-seeker to information about accessible and relevant services. Referrers are not necessarily the penultimate stop in the referrals process. A thorough referrer will call the organization before handing off the referral, and may also call to follow up.
+
+_As a referrer (aka service provider, etc), I want to..._
+
+* Specify the type of help needed in a detailed way so that help-seekers receive the specific type of help they need.
+* To describe client’s needs just once, so that I don’t waste time.
+* Track success so that over time our clients’ lives will improve.
+* Track my cases along with where they received service so that I can respond quickly to funding researchers from the city.
+* To know that a change in my process will help me deliver service better than I currently do. 
+
+
+## Data Administration (i.e. resource data specialist, IT staff)
+
+**Data administration** is typically an “internally facing” role, involving someone who has responsibility of some kind for an information system. This refers to the work done by system administrators, data producers, vendors, volunteer civic technologists, people who compile directories of all kinds. 
+
+Data admins are responsible for information production and maintenance — such as updating records, maintaining naming conventions, running reports, designing mechanisms for retrieval and delivery, etc. They may be responsible for reporting directly to funders and government agencies. These responsibilities are sometimes shared among several roles in an organization. 
+
+Updating data may entail email updates, verbal updates (often over the phone), screen scrape, unvalidated free-form notes, vetting user-submitted input.
+
+Administering data entails some level of technical skill, though these skills may have been gained in an ad hoc way, as a data administrator’s job may not technically be in “IT.” Thus, the data admin’s ability to use a system may depend to a great extent on the available documentation and training. They may be working with ambiguous instructions, with important context that might not be explicitly conveyed. 
+
+Data admin may be trying to share the burden of data maintenance with low-level, high-turnover human resources – which means they need simple instructions that are easy to convey to newcomers and yield predictable output.
+
+Generally, they want more people to be able to make better use of the data that they are administering.
+
+_As a data administrator, I want:_
+
+* a clear repeatable process flow, so that I can help people help me
+* a simple and easy to use interface, so that I can update data quickly and efficiently
+* an automatic and continuous data feed, so that I can speed data updates and validation
+* to receive feedback from users, so we can constantly improve the quality of information
+* to track who did what updates so that we can quickly assess the freshness and accuracy of the data
+
+## Research (i.e. analyst or researcher)
+
+**Researcher:** This type of user includes anyone who wants to use service directory data in synthesis with other kinds of data for the purpose of understanding community health, predicting future needs, identifying funding gaps, and other kinds of analysis. Such a role is often played by funders, policymakers, planners, or community leaders.
+
+Researchers are seeking accountability for the performance of the health, human, and social service system overall. They want their work to make this data useful for system-level decision-making.
+
+They currently get data “wherever they can find it,” often having to extract from Excel spreadsheets or other formats that aren’t designed to be used in this way.
+
+Researchers are often looking to understand the effectiveness of _programs_, which aren’t necessarily specific services but rather may include a set of services that are bundled through a particular funding stream and around a common mission. 
+
+Researchers need reliably-structured data from across institutional and jurisdictional boundaries that can be readily ‘mashed up’ with other kinds of data (census, funding, etc). 
+
+_As a researcher, I want to…_
+
+* See meaningful context for service information so that I can perform population-level analysis.
+* Know who is responsible for a service so that when it’s working well (or isn’t) we know who to contact to learn more… and replicate those successes or propose improvements. 
+* Download data in raw formats over a specific time period so I can analyze program utilization and outcomes.

docs/hsds/hsds_faqs.md

@@ -13,14 +13,14 @@ The Open Referral initiative used multiple methods of research and development t
 
 First, leaders of our pilot projects worked with stakeholders in their communities to develop a series of ‘user profiles’ that described the needs and behaviors of specific users.
 
-Then, at our Open Referral workshop in the summer of 2014, we compiled a set of ‘user personas’ that each describe one of four broad categories of use: seeking help, providing help, analyzing data, and administering data. [Read here for the set of user personas](../initiative/index.md#types-of-use-and-user-personas) developed through activities such as [the Open Referral workshop.](https://docs.google.com/document/d/1kivG6TTw1LKhJRAQHeqH7fTIxZZaDojXRRBYEd_ltWw/edit)
+Then, at our Open Referral workshop in the summer of 2014, we compiled a set of ‘user personas’ that each describe one of four broad categories of use: seeking help, providing help, analyzing data, and administering data. [Read here for the set of user personas](../initiative/users-and-personas) developed through activities such as [the Open Referral workshop.](https://docs.google.com/document/d/1kivG6TTw1LKhJRAQHeqH7fTIxZZaDojXRRBYEd_ltWw/edit)
 
 With this set of insights, we drafted an initial version of the specification that was then reviewed through several rounds of community feedback. During this time, members of our diverse network debated, clarified, and expanded the contents.
 
 Finally, we conducted initial tests of HSDS by using it to transform resource directory databases from pilot projects around the country.
 
 ## Who is the HSDS for?
-The primary users of HSDS are data administrators (who are responsible for managing systems that strive to meet the needs of other users). [Read our user personas here.](../initiative/index.md#types-of-use-and-user-personas)
+The primary users of HSDS are data administrators (who are responsible for managing systems that strive to meet the needs of other users). [Read our user personas here.](../initiative/users-and-personas)
 
 We define ‘data administrator’ broadly: while some data admins will be sophisticated managers of enterprise-grade referral systems, the vast majority of people who produce resource directory data are working with simpler technology such as Access, Excel, or even Word. Our goal is for HSDS to be usable by both the 2-1-1 resource data specialist and the IT volunteer who is helping out the neighborhood food pantry.
 

docs/hsds/use_cases.md

@@ -12,7 +12,7 @@ Open Referral's agenda is shaped by the prerogatives of four types of users:
 * researchers/analysts;
 * database administrators. 
 
-Read more about each of these types of users in [the User Personas documentation](../initiative/index.md#types-of-use-and-user-personas). 
+Read more about each of these types of users in [the User Personas documentation](../initiative/users-and-personas). 
 
 In practice, we find that the primary type of user for HSDS and its associated tools are *Database Administrators*. It is still important for us to understand the needs of other types of end users – however we often process this understanding through the lense of Data Administrators to support them directly meeting the needs of end users.
 

docs/index.md

@@ -3,7 +3,7 @@ About
 
 ![Open Referral](assets/OpenReferral_Logo_Green.png)
 
-The Open Referral Initiative develops data standards and open platforms that make it easy to share and find information about community resources. Learn more about the initiative at [OpenReferral.org](https://www.openreferral.org).
+The Open Referral Initiative develops data standards and open platforms that make it easy to share and find information about community resources. Learn more about the about at [OpenReferral.org](https://www.openreferral.org).
 
 ## Using this documentation
 
@@ -88,12 +88,12 @@ Contents:
 
 .. toctree::
    :maxdepth: 1
-   :caption: About the Open Referral Initiative
+   :caption: About
 
-   initiative/index
-   initiative/design_principles
-   initiative/faq
-   initiative/credits
-   initiative/privacy-notice
+   about/users-and-personas
+   about/design-principles
+   about/specification-governance
+   about/credits
+   about/privacy-notice
 ```