1.1.1.9. Linking Your Records

v4.0-beta

Note

Part of the Draft v4 User Guide: under review during beta testing.

Important

Linking is in beta. It is open to signed-in beta testers, and screens and wording may change. Words used here are defined in the Glossary. Please report anything that does not behave as described through the beta snag list (see the Beta Testing Plan).

This guide is for beta testers who own a dataset in WHG. It explains what a Link is, how WHG suggests possible Links for your records, how to work through those suggestions, and what happens to your Links when your dataset is reviewed, published or withdrawn.

Linking is optional. Your dataset can be published and found whether or not you link anything. Links are an enrichment: they help other people find your records beside related ones.

1.1.1.9.3. Getting started

Open your dataset’s page. If linking is open to you, it has a Links card marked beta:

  • before any suggestions exist it says “No suggestions have been prepared for this dataset yet.” and offers Link your records;

  • afterwards it shows how much of the dataset you have reviewed, how many Links you have made, how many records had nothing found (“normal”) and any not yet checked, with Continue linking.

These counts are shown only to you and your dataset’s team. The WHG editors who review your dataset do not see them, and they play no part in that review.

On the Link your records page, if no suggestions have been prepared yet, choose Prepare suggestions. You can do this while your dataset is still private: nothing of yours becomes visible by doing so.

1.1.1.9.4. Working through the suggestions

The left of the page lists the records in the current tab; the right shows one record at a time with its suggestions, best first. The heading line shows how many records you have reviewed out of the total, and how many Links you have made.

Each suggestion shows its title and identifier, its source (for example GeoNames, Wikidata, Getty TGN, OpenStreetMap, OpenHistoricalMap, Pleiades or WHG contribution), its type, its distance from your record, its dates and countries, up to three other names, and a sentence saying why it was suggested and what disagrees, such as “Suggested because: exact name; under 1 km away.” followed, where something disagrees, by “But: …”.

1.1.1.9.4.1. Your choices for each record

  • Same place beside a suggestion links your record to that suggestion.

  • Same place below the list (or Enter) links your record to the suggestions you have selected. Click a suggestion, or press its number key (1 to 9), to select or deselect it; you can select more than one. If none is selected, the first suggestion is linked, so look at it first.

  • Not the same place beside a suggestion (or x when exactly one is selected) passes that suggestion over. This records nothing about the world, and the record stays in its tab. For a record in Which one, if any?, Advanced also has a box, When I say “Not the same place”, also record it as a Link others can see: tick it to make your answer a Not the same place Link.

  • None of these fits (or n): none of the suggestions is right. This is a note about your review, not a statement about the world, and only you and your dataset’s team see it.

  • Not sure yet (or l) moves the record to Later.

  • Undo (or u) takes back your last decision on this page: it withdraws the Links you made for that record on this page (from its suggestions or from a hand search) and returns the record to its tab.

Use ← and → to move between records without deciding. Under Advanced you can choose Same place, exactly instead of Same place for the Links you make from the record on screen.

You may type a note (up to 2000 characters) saying why you decided. It is kept with your decision, and with any Link the decision makes, where it is shown.

1.1.1.9.4.2. Searching by hand

If the suggestions miss a place you know, use the search box under the record (s puts the cursor there). It searches within the same limits as the suggestions; each limit, such as the record’s dates, is shown as a chip you can switch off. Results show the same facts as suggestions and offer Same place. If the search service does not answer, the page says so (“this does not mean nothing exists”) rather than showing an empty list.

1.1.1.9.5. Private until your dataset is published

A Link that involves a record in a dataset that is private or embargoed is saved as pending. A pending Link is shown only to you and that dataset’s team (and WHG staff), marked “Visible to you and the dataset owners until it is published”. It never appears in Links made by people, is never shown to the public and is never sent outside WHG.

When the dataset is published, its pending Links become public, provided the record at the other end is public too. A Link to a record in another private dataset stays pending until that dataset is published as well.

1.1.1.9.6. Review before publication

During beta, every dataset is reviewed by the WHG team before it is published. Review is separate from linking: you need not start, or finish, linking for your dataset to be reviewed, and you can go on linking while it is under review.

1.1.1.9.6.1. The Review and publication panel

Review and publication are done from a panel on your dataset’s page, headed Review and publication and marked beta. Only the dataset’s owners see it, and only when signed in with beta access. It shows the dataset’s current stage in plain words (for example “Private draft: only you and your collaborators can see it. When it is ready, submit it for review by the WHG team.”) and only the buttons that apply at that stage. Buttons with consequences ask you to confirm first, and say what will happen.

A dataset you uploaded before this review process existed does not enter it automatically. If it is private, the panel offers Start the review process. This moves it to a private draft and changes nothing else: “It stays private while you prepare it. When you submit it, the WHG team reviews it, and it can be published only after that review.” A dataset that is already public cannot be started; it would have to be made private first.

