Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Thinking of Documentation as Code [YUIConf 2013]

2,422 views

Published on

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.

Published in: Business, Technology
  • Be the first to comment

Thinking of Documentation as Code [YUIConf 2013]

  1. 1. Thinking of Documentation as Code Evan Goer YUIConf 2013
  2. 2. Frontend Engineer @ Intuit And much more… YUI 3 Cookbook Author
  3. 3. Thinking of Documentation as Code
  4. 4. Or: Improve Your Documentation With This One Weird Old Tip Invented by a San Jose dad! (okay no, not really)
  5. 5. A Fable The Magical Unit Test Repository
  6. 6. Why do you tell me this when you know I will kill you for it?
  7. 7. “To first order, software documentation is like code.”
  8. 8. The radical notion that Documentation is part of your project Just like your source code and build scripts and unit tests and everything else
  9. 9. Documentation lives in your repo (just like code!)
  10. 10. Documentation source is plain text (just like code!)
  11. 11. Code is very expensive (documentation even more so)
  12. 12. Corollary of “Docs are expensive”: Given a choice between writing lots of docs or fixing your code, fix your code.
  13. 13. Technical Documentation on the Wiki: Threat or Menace?
  14. 14. Don’t Allow User Comments on Documentation Pages
  15. 15. Separation of Concerns What, How, and Why
  16. 16. DRY Documentation
  17. 17. Documentation Build Targets: HTML, EPUB, PDF, TROFF…
  18. 18. Contact Info: evan@goer.org || @evangoer Thank You!

×