Kathy Korevec Avatar

Kathy Korevec

Ship It! Ship It! #17

Docs are not optional

On this week’s episode, Gerhard is joined by Kathy Korevec, former Senior Director of Product at GitHub, and now Vercel’s Head of Product. Docs play an essential role in GitHub Actions, and Gerhard’s experience has proven that. Building, testing, and shipping code with GitHub Actions works better because of their excellent docs. However, the docs that Kathy pictures are not what you are imagining. She explains it best in her post, Maybe it’s time we re-think docs, which is what started this whole conversation.

The bottom line is, just as you wouldn’t ship untested code, shipping code without documentation is not optional. Today’s conversation with Kathy explains why.

Kathy Korevec Medium

Maybe it’s time we re-think docs

Kathy Korevec has been putting a lot of thought into documentation as part of her work at GitHub:

Wouldn’t it be great if the docs knew that you were writing a Python app on a Windows machine and that you preferred watching videos instead of reading through text? I want you to find the answer to your questions in the docs, easily and efficiently. When you’re stuck on a problem and you turn to the docs, there’s a moment of magic as you find the solution, try it out and it works. In that moment you become unblocked, you learn something new and you can move on to keep building your application.

In this post, she outlines 10 guiding principles she developed after speaking with hundreds of developers about their struggles with documentation. She then shares how she’s putting those principles into action in/around GitHub. Good stuff.

0:00 / 0:00