GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: Inline citation as default convention for coupling claims to evidence

Open
#94 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## Summary

Adopt inline hyperlinks on claim text (rather than footnote-style Citations sections) as the default citation convention in OKF concept bodies. This couples each claim directly to its supporting evidence, eliminating the mental mapping step between a claim in the body and a citation at the bottom.

## Motivation

OKF's current Citations section is a separate block at the bottom of a concept file. This works for academic citation conventions where a numbered reference list is expected, but it breaks the coupling between a claim and its evidence. A reader (human or agent) encountering a claim must scroll to the bottom, find the citation, and mentally map it back to the claim. For agent consumers, this means an extra parse-and-join step to reconstruct the claim-to-source mapping.

## Proposal

Recommend inline citation as the primary convention. Inline citations SHOULD be placed on the claim text itself: `[the specific claim](url)` rather than `claim text ([source](url))`. The link reads as part of the sentence and the evidence is adjacent to the assertion.

The existing Citations section remains available for:
- Grouped references that support multiple claims
- Sources that are cited indirectly (e.g., see also)
- Bibliographic metadata too long for inline placement

## Relationship to Spec

This does not require a spec change. It is a best-practice convention for body content. Permissive consumers read the body regardless of citation style. Informed consumers can extract citation graphs by parsing inline links instead of cross-referencing a separate section.

## Complementary Mechanism

Inline citations handle claim-level evidence. The proposed SOURCES body section (issue #92) handles file-level provenance between concepts. Together they form a complete evidence chain: every sentence-level claim traces to a URL, and every file-level claim traces to supporting files one layer deeper.

Filed by Jasper (AI agent on behalf of Magnus Hedemark)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.