apple / apple/pkl

discrepancy in Filling out a Template tutorial

Open
#291 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
11.5k
Forks
402
Avg merge
1d 15h
Merged PRs (30d)
20

Description

hello,

In the amending tutorial, in the `nestedAmend.pkl` example
there is the extract
```
woodPigeon {
name = "Common wood pigeon"
diet = "Seeds"
taxonomy {
species = "Columba palumbus"
}
}

stockPigeon = (woodPigeon) {
name = "Stock pigeon"
taxonomy {
species = "Columba oenas"
}
}

dodo = (stockPigeon) {
name = "Dodo"
extinct = true
taxonomy {
species = "Raphus cucullatus"
}
}
```
and in the description there is a clear reference to the taxonomy field in the bird example previously treated
>In this example, `bird.taxonomy` has` kingdom`, `clade`, `order` and `species`

but the `bird.taxonomy` object has no `species property in the example
```
bird {
name = "Pigeon"
diet = "Seeds"
taxonomy {
kingdom = "Animalia"
clade = "Dinosauria"
order = "Columbiformes"
}
}
```
It seems like `woodPidgeon` is amending `bird` but that doesn't seem true in the code.
It may be very confusing (and it was) the first time ones reads about it.
I've refrained from doing a PR directly since I don't know which narration you'd prefer to have here.

Contributor guide

Open the contributing guide

Research direction

Start with the amending tutorial and its nestedAmend.pkl example, then compare the bird.taxonomy description with the shown bird, woodPigeon, stockPigeon, and dodo objects. Done means the tutorial clearly explains the taxonomy fields and the relationship between these examples without leaving the reader to infer an incorrect amendment.

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
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.