Recently I had a pleasure^M^M^M^M^M…, let’s say “an opportunity” to go through few functional specification documents prepared by various people (some of them by our staff and some by random client personnel). Honestly, it was truly a painful experience. I don’t intend to scare you all with detailed analysis, but there are some thick points that are worth to be listed and somehow emphasized:

  • People tend to mistake business requirements and functional specifications with technical design. Instead of describing the reality and / or trying to capture it in some kind of conceptual process model, they already start to design screens and tables. I call it screen-oriented-architecture and products based on that paradigm are usually quite fast to deliver, but terrible to maintain. Such documents are very hard to validate, as they don’t represent business reality (you have to reverse-engineer a document to find reasons for particular design decisions)

  • People have to clue what HAS TO be written in business requirements and functional specification documents. They lack core structure elements what makes the content unclear and leaky. Clueless author starts writing and he’s certain (as he may be truly the subject-matter expert in that particular area) that his document will be complete and precise, because he knows business domain well. In 90% of cases, he’s wrong (his loose description may be an introduction but does not cover all required sections).

  • People don’t like to arrange their documents in a proper structure. Typically they are not able to distinguish separate logical parts and they can’t extract different aspects of what they write about. For instance - if I was going to write about a communication junction point, I’d cover few typical points that make sense for every interface (and I’d use the same points for EVERY interface described):
    • what way of communication is this?
    • what’s entry data?
    • what’s the response?
    • does communication initiating party wait for response or not?
    • what happens if junction point fails?
    • etc.

  • People hate using any Microsoft Word functionality that is more advanced than basic typing and style changing :) Don’t be shy - use tables, bookmarks, hyper-links, cross-references. If you type manually “You can check procedure details in chapter 12”, you’ll be in trouble if you add a chapter in between later, so your chapter 12 becomes chapter 13. If you use hyper-links and cross-references, Word will do the job for you.

  • People are afraid of adding details as they fail at making documents readable. I can’t guarantee my documents are 100% clear and understandable, but at least I’m struggling for them to be. If your document is just 60 pages of plain text, no-one will read it, abandon all hope. What works for me is dividing whole documents in logically separated 0.5-1 page long (it’s a length of pure text, excluding tables) structured sections and preparing an illustrative picture for every such section. In past I’ve used to design my own graphic schemes, some time ago I switched to UML notation but it appears to be very hard to understand by business people. These days I’m trying to utilize BPMN (Business Process Modeling Notation) - it’s very simple, intuitive and you can describe a lot with just few shapes.
Just to conclude, some useful links for anyone interested in BPMN:
  1. What’s BPMN - http://en.wikipedia.org/wiki/Business_Process_Model_and_Notation
  2. BPMN shapes on one poster (sadly, it’s still BPMN 1.0) - http://www.itposter.net/itPosters/bpmn/bpmn.htm
  3. BPMN specification (if you’re hardcore) - http://www.omg.org/spec/BPMN/2.0/
  4. Nice BPMN introduction (in polish) - http://helion.pl/ksiazki/zrozumiec-bpmn-modelowanie-procesow-biznesowych-szymon-drejewicz,zrobpm.htm
Share this post