Thinking of Documentation as Code
Evan GoerYUIConf 2013
Frontend Engineer @ Intuit
And much more…
YUI 3 Cookbook Author
Thinking of Documentation as Code
Or:
Improve Your Documentation With This One Weird Old Tip
Invented by a San Jose dad!(okay no, not really)
A Fable
The Magical Unit Test Repository
Why do you tell me this when you know I will kill you for it?
“To first order, software documentation is like code.”
The radical notion thatDocumentation is part of your project
Just like your source code and build scripts
and unit tests and everything else
Documentation lives in your repo(just like code!)
Documentation source is plain text(just like code!)
Code is very expensive(documentation even more so)
Corollary of “Docs are expensive”:Given a choice between writing lots
of docs or fixing your code,fix your code.
Technical Documentation on the Wiki:Threat or Menace?
Don’t Allow User Comments on Documentation Pages
Separation of ConcernsWhat, How, and Why
DRY Documentation
Documentation Build Targets: HTML, EPUB, PDF, TROFF…