Improve Your Code With Documentation

This talk explains how documentation can make code easier to understand and maintain. It covers writing for different audiences, code comments, READMEs, instructions, and release notes.

Syllabus

Welcome
Agenda
Why Alexandra started a blog
Alexandras goal
I am lost
Documentation is a tool
You are already writing
The kind of technical writing I do
Good docs
Cliffs Notes
Writing
Teaching CSS
Learning is a twostep process
Write documentation first
Writing is good for you
I love sprinkles
Confetti cake
Everyone agrees
Why are you creating documentation
Does your document exist to inform
Compliance
Why
Audience
Future Self
Reassignment
Internal documentation
Know your audience
The curse of knowledge
Spell out words
Define your deliverables
Write while you code
Google Publisher Tag
Bad Comments
Write a Readme
What Makes a Good Readme
Bonus Points
Stepbystep
Bad instructions
Templates
Release Notes
Bad Release Notes
Performance Improvement
Better Release Notes
You Can Now
X Now Does Y
X No Longer Does Y
Blog Posts