GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Spec inconsistency: §10.3 says the inline computation is a fenced code block, but §10.2's example indents it

Open Beginner friendly
#235 0 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

§10.3 says an Attested Computation may carry its computation inline as *"a single fenced code block in the body under `# Computation`."* But §10.2's own worked example puts the computation in a **4-space-indented** code block, not a fence:

```markdown
# Computation
SELECT SUM(amount) AS revenue
FROM finance.recognized_revenue
WHERE fiscal_year = @year
```

A consumer that detects the inline computation by looking for a *fenced* block under `# Computation` — the literal §10.3 wording — would miss the spec's own example, and for the §10.3 "inline **or** a `computation:` path" rule would wrongly conclude the computation is provided in neither place.

## The question

Should §10.3 read "a fenced *or indented* code block," or should §10.2's example be rewritten as a fenced block? Either resolves it — the mismatch between the normative text and the worked example is the problem.

## Context

Same shape as #234 (the actor convention): the normative text and a worked example disagree, so a strict reading of one flags the other. This surfaced building the same structural validator; we currently key the inline-vs-path check on the presence of the `# Computation` heading rather than the code block's style, so both forms pass.

Contributor guide

Open the contributing guide

Research direction

Compare the normative wording in §10.3 with the worked example in §10.2, focusing on the `# Computation` section and the inline-versus-`computation:` rule. Resolve the mismatch by making the specification and example use the same accepted code-block form, then verify that both forms are described consistently for structural validators.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.