Generate (Evangelist Job Description) from YAML

Example of automated yaml generation (using Jekyll within GitHub) referencing values defined in markup variables at the top of the YAML file

Overview

Using variables
The generated job description
Responsibilities: Day in the life
The ideal candidate
Bonus points
What we offer
Summary
Other ways to automate YAML
- Others:
More on Technical Evanglism

This is an example of a job description for a Developer Advocate, generated by GitHub’s Jerkyll from YAML (markup text) stored in a (private) GitHub repo.

NOTE: Content here are my personal opinions, and not intended to represent any employer (past or present). “PROTIP:” here highlight information I haven’t seen elsewhere on the internet because it is hard-won, little-know but significant facts based on my personal research and experience.

Using variables

This page is also an example of how page variables can be used in the markup text so that key words can be changed in one place and be applied to all instances in the document.

The author of this page added variables in the header at the top of the authoring file which is not presented to readers. Within the body of the article’s text is inserted developers. When Jekyll reads this markup to generates HTML, it substitutes the variable with the data value from the header.

{{ page.company }} is looking for a {{ page.role }} to join us in attracting the interest of {{ page.targets }} using {{ page.languages }} to use our {{ page.product }} along with {{ page.job_tools }}.

Values are obtained at the top of the page containing:

company: XYZ
product: Gizmo
role: Developer Advocate
job_type: SRE
passion: technology evangelism
team: marketing
travel_pct: 20%
bring: content and perspective 
certifications: AWS, Pragmatic Marketing
skill: presenter
expertise: product and customer
targets: developers
competencies: application servers, scripting, and network infrastructure
languages: Go, NodeJs, Python, C, Ruby, and Rust
clouds: Amazon (AWS), Azure, and Google
platforms: Kubernetes
job_tools: GitHub, Maven, Gradle, Groovy
colab_tools: Zoom, Slack, Jira, Confluence, Google Mail
document: use cases (solution briefs)
demo: best practices
---

CAUTION: Misspellings of keys would result in a compilation error that blocks all other page processing.

The generated result:

The generated job description

XYZ is looking for a Developer Advocate so we better attract the interest of developers using Go, NodeJs, Python, C, Ruby, and Rust to use Gizmo along with GitHub, Maven, Gradle, Groovy.

The successful candidate is an engaging communicator, passionate, and loves interacting with our partners, clients, and prospects.

You know the concerns, interests, demographics, and cultures of developers, and you have creative ideas around how we can connect deeply and effectively with them.

As a key member of our small, rapidly growing marketing team, you will be the face and voice of XYZ to developers.

You will be the go to person for telling our story to the market - on stage at events, during industry-wide webcasts, and in conference rooms at the largest companies.

This role would involve up to 20% travel internationally.

As an expert in product and customer, you will be the sales force’s key marketing contact to help develop effective account specific go-to-market strategies.

We’re seeking not only great presenter but an excellent listener, who is curious about the needs and concerns of our prospects and customers.

You’ll be using Amazon (AWS), Azure, and Google where we run Kubernetes.

Responsibilities: Day in the life

Your key responsibilities toward building a following of passionate developers include the following during a day in the life:

Identify strategies and opportunities to bring content and perspective to both developers and executives who manage them.
Plan content and campaigns (with partners) that leverage time and expense to achieve the highest returns.
Analyze trend data in order to position XYZ as a thought leader.
Analyze new features and capabilities to present them as useful and compelling.
Seek out and write up use cases (solution briefs) to demonstrate best practices.
Publish blog posts and tutorials and speak at meetups and conferences to highlight best practices and offer fresh perspectives.
Champion users’ needs internally by providing invaluable feedback to the sales, product, and engineering teams.
Craft attention-getting yet informative posts in social networks and create blog and video content to attract and grow interest.
Use and create open source projects so developers can adopt the company’s offerings quicker and more confidently.

The ideal candidate

Has done a similar job before, with sharable examples of your work (previous speaking opportunities, conference speaker feedback, and/or recorded webcast delivery).
Has built a visible online presence via social media, blogs, forums, GitHub repos and/or community involvement.
Experience as a current or former SRE with one or more apps published in an app marketplace (Google Play, Apple Store, Windows Store, Office Store, iTunes, etc.)
Ability to code in Go, NodeJs, Python, C, Ruby, and Rust.
Expertise using GitHub, Maven, Gradle, Groovy.
Familiarity using Zoom, Slack, Jira, Confluence, Google Mail and other collaboration tools.
Can confidently moderate discussions among technical and non-technical groups.
Passed AWS, Pragmatic Marketing certifications.
Has potential aspirations for marketing, business development, sales, or product leadership roles in the future.

Bonus points

You get bonus points if:

You are in love with the Gizmo product.
You are a tinkerer! Show us any personal projects you’ve worked on, GitHub projects you’ve forked, etc.
You are naturally inclined to provide unbelievable customer service and enjoy teaching and helping others.
Measurable competency with application servers, scripting, and network infrastructure.
Experience in a startup and growth-stage environments
Developed a “maturity model”.

What we offer

For ideal candidates we offer ideal perks … (dream on)

