I once worked in an environment where it was mandated that all new projects would create “use cases” for all requirements. We would be doing away with standard functional requirements and the non-functional requirements would be as limited as possible. All requirements were to be disgorged, at the use case level, into a system, and this would be the future.
Naturally, I vehemently opposed this approach.
I told my manager that this was all good and fine but my project would not be doing it. He told me that was not the case and that we would comply. We went into a project review session with the senior technology executive who had mandated this – a man I respect very much and find to be quite thoughtful, creative, and intelligent – and as politely, but directly, as I could, I reiterated my position. He looked at me once, twice, asked for my reasoning, I gave it, and then he said “okay”: my project had a pass.
The words I used were: “Fit for purpose”. What I think he most wanted out of my project, and everyone’s for that matter, was not blind obedience but evidence of thought, evidence of examination and consideration.
Believe it or not, I am not a documentation junkie. I like to write (as you can see, I have a whole website dedicated to that!) and I like to draw — I feel like I’m missing a limb without a whiteboard and a sketchpad and Visio on my machine — but that’s because we live in
- a distributed world where we must collaborate over land masses and oceans and through space and sky
- documentation brings the past to the present which is necessary to create the future, and
- it’s a way to check the coherency and efficacy of your thought process
In a perfect, sci-fi like world, I would have a thought, we would struggle with it between our mighty telepathic minds, and then it would be done. The real world doesn’t work that way, therefore, no matter how much we would like to avoid it, we need to write things down.
Writing things down in a haphazard fashion is just as bad as not writing them at all. I wish that right alongside “Object-Oriented Programming” and “Financial Algorithms” they taught “Writing Requirements” or “Methods of Functional-Logical Structuring”. In any undergraduate college course you can find a software architecture class but you don’t find the equivalent ‘soft skill’ of functional requirements definition, which is an abstraction of that logical architecture into the “functional pieces” of how it works so as to convey the how in which a business process will be executed. It’s not seen to be as important and that’s a failure of imagination and a failure to recognize the fundamental difficulties of communication. But, I digress, let’s continue on our journey to define “fit-for-purpose”.
Writing too much is just as bad as not writing enough. Do you see a theme there? Your average developer is a) not going to read 200 pages of documentation or b) won’t understand it. If you have 200 pages of documentation, you must ask yourself the following questions:
- Is this the smallest functional unit I can break this into? If not, why don’t I split this into separate documents which can then be distributed, likely, to multiple developers to develop their individual, yet to-be-integrated, bits of functionality?
- Am I using paragraphs where I can use bullet points? If I’m using too many bullet points in a single requirement or specification, why am I not splitting them out?
- Pictures are worth a thousand words – am I using paragraphs where I ought to be using pictures?
- Is information in here that is purely contextual and doesn’t push forward items?
- Should this be in an appendix for additional, voluntary reading, perhaps even in a separate document altogether?
- Do I know enough to break this down to the parts it needs to be broken down to or do I need to return back to my users (or in the case of a functional analyst back to the business analyst) to better define something?
I once read a functional specifications document that came in at 132 pages. My reaction:
- I was angry, really and truly.
- It buried the requirements in paragraphs and context and historical thought processes and options discussions and…it buried the requirements – they were utterly unclear.
- Business requirements were mixed with functional specifications and the mish-mash it created had led to development that reflected the lack of clarity and distinction; in other words, a system full of bugs and dead-ends and change requests everywhere.
- Future updates to the document were a dead-end; it wasn’t usable as a core document and began a cycle of fix/break/fix/break that was terrible – terrible on morale, terrible on the relationship between IT and the business, terrible on new joiners, just plain terrible everywhere.
Use cases and mockups and functional specifications and business requirements, oh my! In the posting where I spoke about asking for forgiveness and not permission, I had a section where I talked about how one document couldn’t serve all audiences, and that’s true. In addition, one type of document is incapable of covering all types of projects.
Now, that’s not an exhaustive list, but it’s my general thought pattern, and it’s core to being “fit-for-purpose”. I don’t want to create documents which are for the purpose of checking boxes; I create documents which can be used for:
- Understanding of what needs to be done
- Building of what is necessary to meet those needs
- Testing and validating that we did it right
- Providing an audit trail/transparency, i.e. “bringing the past to the present”
- Supporting future enhancements and bug fixes, i.e. “creating the future”
- Allowing for an eventual ordered decommissioning or shutdown of the product and/or system.
Documentation, in our modern era, can feel clunky and a waste of time or effort. In the “Agile world”, the “proof is in the pudding” of the product. Also, in the Agile world, the proof is in the spaghetti code and the consistent, constant reengineering efforts. Even in the non-Agile world, non-fit-for-purpose documentation has created a Gordian’s Knot of infrastructure and systems in many a company, and many of us suffer daily due to this fundamental challenge.
I could talk for hours on this topic, but I won’t. I think my meaning is clear: when you embark on a project, especially if you get to be the one who does it from the beginning, ask yourself two questions:
1) What’s my purpose?
2) How am I going to document it to fit that purpose?
As long as you have a good reason…