If you haven't noticed, the image at the beginning of this post is a painting by Howard Podeswa titled "Pull and Turn" which was showcased as part of the OOP - Object Oriented Painting Show.
That's very cool Howard!
Excellent topic to ponder and well worth bringing up. I would certainly agree with everything you mentioned regarding project and solution type. It is easy to fall into the rut of producing documentation just to produce it. This can be a colossal waste of all types of resources and may end-up as throw away work. Analysts definitely need to think about what the value is to producing an artifact and question the need for it just like they would question a valueless aspect of a project.
I'd also like to bring up another factor that is important to this topic. Organizational Environments are also a major component when considering what to document and what the value of it is. For instance, a firm that is in the beginning of CMMi maturation will find much more value from some artifacts than one at Level 3 or 4? This is due to the fact that the early stages of CMMi implementation involve a solidification of processes in order to get to the point that they are correct and repeatable. If the example firm was previously jumping from Requirements to Construction without Design, the value obtained from a Logical Design document and associated modeling is huge and provides great value. Equally important is the routine that is performed in order to create the documentation, which is the actual maturation of the individuals learning to execute better.
Conversely, the Level 3/4 organization has, in effect, trained itself to always follow procedure and process and knows that it ALWAYS creates this or that document. This is a point in which the personnel that do so must ask themselves if there is still inherent value in the routine. Afterall, the learning curve is no longer and if there is no other benefit from a procedural step and its document, then perhaps it should be eliminated or tailored to include only those parts that do provide value.
Thanks for the opportunity to weigh in.
At the bare minimum, the business analyst needs to do enough analysis in the problem domain to determine the conditions that are causing the business problem to be solved. This can best be done with diagrams or models, UML or otherwise. Workflow diagrams and models seem to be a preference among business analysts documenting the problem domain. It is from the definition of the conditions causing the problem that we can determine the solution and then the requirements to implement the solution. Since by definition a problem must have more than one solution (or it's not a problem) the solution domain analysis focuses on eliminating alternate solutions until the best alternative can be selected. Again, it is usually easier to use a diagram to visually compare various solutions.
When the business has provides a solution without specifying a problem and demands that solution be implemented as stated within a certain time frame, analysis becomes a luxury, and could expose the fact that the business' solution is not the best or that the business has not defined the right problem. This is what the business analyst is supposed to do, but the political fallout might not be pleasant.
I think it would be a good idea to discuss separately "suggested UML tools based on project size, solution type and lifecycle approach" and "how much analysis is needed on a given project".
In regard to the second topic, I would say that the level of experience and competence of the development team is something that can also significantly affect the amount of analysis that a BA needs to perform during a project. I've seen relatively simpler projects require much more detailed analysis and documentation only because the developer wasn't experienced enough.
For example, if I'm specifying a web application that will be used to exchange messages among people from different countries that will be developed by skilled IT professionals that I know are familiar with software internationalization, the level of documentation I'd provide on character handling would be minimum, whereas for a less experienced developer I would produce a much more detailed specification to prevent the application generating subject lines such as "???? ????? ?? ????" due to character enconding issues).
DougG makes a very good point wrt maturity.
In a high maturity organization, most of the documentation is, in principle, already there.
While there are high maturity development organizations, every development project seems to be directed only toward that development. Once done, there is no place for the documentation to go.
Even in small businesses it isn't clear there should be an 'empirical' class project. Small projects should start from the existing system and result in incremental substitutions or additions to the overall business system and documentation.
The real life situation is that even large projects can go forward with their own top level system view generated for the purposes of that project. War story: I've seen a large effort where two projects made major investments in process capture/modeling that overlapped for 20-30% of the functionality. They captured totally different processes, everyone knew it, and because there was separate funding no one cared.
In the end, users kept post it notes as they maneuvered between systems.
So, the question of what documentation to generate is really:
o what is required to gain customer "start" approval and acceptance criteria
o what is required to pass QC
o what is enough that the next level doesn't come back with too many questions
Feeling cynical today i guess.
The level of documentation to move between levels should be independent of the person at the other end.
At each hand off, there has to be an external/internal interface where the external input only specified the external behavior and the internal work uses its resources to accomplish that.
In the messaging example, "all textual data storage or processing shall support international encodings" should be sufficient. It is a good thing to walk down the hall and help the new guy out. But it isn't a good thing to muddle resource quirks into the specification documents.
apthrop said, "In the messaging example, "all textual data storage or processing shall support international encodings" should be sufficient. It is a good thing to walk down the hall and help the new guy out. But it isn't a good thing to muddle resource quirks into the specification documents."
In an ideal world, apthrop, I'd agree with you that a high-level requirement statement should be enough (and usually is for a more seasoned team, who can always come back with questions as to what your requirement really means).
If using a less experienced team, however, the way you stated the requirement would cause unnecessary development effort and code complexity because "all textual data storage or processing" would be too encompassing (in reality some processing and some data would require that, not all.
In my opinion the level of detail to be provided in the documentation has to take into account the level of detail the implementation team needs to be able to translate the functional spec into software that behaves correctly and does not suffer from "feature bloat". And this requires understanding the audience that will use your documentation.
Thanks to MA-ers out there who have responded so far. As I had hoped - the initial post has generated a lot of important discussion on this issue - and have pointed to a number of parameters to look at beyond those I had begun with. Here's my summary of what was brought up in comments:
- Maturity of the organization: with more documentation effort required for less-mature orgs (because less is there initially)
- Level of competence and maturity of the development team - with more documentation required for less competent teams. Some of the competence revolves around the team's business knowledge as well as technical (as in the internationalization example)
- Project timeframe - with less analysis on shorter timeframes due to time constraints (and possibly - politics [for better or worse])
- Reality check - how much does the customer and QA need for sign-off; how much do the developers really need.
Let me know if these conclusions sound reasonable. There is still time to add more comments and have these considered in the revisions I am currently making to my book, UML for the IT Business Analyst. Thanks will go in writing to the MA community for their input and to some of the individuals who have contributed comments.
How much do we need to model?
We need to model the essential. And as function is defined by its inputs and outputs, it is essential that we model the inputs and outputs in functional definition (i.e., fuctional requirements specification).
Until we start talking about inputs and outputs (i.e, move away from the UML and BPM techniques) there can be no answer to the question.
What about the idea of pull and push on workflow. At first pass the requirements only need to be sufficient to estimate he project and do the initial architecture. This is a pull from the project sponsor (who is paying) and the solution deisgner (who has to scope the technical work.)
Later you can deliver just enough to get the developer/designer to be able to do the work to your satisfaction (or to meet your test cases.)
If you are on the team throughout the development phase you can err on the side of light documentation - becasue you are there to ask, and you can elaborate in a Just In Time fashion. If you won't be around you need to be much more comprehensive.
Excellent point. Large project methodology is going to have phase gates of some sort. Given the UML emphasis here RUP is a canonical example.
A point to question is if there is any use for documentation after the project is complete. Agile takes the position that the code is the documentation, so any future executive who wants to know how their operations run can just read the code. Others think there is value in having clear articulation of the business strategy and business operational architecture as well as IT architecture and application design. The major arguments for the latter position is 1) that it becomes progressively more difficult to 'just fix this one thing' in the presence of the slag heap of previously 'just this one thing' local fixes, 2) that overall system validation becomes increasingly difficult, and 3) business adaptability at larger than 'just this one thing' is seriously compromised, leading to 'start over' solutions in favor of much lower cost incremental improvements.