Agile methodologies prefer working code and direct communication over documentation. But in distributed teams it's impossible to rely only on direct conversations. Sometimes a bit of written specification is very helpful.
Informal specification
Primary documentation format for our projects is HTML (optionally connected with CmsWiki). Important benefits:
- simple
- known by web applications developers
- portable (scales well from full-featured web browsers to simple handhelds)
- many WYSIWYG editors available (including OpenOffice)
Alternate documentation format is RST (ReStructuredText). Important benefits:
- simple like ASCII documents (minimal markup)
- easy embedding of software code listings
- easy convertable to other formats
- mergable (two persons working on one file)
Sample of RST syntax:
Section title ============= This is paragraph with some text *bolded out*. It's a link: http://aplikacja.info - A list - Another list item
Accepted variation of RST is use of Wiki. Benefits of this option:
- document can be developed and inspected on-line (possibly in real-time with customer)
- it's very easy to add changes (no need to update/checkin cycle to version control system)
Another very useful documentation format is spreadsheet. It's very easy to create (I recomment Google Docs for this task) and could be exported to CSV format in order to be parsed (testing/code generation purposes).
Formal specifications
For documenting existing software interfaces it's best to use automatically generated from source docs (Java Doc for Java, PyDoc for Python). They are always up-to-date because are regenerated automatically. JavaDoc example:
/** * Function description * @author DCI * @see AnotherClass.anotherMethod() **/ void loadTransactions(String filePath);
At more formalized level one can specify system using models (UML/OCL for instance). Those models can describe formally requirements and could be checked internally for consistency. I prefer open source tool called USE (A UML-based Specification Environment).
Writing system that will meet user requirements is as important as writing system correctly (with minimal bug rate). Transferring specification from users to development team is very important part of any project. Proper tools used for documentation may help here.