Download Agile Oracle Application Express

CHAPTER 8
Documentation
Documentation has a bad reputation among software developers. Just mention “documentation,” and
those of us who were raised on traditional waterfall software project methods remember weighty
requirements documents, followed by detailed design documents, followed by lengthy reviews and
signoff documents, all before a line of code was written. We recall long meetings, flipping through reams
of paper (the poor trees!), and the inevitable loss of enthusiasm for the project before coding even began.
If we were lucky, funding (or interest) ran out before we were required to produce technical manuals,
end-user manuals, operational manuals, administration manuals, and more at the completion of the
coding cycle. No wonder documentation has a bad reputation for many of us aging developers—we
wrote more documentation than code. Thank goodness the Agile world has left that voluminous mode of
communication behind in favor of Agile documentation.
Agile documentation is nothing more or less than the application of Agile principles to document
aspects of your software project, when and only when it is essential to do so. Agile documentation is
clear, succinct, efficient, and just enough. Agile documentation can take many forms, the key factors
being that it must add value and it must not cost more to produce than that value. The purpose of this
chapter is to describe the principles of Agile documentation and suggest how to apply those principles to
your APEX projects.
This chapter opens with an overview of the principles of Agile documentation and discusses when,
how, and in what form to produce valuable artifacts that support your working software. The second
part of the chapter recommends standards and habits to develop for producing Agile documentation
specific to your APEX projects.
Agile Documentation
One of the core values of the Agile Manifesto is “working software over comprehensive documentation.”
So, you say, why a whole chapter on documentation? Haven’t we left that behind? While yes, the main
goal is to produce working software. Depending on your project, it is likely that documentation in some
form will be required. The difference is, in Agile software development, documentation is an essential
supplement, not the driving force or the proof of completion of your project.
There is wealth of material on the topic of Agile documentation, readily available through the Agile
Alliance or a simple web search, or through the reference section for this chapter. It is beyond the scope
of this text to repeat that information here. It is recommended that the reader consult the chapter
references for more in-depth Agile documentation material. For the scope of Agile and APEX
development, the subject can be summarized in this simple statement:
Do as little as possible, as efficiently as possible, as late as possible.
143
www.it-ebooks.info