A unique opportunity to play a critical crossover technical/ business role at a high-growth company in a rapidly emerging category
The chance to say you “got in early” into one of the pioneers
Equity
Matching 401(K) plans
100% employer paid premiums for medical, dental, life insurance, disability
Free lunches, dinners, and fully stocked snacks & beverages
Commuter benefits for public transit and bicycle commuters
Free parking (We pay for parking tickets, too.)
MacBook Pro Max (32 GB, with 2 additional screens)
Employee development opportunities
Flexible vacation - take time off when you need it
Wellness initiatives (incentive programs, fitness classes)
Shower facilities in the building
Free gym membership with shuttle service, onsite cardio gym, company organized and sponsored sports and leagues
Volunteer opportunities and extra PTO for community work
Monthly happy hours
Lounge areas with ping pong, foosball, pinball, and arcade games
Company ski trips, boat parties, BBQs, happy hours, game nights … just to name a few!
Casual dress code

Summary

BS in a STEM degree, SRE experience, ability to code in Go, NodeJs, Python, C, Ruby, and Rust, excellent written and presentations.

Other ways to automate YAML

YAML is ubiquitous. Wether you love it or hate it, you have no choice but using it. It established itself as the configuration format for all things cloud/devops/serverless (choose your buzzword).

https://learnk8s.io/templating-yaml-with-code describes the difficulty of editing static YAML injected by Kubernetes and other systems, then offer alternatives:

https://kustomize.io/ which was created for Kubernetes. kustomize uses a file called kustomization.yaml to decide how to template the YAML.

Kustomize recognizes inheritance.
A CLI tool called yq can merge two YAML files together. A command such as this outputs to stdout:
```
yq m -a append pod.yaml envoy-pod.yaml
```
Helm charts used for package management. “Whoever struggled with toYaml in Helm charts is a victim of YAML text templating.”

https://github.com/helm/helm
Handlebars
Cue is a configuration language that doesn’t limit itself to Kubernetes. Instead, it can generate the configuration for APIs, database schemas, etc.
jsonnet is a data templating language similar to Cue. Although JSON is in its name, it also handles YAML and other file formats

https://jsonnet.org/

jsonnet is a powerful language that natively understands the data structure.

https://www.swisspush.org/tools/2020/01/29/painless-yaml-templating
jk is a data templating tool designed to help write structured configuration files.

https://github.com/jkcfg/jk
Write a program such as pod.js. Examples on how to create Kubernetes YAML in Java, Go, Python, C# are at:

https://github.com/learnk8s/templating-kubernetes
Dhall is a functional programmaging configuration language. “the best-kept secret in the DevOps world right now”

VIDEO: An introduction

https://dhall-lang.org/

says create a single authoritative configuration file (source of truth)

https://github.com/dhall-lang/awesome-dhall

https://ferrai.io/2019/dhall-survey-review/

https://github.com/dhall-lang/dhall-lang

“JSON + functions + type + imports”

https://github.com/sjakobi/awesome-haskell-tutorial-modules shows Dhall’s affinity to the Haskell language.

Dhall allows you to write a single config for use to derive the correct configurations for each tool used.
- json-to-dhall
- dhall-to-json
- dhall-to-json
- json-to-dhall
- yaml-to-json
- json-to-yaml
It features:
- lambdas
- let bindings
- modules
- Sum and Product types
https://github.com/dhall-lang/vscode-language-dhall

Install its VSCode for Dhall LSP Server:

https://marketplace.visualstudio.com/items?itemName=dhall.vscode-dhall-lsp-server

https://dhall-terraform.org/ -> https://github.com/dhall-terraform supports generating valid .tf.json configurations from a total functional programming language (dhall)

Dhall’s provider for Terraform:

https://github.com/awakesecurity/terraform-provider-dhall

Dhall’s integration with Kubernetes:

https://github.com/dhall-lang/dhall-kubernetes
Skycfg is an extension library for the Starlark language that adds support for constructing Protocol Buffer messages (and hence Kubernetes resources):

https://github.com/stripe/skycfg

Others:
Jinga
kube-gen (kapitan), a tool internal to AirBnB to simply “the Kubernetes Workflow for 1000+ Engineers” was described on APR 18, 2019 by Melanie Cebula at:

https://www.infoq.com/presentations/airbnb-kubernetes-services/

“The whole service is generated by one command” referencing _infra folder in GitHub.
ytt : “a middle ground” with powerful overlay features.

Use its playground to see it in action processing your own Git file from GitHub:

https://carvel.dev/ytt/#playground

The utility’s source code is at VMware’s open-source GitHub:

https://github.com/vmware-tanzu/carvel-ytt

Its docs are at:

https://carvel.dev/ytt/docs/v0.41.0/install/#via-homebrew-macos-or-linux

Install it on your mac:
```
brew tap vmware-tanzu/carvel
brew install ytt
ytt version  # ytt version 0.41.1
```
This blog explains the tool:

https://developer.ibm.com/blogs/yaml-templating-tool-to-simplify-complex-configuration-management/
yaql (Yet Another Query Language)

https://yaql.readthedocs.io/en/latest/
HashiCorp created “consul-template” as a Template rendering, notifier, and supervisor for @hashicorp Consul and Vault data. It was created by the great Seth Vargo when he was at HashiCorp:

https://github.com/hashicorp/consul-template

When Consul Template first starts, it reads any configuration files and templates from disk and loads them into memory. From that point forward, changes to the files on disk do not propagate to running process without a reload.

The templating language is described at:

https://github.com/hashicorp/consul-template/blob/main/docs/templating-language.md

Wilson Mar