Move "wiki" into repo

CONTRIBUTING.md

@@ -46,7 +46,7 @@ A few things to note:
 
 ## Contributing a new implementation
 
-If you have an implementation in your own repository, that's great! Just add a link to it in our [wiki](https://github.com/google/open-location-code/wiki/Other-Implementations).
+If you have an implementation in your own repository, that's great! Just add a link to it in our [wiki](https://github.com/google/open-location-code/tree/main/docs/wiki/Other-Implementations.md).
 
 Follow this process for contributing a new implementation:
 

README.md

@@ -33,7 +33,7 @@ Links
 -----
  * [Demonstration site](http://plus.codes/)
  * [Mailing list](https://groups.google.com/forum/#!forum/open-location-code)
- * [Comparison of existing location encoding systems](https://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems)
+ * [Comparison of existing location encoding systems](https://github.com/google/open-location-code/tree/main/docs/wiki/Evaluation-of-Location-Encoding-Systems.md)
  * [Open Location Code definition](https://github.com/google/open-location-code/blob/master/docs/olc_definition.adoc)
 
 Description
@@ -74,7 +74,7 @@ Rather than a large city size feature to generate the reference location, it is
 better to use smaller, neighbourhood features, that will not have as much
 variation in their geocode results.
 
-Guidelines for shortening codes are in the [wiki](https://github.com/google/open-location-code/wiki/Guidance-for-shortening-codes).
+Guidelines for shortening codes are in the [wiki](https://github.com/google/open-location-code/tree/main/docs/wiki/Guidance-for-shortening-codes.md).
 
 Recovering shortened codes works by providing the short code and a reference
 location. This does not need to be the same as the location used to shorten the

docs/comparison.adoc

@@ -1 +1 @@
-The document "An Evaluation of Location Encoding SystemsAn Evaluation of Location Encoding Systems" has been moved into the link://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems[wiki].
+The document "An Evaluation of Location Encoding Systems" has been moved into the link: https://github.com/google/open-location-code/tree/main/docs/wiki/Evaluation-of-Location-Encoding-Systems.md[wiki].

docs/wiki/FAQ.md

@@ -0,0 +1,79 @@
+# Open Location Code Frequently Asked Questions
+
+## Table Of Contents
+* [Background](#background)
+  * ["plus codes" or "Open Location Code"?](#plus-codes-or-open-location-code)
+  * [What are they for?](#what-are-they-for)
+  * [Why not use street addresses?](#why-not-use-street-addresses)
+  * [Why not use latitude and longitude?](#why-not-use-latitude-and-longitude)
+* [Plus code digital addresses](#plus-code-digital-addresses)
+  * [Plus code addresses in Google Maps](#plus-code-addresses-in-google-maps)
+  * [Plus code addresses in high-rise buildings](#plus-code-addresses-in-high-rise-buildings)
+  * [Plus code precision](#plus-code-precision)
+
+
+
+## Background
+
+### "plus codes" or "Open Location Code"?
+
+The software library (and this GitHub project) is called "Open Location Code", because it's a location code that is open source. The codes it generates are called "plus codes" because they have a plus sign in them.
+
+### What are they for?
+
+Plus codes provide a short reference to any location. We created them to provide a way to refer to any location, regardless of whether there are named roads, unnamed roads, or no roads at all.
+
+### Why not use street addresses?
+
+A lot of rural areas can be far away from roads, and people still want to be able to refer to specific locations. Also, at lot of the roads in the world don't have names, and so locations along those roads don't have addresses. There is an estimate by the World Bank that the majority of urban roads don't have names.
+
+Street-based addressing projects are expensive and slow, and haven't made much of a dent in this problem. Plus codes can be assigned rapidly and because they can be used immediately can solve the addressing problem quickly and cheaply.
+
+### Why not use latitude and longitude?
+
+One answer is that if latitude and longitude were a practical solution, people would already be using them. The problem with latitude and longitude is that they are two numbers, possibly signed, with a lot of digits, and the order is important.
+
+But latitude and longitude, and many other systems such as MGRS, geocodes, etc, also have the problem that they do not look like addresses. We all know what an address looks like - a collection of references from less detailed to more detailed, typically: country, state, city, street, and house. This hierarchy is important since it makes it easy to determine if something is near or far without having to understand the whole thing. You can tell if it's in a different city without having to know the street name.
+
+### Why is Open Location Code based on latin characters?
+
+We are aware that many of the countries where Open Location Codes will be most useful use non-Latin character sets, such as Arabic, Chinese, Cyrillic, Thai, Vietnamese, etc. We selected Latin characters as the most common second-choice character set in these locations. We considered defining alternative Open Location Code alphabets in each character set, but this would result in codes that would be unusable to visitors to that region, or internationally.
+
+## Plus code digital addresses
+
+Plus code digital addresses use known address information, like country, state, city, and then use the plus code to provide the final information. Typically converting a plus code to a plus code address removes the first four digits from the code to shorten it to just six digits.
+
+Any city or place name within approximately 30-50 km can be used to recover the original location.
+
+### Reference location dataset
+
+The open source libraries support conversion to/from addresses using the latlng of the reference location. Callers will need to convert place names to/from latlng using a geocoding system.
+
+Providing a global dataset isn't within scope of this project. For a potential free alternative, see [Open Street Map](https://wiki.openstreetmap.org/) and derived geocoding service [Nominatim](https://nominatim.org/).
+
+### Plus code addresses in Google Maps
+
+Google Maps displays plus code addresses on all entries. It does this by using the location of the business for the plus code, and then using the place name to shorten the plus code to a more convenient form.
+
+If the listing is managed by the business owner, it will try to use a place name from the address, otherwise it will use Google's best guess for the place name. (Google tries to pick names for cities rather than suburbs or neighbourhoods.)
+
+If you think a different place name would be better, you can use that, and as long as Google knows about that place name the plus code address should work.
+
+### Plus code addresses of high-rise buildings
+
+Plus codes don't include the floor or apartment in high-rise buildings. If you live in a multi-storey building located at "9G8F+6W, Zürich, Switzerland", think of the plus code as like the street name and number, and put your floor or apartment number in front: "Fourth floor, 9G8F+6W, Zürich, Switzerland"
+
+The reason for this is that plus codes need to be created without knowing specifically what is there. The other reason is that addresses in high-rise buildings are assigned differently in different parts of the world, and we don't need to change that.
+
+### Plus code precision
+
+The precision of a plus code is indicated by the number of digits after the "+" sign.
+
+*  Two digits after the plus sign is an area roughly 13.7 by 13.7 meters;
+*  Three digits after the plus sign is an area roughly 2.7 by 3.5 meters;
+*  Four digits after the plus sign is an area roughly 0.5 by 0.8 meters.
+
+Apps can choose the level of precision they display, but should bear in mind the likely precision of GPS devices like smartphones, and the increased difficulty of remembering longer codes.
+
+One reason to use three or four digits after the plus sign might be when addressing areas that contain small dwellings, to avoid having multiple dwellings with the same plus code address.
+

docs/wiki/Field-Data-Collection-Practices.md

@@ -0,0 +1,94 @@
+# Field Collection of Plus Code Locations
+[<img src="https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png" width="200">](https://play.google.com/store/apps/details?id=org.odk.collect.android)
+
+## Summary
+
+Collecting locations of equipment, buildings, homes etc from the field, and obtaining the plus codes, is a common problem.
+
+[Open Data Kit](https://opendatakit.org) is a suite of free and open source software to support collecting, managing and using data. [Open Data Kit Collect](https://play.google.com/store/apps/details?id=org.odk.collect.android) (ODK Collect) is a free, open source app available in the Google Play Store for customizable data collection in an offline environment.
+
+This document explains how to get started with ODK to collect location data and convert it to plus codes.
+
+**Note:** This process will collect latitude and longitude and convert them to global plus codes, e.g. 8FVC9G8F+6W. Converting these to plus code addresses (9G8F+6W Zurich, Switzerland) is out of scope of this data collection. (One way it could be done is using the [Google Maps Geocoding API](https://developers.google.com/maps/documentation/geocoding/intro).)
+
+## Overview
+
+First we will define a [form](https://docs.opendatakit.org/form-design-intro/) that specifies what data we want, and then use [ODK Collect](https://docs.opendatakit.org/collect-intro/), an Android app, to collect filled in forms.
+
+ODK Collect saves location information as latitude and longitude, so the final step will be to convert those to plus codes using the [plus code add-on for Google Sheets](https://gsuite.google.com/marketplace).
+
+## Requirements
+
+* ODK Collect runs on Android devices
+* The field workers will need Google accounts (we're going to use Google Drive and Sheets).
+
+## Alternatives
+
+Other options for collecting this data might be to use Google Maps - manually long pressing on the map displays an address card, and expanding that shows the plus code.
+
+Alternatively, you could write an HTML5 web app or develop another mobile app. These could do the conversion from GPS coordinates to plus codes directly. However, we think that using Open Data Kit provides the fastest route to general functionality.
+
+## Using Open Data Kit
+
+Here is a [description of using ODK with Google Drive and Sheets](https://www.google.com/earth/outreach/learn/odk-collect-and-google-drive-integration-to-store-and-manage-your-data).
+
+This procedure can be followed exactly, or a slightly easier method to define the form is described below.
+
+## Online Form Editor
+
+That document uses a Google Sheet to define the form. This can be complicated to test and debug. A simpler way is to use the [online form editor](https://build.opendatakit.org/).
+
+This provides a drag and drop method to sequence the form questions and set the field names, list of options etc.
+
+You can build a basic flow with location collection, and include additional metadata such as the time of collection, the phone number etc.
+
+You will need to create a blank Google Sheet. Name one of the tabs "Form Submissions" or similar, copy the URL of that tab and set it as the `submission URL` in the form (using Edit -> Form Properties).
+
+The, save the form and export it (with File -> Export to XML), and then transfer that XML file to your Google Drive account. (Putting it in a folder together with the spreadsheet will make sharing those files to your field workers easy.)
+
+### Location Notes
+
+You can select whether to use Google Maps or OpenStreetMap in the general settings. You can also select whether to display the street map, or aerial imagery.
+
+ODK Collect will only use GPS locations when it can see a minimum number of satellites. If your field workers will be using it indoors, then the GPS location may not be available. Instead, you can set the field to not use GPS but allow a [user entered location](https://docs.opendatakit.org/form-question-types/#geopoint-with-user-selected-location) - but that will not collect accuracy or altitude, and may also be inaccurate.
+
+A better solution is to use the manual location as a fallback to GPS. You can have one question that uses the GPS location (with or without a map), and a second question that gets the location manually, and only show that question if the GPS is not available, or the location accuracy was poor.
+
+If using the online editor, enter the following in the **Relevance** field for the manual location field:
+```
+not(boolean(/data/gps_location)) or number(/data/gps_location)>15
+```
+
+(This assumes the data name of the GPS location field is `gps_location`.)
+
+If building your form in a spreadsheet, put the following in the **survey** tab:
+
+| type | name | label | relevant | appearance |
+|------|------|-------|----------|------------|
+| geopoint | gps_location | GPS location |  | maps
+| geopoint | manual_location | Manual location | `not(boolean(${gps_location})) or number(${gps_location})>15` | placement-map
+
+# Configuring ODK Collect
+
+Install and configure ODK Collect as described in the [document](https://www.google.com/earth/outreach/learn/odk-collect-and-google-drive-integration-to-store-and-manage-your-data).
+
+The document also describes how to use it and upload completed forms to the Google Sheet.
+
+# Converting Locations To Plus Codes
+
+ODK uploads locations to the sheet using three fields:
+* location (decimal degrees)
+* altitude (set to zero for manual locations)
+* accuracy (set to zero for manual locations)
+
+To convert these to plus codes, install the Google Sheets plus code add-on from the [G Suite Marketplace](https://gsuite.google.com/marketplace). You can convert a column of locations into their corresponding plus codes using the formula:
+```
+=PLUSCODE(B:B)
+```
+This will use the default precision code length, 10 digits. If you need a different precision, specify the code length in the formula:
+```
+=PLUSCODE(B:B, 11)
+```
+Installing and using the Google Sheets Plus Codes add-on is covered in a series of videos:
+
+[![Google Sheets Plus Codes add-on video playlist](https://i.ytimg.com/vi/min-u1w4SOQ/hqdefault.jpg)](https://www.youtube.com/watch?v=n9kJC5qVeS0&list=PLaBfOq9xgeeBgOLyKnw8kvpFpZ_9v_sHa)

docs/wiki/Guidance-for-shortening-codes.md

@@ -0,0 +1,17 @@
+Shortening codes is a key feature that aids their usability.
+
+Being able to say _WF8Q+WF, Praia_ is significantly easier than remembering and using _796RWF8Q+WF_. With that in mind, how do you choose the locality to use as a reference?
+
+Ideally, you need to use both the center point and the bounding box.
+
+Given a global code, _796RWF8Q+WF_, you can eliminate the first **four** digits of the code if:
+ * The center point of the feature is within **0.4** degrees latitude and **0.4** degrees longitude
+ * The bounding box of the feature is less than **0.8** degrees high and wide.
+
+If there is no suitable locality close enough or small enough, you can eliminate the first **two** digits of the code if:
+ * The center point of the feature is within **8** degrees latitude and **8** degrees longitude
+ * The bounding box of the feature is less than **16** degrees high and wide.
+
+These values are are chosen to allow for different geocoder backends placing localities in slightly different positions. Although they can be slightly increased there will be a risk that a shortened code will recover to a different location than the original, and people misdirected.
+
+Note: Usually your feature will be a town or city, but you could also use geographical features such as lakes or mountains, if they are the best local reference. If a settlement (such as neighbourhood, town or city) is to be used, you should choose the most prominent feature that meets the requirements, to avoid using obscure features that may not be widely known.

docs/wiki/Home.md

@@ -0,0 +1,28 @@
+# Welcome to the Open Location Code wiki!
+
+The wiki is where you can find out information about using the software, the codes, or the API.
+
+## Wiki pages
+### Common pages
+*  [Frequently Asked Questions (FAQ)](https://github.com/google/open-location-code/tree/main/docs/wiki/FAQ.md)
+*  [Naming Guidelines](https://github.com/google/open-location-code/tree/main/docs/wiki/Naming-guidelines.md)
+### Specification and technical implementation
+* [Open Location Code specification](https://github.com/google/open-location-code/blob/master/docs/specification.md)
+* [Open Location Code Overview](https://github.com/google/open-location-code/blob/master/docs/olc_definition.adoc)
+* [An Evaluation of Location Encoding Systems](https://github.com/google/open-location-code/tree/main/docs/wiki/Evaluation-of-Location-Encoding-Systems)
+* [Guidance for shortening codes](https://github.com/google/open-location-code/tree/main/docs/wiki/Guidance-for-shortening-codes)
+### Technical
+*  [Supporting plus codes in GIS]([https://github.com/google/open-location-code/tree/main/docs/wiki/Supporting-plus-codes-in-GIS)
+*  [Supporting plus codes in an app](https://github.com/google/open-location-code/tree/main/docs/wiki/Supporting-plus-codes-in-your-app)
+
+### Tools
+*  [Using plus codes in spreadsheets](Using-plus-codes-in-spreadsheets)
+*  [Field Data Collection Practices](https://github.com/google/open-location-code/tree/main/docs/wiki/Field-Data-Collection-Practices)
+*  [Display the plus code grid over maps](https://grid.plus.codes) (not a wiki page)
+
+
+## About plus codes
+
+Plus codes are a digital addressing technology that aims to help people answer the question "where are you?".
+
+Developed by Google, this technology is open and free for anyone to use.

docs/wiki/Naming-guidelines.md

@@ -0,0 +1,28 @@
+# Why have guidelines?
+These guidelines are offered so that people see a consistent reference to the codes and technology. This will make it easier for them to understand what they are being shown or asked for.
+
+We have chosen two names - one for the technology and one for the actual codes. The name for the codes reflects and reinforces the importance of the plus symbol, which is how the codes can be recognised.
+
+# Plus Codes
+When referring to Plus Codes in English, the **only** term that should be used is "Plus Code", in Title Case.
+
+Some examples of usage are:
+* "My Plus Code is CX37+M9."
+* "I gave your Plus Code to the cab driver and he found the way without any problems."
+* "Will the postcard arrive if I put your Plus Code as the address?"
+* "Enter your Plus Code or street address here."
+
+## Global and local codes
+
+Codes that can be decoded to a lat/lng on their own, e.g. 796RWF8Q+WF are referred to as global codes.
+
+The shortened codes, e.g., WF8Q+WF are referred to as local codes, because they work within a local area.
+
+# Open Location Code
+When discussing with organisations or developers, refer to the library, algorithm and technology as "Open Location Code". This can be abbreviated to OLC, is capitalised, and shouldn't be translated.
+
+It shouldn't be used to refer to the actual codes - don't say "Open Location Codes" for example.
+
+# Summary
+Having consistent names and presentation will make it easier for people to recognise what is meant, and make it easier for them to use and benefit from the project.
+