Upload
evangoer
View
1.191
Download
1
Embed Size (px)
DESCRIPTION
As a software engineer, one of the best things you can do for your documentation is to take the principles of code construction that you already know and apply them to your writing. We'll demonstrate how thinking about documentation as code will help you avoid many of the classic high level mistakes people make when launching documentation projects. This is a companion piece to last year's talk, which focused on how to optimize English prose at the micro level.
Citation preview
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…
Contact Info: [email protected] || @evangoer
Thank You!