Generating a Culture of Code Documentation

Generating a Culture of Code Documentation

This is from a presentation given at the Write the Docs conference,

Cutter’s experience is that SMEs fall into three categories in roughly equal proportion: eager to help, willing to help (with guidance in the form of templates and direction), and curmudgeons.

…You as a writer have knowledge that engineers need to help them write docs effectively, and when you share that knowledge you help them write more docs. Hold doc office hours where you’re available to help them with docs. Because some text is better than no text.

Curmudgeons will say “but code documents itself!” Cutter calls “bull”; code only tells what it does, not its intent. [NB: Intent is worthless if the code’s action doesn’t match it.] Even if you know what you wrote immediately after you wrote it, six months later you’ll have moved on and that’s when the documentation becomes critical.

One comment

Comments are closed.