Skip to content

Documentation Formats for Software Developers

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).

qt7

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.