1.1.1.9.6.2. Submitting

While the dataset can be submitted, the panel shows:

  • Before review: two questions, which the editor reads “when deciding whether part of the dataset should be held back”: whether the dataset includes information about Indigenous peoples, lands or places that their communities may wish to control, and whether it includes locations that could cause harm if widely known (sacred or burial sites, vulnerable heritage, private homes). Answer each, then choose Save answers. A “yes” asks you to say briefly what is sensitive;

  • an optional Note for the editor, and Submit for review (or Submit again for review after changes were requested, after the dataset was declined, or after it was withdrawn).

Both questions must be answered before you can submit. Until they are, the submit button is greyed out and the panel says “Answer the two questions on Indigenous and sensitive data before submitting this dataset for review. Use “Save answers” above first.” If you answered Yes to either question without saying what is sensitive, it says “You answered Yes to a sensitivity question: say briefly what is sensitive before submitting this dataset for review.” Answers you saved earlier are kept, so you need not answer again when you submit the dataset a second time.

You receive an email saying when to expect an answer; reviews usually take up to 10 working days, and the panel shows the expected date (“The WHG team will usually reply by …”). The dataset stays private meanwhile.

The panel also has Automatic checks, the same checks the editor reads, each marked as passed, worth a look, must be fixed, or not checked:

  • records loaded, and the licence: a dataset with no records, or no licence, cannot be published;

  • placeholder identifiers (where a private draft has some, Remove them deletes them in one step), possible duplicates, coordinates and dates;

  • description and attribution;

  • the sensitivity declaration (until both questions are answered it says “the dataset cannot be submitted for review until they are”);

  • whether link identifiers resolve (not checked yet).

Your copy of the checks also counts the records with links and the Links made from your records. The editor does not see these counts.

1.1.1.9.6.3. What the editor does

An editor opens the review queue, chooses Start review (so others know the dataset is being looked at), reads the automatic checks and your answers, looks at your records, and decides:

  • Accept, with an optional note: the panel then says “Accepted. You can publish it whenever you are ready.”

  • Request changes, with a note saying what needs changing. The panel shows “The editor’s note” and offers Submit again for review once you have made the changes.

  • Decline, with a reason. The panel says “The editor has declined this dataset. It stays private. You can edit it and submit it for review again.”, shows the editor’s reason, and offers Submit again for review.

Each decision is also sent to you by email, with the editor’s note.

1.1.1.9.7. Publishing and withdrawing

Publish appears on the panel once the dataset is accepted. Its confirmation says: “It becomes public: anyone can see and download it, its records are added to the search index, and the links you made from its records become public too.” Then:

  • its pending Links become public, as described above;

  • it is added to WHG’s search index, usually within minutes. Until that is done the dataset page says “Waiting to be added to the search index”. Datasets with polygons are added too;

  • if it cannot be added automatically, the dataset page says “This dataset could not be added to the search index automatically. Please contact the WHG team if it is still not searchable in a day or so.”

Withdraw appears once the dataset is published, with an optional reason. Its confirmation says: “It becomes private again: it is removed from the search index and its public page, and the links you made from its records stop being public.” Its Links go back to pending at once.

A withdrawn dataset goes back through review before it can be published again. The panel says “To publish it again, submit it for review again” and offers Submit again for review.

A dataset with places in WHG’s older shared v3 index cannot be withdrawn this way: WHG asks you to contact the editorial team.

A dataset that becomes public by another route (for example the older v3 dataset settings) also has its pending Links made public, provided the record at the other end is public too.

1.1.1.9.10. Known limits in beta

  • Fuzzy search does not find newly published places yet. Once a dataset is in the search index, its places are found by exact-name searches and by searches on the start of a name. Fuzzy search, which allows for spelling variation, finds them only after a further processing step has been run on the index. Suggestions for other people’s records use fuzzy search, so your newly published places are not suggested to them until then.

  • Some wording elsewhere is still WHG v3’s. The progress badges on the dataset page, for example, still show the v3 steps. The older v3 matching tools also still work during beta; see Guides & Tutorials.

  • Suggestions are prepared once. After the first run there is no button to prepare them again.

  • A newly uploaded dataset does not enter the review process by itself. Choose Start the review process on its page while it is private.

  • Linking, the Concordance and Links made by people are open only to beta testers until WHG v4 opens to everyone.

1.1.1.9.10.1. What is not built yet

  • a map on the suggestions page;

  • an email when suggestions are ready;

  • preparing suggestions automatically once your upload has been checked (for now you choose Prepare suggestions yourself);

  • refreshing suggestions as new records are published;

  • a background worker reserved for preparing suggestions;

  • confirming many suggestions at once. This stays off until WHG has checked, against beta testers’ decisions, how often Likely the same place is right;

  • uploading a dataset straight into the review process (for now, Start the review process after uploading);

  • a count, on WHG’s dashboard, of the datasets waiting for review.