Docs: explain where the data comes from and how sources are arbitrated - #43
Merged
Conversation
The provenance page documents the facts endpoint, which answers 'where did this value come from' for a developer holding an API token. It does not answer the question a botanist or a data consumer asks first: what are these sources, why does one win over another, and how much of this can I actually rely on. This is the editorial companion. No code, no JSON: the sources and what each contributes, the four principles behind the ranking (and the plain statement that it is an editorial judgement applied globally rather than field by field), what the less obvious fields mean, and an honest account of coverage — nomenclature is solid, botanical traits are largely empty, and that is a gap rather than an inaccuracy. Says explicitly that ecological indicators describe habitat rather than tolerance, that they only cover the temperate European flora, and that 0 is a value there and not a blank — the confusion behind trefle-api#90. Also states why a range never becomes an average, and why Wikipedia never feeds a numeric field.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A page for the reader who wants to judge whether to trust a value, without reading any code.
Why a second page on this
Data provenancedocuments the facts endpoint — it answers where did this value come from for someone holding an API token and reading JSON. It does not answer what a botanist or a data consumer asks first: what are these sources, why does one beat another, and how much of this can I rely on?This is the editorial companion, and it sits first in the Advanced section so it is read before the field reference.
What it covers
0is a value there rather than a blank — the exact confusion behind trefle-api#90Verification
Build green, new page generated, both internal links resolve (
onBrokenLinksdefaults tothrowin Docusaurus 3, so a bad link would have failed the build).