ytt guides & examples

[cari-lynn]

Problem Statement

The current ytt documentation goes in depth listing what features are available in ytt which is acting like a reference. However, it lacks in explaining how these various features can be applied in real-life scenarios which leaves new ytt users to figure out how to use ytt to solve their problems on their own. This not only takes time for new users to ramp up in ytt but also leaves them feeling less confident whether they are using ytt the “best way” or the intended way it was designed to be used.

Many ytt users have pointed out that the interactive playground is a great place to learn, however, it could be hard to find the topic the users are interested in and the name of the topics are not descriptive enough to help finding the right example they are looking for.

First Increment (MVP)

Research and compile a list of 5 or 6 use cases for guides. This list will be updated as we research and get feedback.

• Getting started with ytt from plain yaml
• When I would use library file, private library, or a data values file?
  • e.g. Is "composability" really a fundamental ytt limitation that jsonnet doesn't have? #392
  • e.g. #carvel@2021-06-02T14:14Z
• Create Guide: How to convert Helm templates to ytt templates #649
• Create guide: How to use ytt with Helm #650
• Create example: Templating in a multiline string #651

Prioritizing content over presentation, create guides and code examples for the use cases.

Collect feedback on the guides early and incorporate it into the following guides.

[pivotaljohn]

Data point: #728

TL;DR. A critical factor in "maintainability" of a system is how likely would someone in my shop be able to intuit what's going on mostly from what's there.