I thought that using Makefile targets was the shortest friendliest to show what a project can do. Turns out make and Makefiles can be mysterious when they fail.

Tutorials are "best-effort" and often don't dwell on the rabbit-holes they create when a poor soul runs astray of the sunny path.

Example of a good tutorial:

Python's powerline shell: https://github.com/b-ryan/powerline-shell

The README is succinct. Well put together.