Merge pull request #5680 from opentripplanner/abyrd/access-overview-docs

Update overview and accessibility docs [ci skip]

docs/Accessibility.md

@@ -2,10 +2,16 @@
 
 ## Preamble
 
-GTFS and Netex define accessibility primarily in terms of binary access for wheelchair users: it's
-either on or off. Whilst it is the desire of the OTP developers to broaden the scope of
-accessibility the lack of data limits us to use this definition in the implementation and in this
-document.
+In this document and in OTP, the term "accessibility" is used with its most common 
+meaning: design of products, devices, services, vehicles, or environments to ensure they are usable by 
+people with disabilities. If you have reached this page looking for cumulative opportunities 
+accessibility indicators (access to opportunities metrics) please see the [Analysis](Analysis.md) page.
+
+While accessibility is a complex subject, at this point GTFS and Netex mostly represent it very
+simply as a yes/no possibility of wheelchair use. While OTP developers hope to broaden the
+scope and nuance of accessibility support in OTP, the lack of detailed data from data producers
+currently limits implementation and discussion in this document to this binary
+"wheelchair accessible" definition.
 
 ## Unknown data
 

docs/Analysis.md

@@ -0,0 +1,21 @@
+# Travel Time Analysis
+
+## Background
+
+Since the beginning of the project, many OTP contributors and users have been primarily interested in research, spatial analysis, and urban planning use cases. They have prototyped many ideas within or on top of the OTP codebase, including one-to-many searches producing travel time grids, isochrones, and access-to-opportunities indicators (see Terminology Note below). This has historically been a major area of application for OpenTripPlanner and has helped popularize cumulative opportunities metrics in urban planning. For example, the University of Minnesota Accessibility Observatory used OpenTripPlanner for [Access Across America](https://www.cts.umn.edu/programs/ao/aaa). 
+
+Although we consider these use cases quite important, most work of this kind has long since shifted to separate projects focused on urban planning and analytics. As of version 2, OTP has chosen to focus entirely on passenger information rather than analytics.
+
+## Travel Time Analysis in OTP1
+
+Much of the analysis code present in the v1.x legacy branch of OTP is essentially an unmaintained and unsupported early prototype for later projects, specifically [R5](https://github.com/conveyal/r5/) and the [Conveyal Analysis](https://conveyal.com/learn) system built upon it. OTP1 seems to have gained popularity for analysis uses due to the existence of documentation and an active user community, but has significant technical shortcomings. One of these is simply speed: OTP1 can be orders of magnitude slower (and more memory-intensive) than the approaches used in R5. The other is the requirement to search at a single specific time. Travel times and especially wait times on scheduled transit vary greatly depending on when you depart. Accounting for variation over a time window requires repeated independent searches at each possible departure time, which is very inefficient. R5 is highly optimized to capture variations in travel time across time windows and account for uncertainty in waiting times on frequency-based routes.
+
+## Travel Time Analysis in OTP2
+
+OTP2's new transit router is quite similar to R5 (indeed it was directly influenced by R5) and would not face the same technical problems. Nonetheless, we have decided not to port the OTP1 analysis features over to OTP2 since it would broaden the scope of OTP2 away from passenger information and draw the finite amount of available attention and resources away from existing open source analytics tools. If you would like to apply the routing innovations present in OTP2 in analytics situations, we recommend taking a look at projects like R5 or the R and Python language wrappers for it created by the community.
+
+Some analytics features may still be available as optional "sandbox" features in OTP2 (such as [Travel Time](sandbox/TravelTime.md)), but these do not work in the same way as the features you may have used or read about in OTP1. They are unmaintained and unsupported, and may be removed in the near future.
+
+## Terminology Note
+
+In OpenTripPlanner, we usually use the term "accessibility" with its most common meaning: design of products, devices, services, vehicles, or environments to ensure they are usable by people with disabilities. The term "accessibility" has a completely separate, unrelated definition in the fields of spatial analysis, urban transportation planning, and associated social sciences, where it refers to quantitative indicators of how well-connected a particular location is to people or opportunities. OTP has been widely used in research and planning settings for the calculation of such indicators. Although this meaning of the term dates back many decades, it is less well known and has become a source of confusion, so the academic and planning communities are gradually shifting to the expression "access to opportunities", often shortened to "access".

docs/Product-Overview.md

@@ -3,16 +3,17 @@
 ## OpenTripPlanner project
 
 OpenTripPlanner is a group of open source software applications that help individuals and organizations 
-calculate and deliver multimodal trip plans based on OpenStreetMap (OSM) and other standardized data 
-sources (e.g. GTFS, GBFS, NeTEx).
+calculate and deliver multimodal trip plans based on a combination of open-standard data sources.
+These include public transit services and schedules (GTFS and NeTEx) and OpenStreetMap (OSM), as 
+well as sources describing bicycle sharing or rental, ride hailing, and other services (e.g. GBFS).
 
 A community of dozens of individuals and organizations work on OpenTripPlanner collaboratively to 
 improve multimodal trip planning best practices and to make it easier for public transit agencies and 
 public transit riders to publish and access information about transit services.
 
 OpenTripPlanner deployments are locally managed in many different ways by many different types of organizations. 
 OpenTripPlanner consistently and dependably delivers multimodal trip plans to millions of riders 
-everyday in dozens of countries around the globe. The project is actively maintained by the community, 
+every day in dozens of countries around the globe. The project is actively maintained by the community, 
 with more than 50 commits most weeks during 2022, and 20 different developers having made 50 or more 
 commits during the life of the project.
 

docs/Version-Comparison.md

@@ -81,31 +81,14 @@ other projects where they are more actively developed.
 
 ### Analysis
 
-Many OpenTripPlanner contributors have been primarily interested in transportation and urban
-planning use cases. We consider these use cases quite important. This has been a major area of
-application for OpenTripPlanner and has helped popularize cumulative opportunities accessibility
-metrics. For example, the University of Minnesota Accessibility Observatory used OpenTripPlanner
-for [Access Across America](http://access.umn.edu/research/america/). Nonetheless, the analysis code
-in OTP1 is essentially an unmaintained and unsupported early prototype for later projects,
-specifically Conveyal's R5 (and the Conveyal Analysis system built upon it). OTP1 seems to have
-gained popularity for analysis uses due to the existence of documentation and an active user
-community, but has significant technical shortcomings. One of these is simply speed: OTP1 can be
-orders of magnitude slower (and more memory-intensive) than the approaches exemplified in R5. The
-other is the requirement to search at a single specific time. Travel times and especially wait times
-on scheduled transit vary greatly depending on when you depart. Accounting for variation over a time
-window requires repeated independent searches at each possible departure time, which is very
-inefficient. R5 is highly optimized to capture variations in travel time across time windows and
-account for uncertainty in waiting times on frequency-based routes.
-
-Due to its similarity to the R5 approach, OTP2's transit router would not have these same problems.
-Nonetheless, we have decided not to port the OTP1 analysis features over to OTP2 since it would
-broaden the focus away from passenger information and draw finite attention away from existing
-projects like R5 and Conveyal Analysis.
-
-Accordingly, we have made an effort to clean up and augment OTP1 analysis documentation for
-researchers who will continue to need it. It should remain possible for people to continue using
-OTP1 if they prefer. If you would instead like to apply the innovations present in OTP2, we
-recommend looking into R5 or Conveyal Analysis.
+From the beginning of the project, many OTP contributors and users have used OTP in research,
+analysis, and planning applications. They have prototyped many ideas within the OTP codebase, 
+including one-to-many searches producing travel time grids, isochrones, and access-to-opportunities
+metrics. While some of these features may still be available as optional "sandbox" features in OTP2, they are unsupported and may be removed in the near future.
+
+Most work of this kind moved over separate projects focused on urban planning and analytics. As of 
+version 2, OTP has chosen to focus entirely on passenger information rather than analytics
+applications. See the [Analysis](Analysis.md) page for more details.
 
 ### Routers API and Hot Reloading
 

docs/sandbox/TravelTime.md

@@ -11,7 +11,11 @@
 ## Documentation
 
 The API produces a snapshot of travel time form a single place to places around it. The results can
-be fetched either as a set of isochrones or a raster map.
+be fetched either as a set of isochrones or a raster map. Please note that as a sandbox feature this
+functionality is UNSUPPORTED and neither maintained nor well-understood by most current OTP 
+developers, and may not be accurate or reliable. Travel time analytics work that began within OTP
+has moved years ago to other projects, where it actively continues. See the 
+[Analysis](../Analysis.md) page for further details.
 
 ### Configuration
 

mkdocs.yml

@@ -84,6 +84,7 @@ nav:
     - "Stop Area Relations": 'StopAreas.md'
     - "Street Graph Pruning": 'IslandPruning.md'
     - Accessibility: 'Accessibility.md'
+    - "Travel Time Analysis": 'Analysis.md'
     - "Logging": "Logging.md"
 - Development:
     - "Developers' Guide": 'Developers-Guide.md'