docs.yml builds Dokka on every push to main and deploys it to Pages. There is one copy, nothing on
the page says which version it describes, and what it describes is the unreleased tree. A reader who
follows the API docs badge while depending on 2.2.0 is reading the API of something that has not
shipped.
That gets worse with every deprecation rather than staying still. 2.2.0 deprecated the
kdrant-micrometer Ktor plugin and 2.4.0 deprecates a strict-mode field, so the site will recommend
replacements the reader's version does not have, in the exact place a reader goes to check what their
version has.
The other half is what happens before anybody reaches an API reference. Everything this project teaches
is in a 557-line README. That is the right home for the argument and the wrong home for the fifth task
somebody performs: a hybrid search, a resumable ingest, a collection migration and a multi-tenant filter
each have a section in there, and none of them is findable from outside the file. The API reference does
not help, because Dokka answers what a symbol is and not what to do.
What this must not become is a documentation site as a project, with a second toolchain and a second
place for facts to disagree. The shape that stays cheap: one Dokka set per released minor behind a
version selector, a landing page that names the current version and links the tasks, and a release that
adds its own version to the site the way it already adds a changelog entry.
Exit criterion: the published site carries one Dokka set per released minor with a version selector and
a default naming the newest release, publishing a release adds its version to the site, and the README's
API docs badge points at the released API rather than at main.
docs.ymlbuilds Dokka on every push tomainand deploys it to Pages. There is one copy, nothing onthe page says which version it describes, and what it describes is the unreleased tree. A reader who
follows the API docs badge while depending on
2.2.0is reading the API of something that has notshipped.
That gets worse with every deprecation rather than staying still.
2.2.0deprecated thekdrant-micrometerKtor plugin and2.4.0deprecates a strict-mode field, so the site will recommendreplacements the reader's version does not have, in the exact place a reader goes to check what their
version has.
The other half is what happens before anybody reaches an API reference. Everything this project teaches
is in a 557-line README. That is the right home for the argument and the wrong home for the fifth task
somebody performs: a hybrid search, a resumable ingest, a collection migration and a multi-tenant filter
each have a section in there, and none of them is findable from outside the file. The API reference does
not help, because Dokka answers what a symbol is and not what to do.
What this must not become is a documentation site as a project, with a second toolchain and a second
place for facts to disagree. The shape that stays cheap: one Dokka set per released minor behind a
version selector, a landing page that names the current version and links the tasks, and a release that
adds its own version to the site the way it already adds a changelog entry.
Exit criterion: the published site carries one Dokka set per released minor with a version selector and
a default naming the newest release, publishing a release adds its version to the site, and the README's
API docs badge points at the released API rather than at
main.