Fix Code, Delete Docs

*
Proposal
Short Form
Beginner

Excerpt

Educators, authors, and co-workers are constantly demanding more code comments and documentation, yet none of them ever update it. The comments lie, the documentation exists in three variants, and still nobody knows how to make the code do the right thing.

Description

The great benefit of software’s malleability is lost when documentation weighs it down. This talk will explore common beginner and intermediate mistakes in commenting and documenting code. We’ll learn to recognize potential problems and see how “lying comments” evolve through code changes. Let’s get to a deeper understanding about our users (whether end-users, developers or co-workers) and what they want out of “documentation” so we deliver better, more useful code and less noise. Maybe we can even get to less code. Sometimes, the solution is to write some clever code instead of dumb documentation, and sometimes code can write the documentation. We’ll also look at some elements of code craft and learn how to make code speak for itself. Bad and/or good examples and/or cookies may be included.

Tags

documentation, codecraft, DWIM, DTRT, dry, UX. WUT

Speaking experience

Eric has previously spoken at OS Bridge, OSCON, LFNW, and given several presentations at various local user groups.

Speaker