Documentation neglect is a chronic problem in most enterprise application development efforts. This problem is unrelated to the selected development methodology but there are some who assume that agile methods eliminate documentation despite the agile manifesto's declaration that we value "working software over comprehensive documentation." It does not claim that documentation is not needed.

In my own work, I've found that comprehensive documentation authored by well meaning individuals, or worse a committee, who possess very little technical expertise, is often written in confusing, lengthy narrative style that requires a linguistic anthropologist to decipher. Too often development teams spend days pulling out the real features and requirements and expected behavior from such documents, generally resulting in many unanswered questions, the answers to which just cannot be found in the comprehensive documentation.

Recently we have found greater value in documentation that has relatively strict structures that guide authors to produce specific, detailed and comprehensible documentation. The format is simple and adopted from the increasingly popular behavior driven design (BDD) approach.

The goal of this approach is to define desired behavior and clear acceptance criteria for specific requirements without mashing them all together in a narrative style that requires time consuming decomposition. Here's the format:

+++++++++
P[n]: Process Title
Two line description of a process (akin to epic user story)

F[n]: Function Title (a feature or step in the workflow)
As a role
I want action/process description
so that benefit/value of feature.

AC[n]: Acceptance Criteria or Scenario Title (p1)
Given some initial context (the givens),
when an event occurs,
then ensure some outcomes.

+++++++++

It's really not different than BDD. There is only one subtle difference which I've found can make all the difference in the world. the terms used (process, function and acceptance criteria) are far less scary to the business than terms like epic, user story and scenario.

Of course, this won't work for every situation, but where you can break documentation down into logical units that focus on one feature, one thing at a time, you can eliminate the time consuming deconstruction of comprehensive documentation that can only be processed by the most advanced computer in the world: the human brain.