External docs get a lot of attention, but this talk is about the quiet background heroes of documentation. These are the docs we write every day for ourselves and our teammates: our internal docs.

Everyone’s familiar with the pain of sifting through a large codebase while trying to figure out how things work. In many cases, a simple record of WHY a certain decision was made can save hundreds of hours of work. On the other hand, there’s nothing quite like the breath of fresh air that new teammates and internal customers get when they encounter great docs that empower them to ramp up quickly and start contributing.

Internal docs have a subtle but powerful influence on the scalability of an organization. Excellent internal docs encourage different perspectives and new contributions. Bad internal docs shut people out and cause suffering.

We’ll look at several types of internal documentation, the old standbys like docstrings and READMEs, and some surprises - commit messages are docs too! We’ll look at how these docs can go wrong and how they can go very right.