~/talk

Documentation: The Missing Pieces

on YouTube 33m
Talkat Berlin Buzzwords 2021 · 2021-06-15..06-17· [documentation, developer-experience]

speaker

name:Adrienne Braganza Tacke
website:https://looksgoodtomebook.dev

resources

video:https://youtu.be/jlzKGIPQWJ8
slides:none on file

summary

Most documentation fails because it assumes knowledge and skips exact steps; fix it by spelling out acronyms, replacing foo/bar with descriptive names, and listing concrete environment requirements including exact versions, dependencies, whether a free tier suffices, and an estimated completion time. Capture and name screenshots to match steps and provide alt text, validate links, add quick-jump anchors, minimize distracting GIFs, and make examples platform-agnostic or provide a Docker setup so readers can reproduce results reliably.

AI-written summary · about

chapters (12)

  1. 0:00Introduction to documentation gaps
  2. 1:33SMH IDK acronyms problem
  3. 8:58Step skipper in tutorials
  4. 13:47Foo bar ambiguity issue
  5. 16:16Tell me what I need prerequisites
  6. 20:34Random screenshot hudis
  7. 22:43Oh you didn’t know that assumption
  8. 24:50No more 404s broken links
  9. 25:56Jump to recipe quick links
  10. 26:57Not now jiffy gifs distraction
  11. 29:06Works on my machine issue
  12. 30:31Summary best practices

related talks

~/search
type to search 6,249 conferences, 138,987 speakers and 185,172 talks
~/help
cmdctrl k
search every conference, speaker and series
/
focus the filter search
h
home
c
conferences
s
speakers
e
series
t
light / dark — the status bar button does the same
?
this help
esc
close this, then clear every filter — or just the search, while you are typing in it

Ignored while you are typing. Pages without a filter rail have no search to focus.