Liquid Media's Apps

Agile Documentation

I'm presenting the following talk tonight at Toronto's Ruby on Rails Project Night. 6 p.m. at the Rich Media Institute (156 Augusta St.):

"Programmers generally hate writing documentation. That's because most documentation is kept separate from the code and becomes hard to keep up-to-date. Besides violating the DRY principle... it can lead to misleading documentation, which is generally worse than none at all." [Subramaniam/Hunt '06]. Why do developers hate writing documentation, and why do stakeholders and managers keep requiring it? Is there agile documentation beyond inline API documentation (JavaDoc, RDoc, etc.) and comments in the code? What parts of a project deserve separate-from-code documentation? How do we identify them, capture them, and keep them relevant? This talk discusses the problem of documentation, explores some key aspects to consider when writing effective documentation, and dreams of a future of testable, executable documentation, where non-code knowledge could be integrated into your code.

This is the area of my M.Sc research, so you're going to see more on this topic on this blog over the next few months (and maybe years!). I look forward to your comments.

Tagged agile, documentation, and presentation.
blog comments powered by Disqus