Language tutorial "Writing a Template" is confusing sometimes
- Dominant language
- Java
- Stars
- 11.5k
- Forks
- 402
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 20
Description
[This](https://github.com/apple/pkl/blob/release/0.26/docs/modules/language-tutorial/pages/03_writing_a_template.adoc?plain=1#L170-L247) whole section talks about `pklTutorialPart3.pkl` which had not been defined up to that point. Additionally, it's talking about types and classes and then shows an example of amending that has no classes (`TutorialPart.pkl` and `pklTutorialPart3.pkl`).
It goes on to [say](https://github.com/apple/pkl/blob/release/0.26/docs/modules/language-tutorial/pages/03_writing_a_template.adoc?plain=1#L246-L247):
```
This now behaves exactly like our pklTutorialPart3: TutorialPart = (pklTutorialPart1) {… before. pklTutorialPart3 is now defined as the value we get by amending tutorialPart and giving it a name and a part
```
Ok, it behaves exactly like that so then what's the point of using a class (I know the point, I don't understand why the tutorial is going down this path).
Contributor guide
Research direction
Read docs/modules/language-tutorial/pages/03_writing_a_template.adoc, especially lines 170-247. Trace where pklTutorialPart3.pkl is first introduced and compare the discussion of types and classes with the TutorialPart.pkl and pklTutorialPart3.pkl examples. Done means the section defines its examples in order and explains why the class-based path is useful.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100