carvel-dev / carvel-dev/ytt

Inconsistent use of the terms 'annotation' and 'directive' in docs

Open
#458 5 comments 0 reactions 0 assignees View on GitHub
carvel accepted discussion documentation
Dominant language
Go
Stars
1.9k
Forks
167
PR merge metrics
No merged PRs in 30d

Description

### Acceptance Criteria

**As a** ytt user looking at the "When should I include a space in my ytt comment?" question in the faq
**I want** to see an answer explaining why some annotations use spaces and some don't.

**As a** ytt user looking at the docs
**I want** to search the docs for "spaces in annotations", "#@ overlay or #@overlay", or "When do include a space in my annotations?", and see a result pointing to a FAQ response answering the question.

**As a** ytt user looking at the docs
**I want** to search the docs for "templating directive", or "directive", and see a result pointing to [Text Templating](https://carvel.dev/ytt/docs/latest/ytt-text-templating/).

Additional doc fix:
In the [Known Limitations](https://carvel.dev/ytt/docs/latest/known-limitations/) it mentions a "templating directive", I think these references can be changed to "annotation".

---
Original issue context:

It was pointed out on slack that in the [faq](https://carvel.dev/ytt/docs/latest/faq/#when-should-i-include-a-space-in-my-ytt-comment-does-it-matter-is-it-load-or--load-overlaymatch-or--overlaymatch) defines a clear boundary between annotations and directives. This definition is confusing and it contradicts how we define a [yaml annotation in the yaml primer doc](https://carvel.dev/ytt/docs/latest/yaml-primer/#annotating-yaml).

@ewrenn8 noted: "All `#@`'s are annotations, the `#@ 1+1` is just syntactic sugar for the full annotation `#@temeplate/code 1+1`"

---
Vote on this request

This is an invitation to the community to vote on issues, to help us prioritize our backlog. Use the "smiley face" up to the right of this comment to vote.

👍 "I would like to see this addressed as soon as possible"
👎 "There are other more important things to focus on right now"

We are also happy to receive and review Pull Requests if you want to help working on this issue.

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.