Agile Documentation Thoughts for Small Groups

Contrary to the 'cowboy coder' philosophy, proper documentation is just as important for a small group, or even (especially) a single employee than for a large group. Documentation must be of sufficient quality that someone coming in cold can get up to speed quickly.

Documentation closely tied to the code is best documented using comments within it. For example, I document what each table and field is used for within the Java doc for a DAO. Using Hibernate entities within the DAOs, any changes to the database happen within that DAO. This makes it easy to update the documentation, database, and code naturally within one file at the same time. I find commenting on the 'why' more than the 'what' is the important thing. The 'what' is within the code; the 'why' explains those strange corner cases within the function that a naive look at the code would indicate with a fresh look 'I can optimize this out.' Of course, the 'what' is also documented with the unit and functional tests, which are also a form of documentation.

Other documentation not tied to the code, like end-user documentation, are best documented elsewhere. Wiki's are particularly well suited to this type of documentation. Tools like OpenOffice and Microsoft Office are terrible for continuous documentation as by their nature monolithic documentation tools encourage building huge paper documents of a serial nature. I've seen many attempts to build documentation with such tools fail, generating outdated documentation that no one uses. Most modern jobs need small agile web-like documents that are easy to change, search, and use linking to easily tie them together and build natural structure without wading through a huge document.