I've finally had an opportunity to read Julian's response to my article, Problem to Solution.... Because I can't respond on his site, I'll respond here with a promise to expand these thoughts into another article.
First, I generally agree with Julian's thoughts as I understand them.
Julian makes the point that "needs" and "solutions" are tightly coupled pairs that cannot live alone. I think what he is saying is that a real life problem statement always implies some level of solution. If it didn't we'd start every project from a point charge in a vacuum (a phrase I've stolen from my colleague). While this is generally true, I think it's a different vein of argument. What I'm trying to show is that we want to get to the most abstract statement of the problem that meets the business vision. This focuses us on the problem independent of all solutions.
I really bristle when I read terms like "business requirement" and "stakeholder requirement". I used to live by RUP so I understand what they are attempting to capture. My problem is the mindset they put the reader in. I'll post more on this later, but generally a "requirement" is something that "must" happen which implies that someone has already thought about how to do it (the solution), it just has to happen now. My preference is to keep people thinking about the possibilities as long as possible which is a different mindset. To get into this mindset we think about the problem we have, rather than a set of requirements.
Julian does tie the terminology to the perspective, which is something I also eluded to but have yet to fully articulate. One person's "requirement" is another person's "design". I agree with this notion, but I would state it differently. I would say that a solution at one level is a problem at the next level. So we know we want a website for auctions (a solution) what's the nature of that website (new problem). I'm still clarifying this stuff in my head, so the discussion is useful.
Wednesday, March 3, 2010
Tuesday, March 2, 2010
Focus the Documentation Effort To Maximize the ROUTE
Documentation is a means to communicate. It takes substantial effort to create good documentation, thus we want to ensure that the effort will provide an equal or greater payback. Just as much effort can be wasted on developing great documentation that turns out to be useless as can be wasted on reverse engineering a system with no documentation. The focus must be to maximize the ROUTE: Ratio Of Usefulness To Effort.
For each potential piece of documentation ask the following questions:
The usefulness of a document varies based on the perspective. From the perspective of the project, a document is useful if it gives the designers more in-site or information and is used by a large audience. From the perspective of the audience, a document is useful if they get the information they need from it and return to it many times. A useful document may be reviewed once by many people who are then able to provide feedback. Another useful document is used many times by one person to find the information they need quickly and easily. These differing perspectives have differing needs and likely different documentation forms.
Minimizing the document creation effort requires looking at the requirements for format, formality, completeness and the available creation aids. The effort in creating a formal document can be substantially reduced if there are tools available to assist in the generation. For example the use of document templates or document generation from code or models lowers the effort and allows the designer to focus on content. Simplifying the format is, however, the best way to minimize effort. The documentation format is really a communication format. Simple forms such as spreadsheets, sticky notes, e-mail messages, and white boards may provide the same usefulness with far lower effort.
One very effective way to maximize the ROUTE in software projects is to document the solution design and its constraints in the code. The only place anyone will ever look to understand how something actually works is the code itself. Therefore, this is where the documentation should be not only for the low level design (the code implementation) but also for the higher level patterns being used. Unit tests provide additional documentation of the understanding of the problem that was being solved as well as the constraints on the design chosen. Code is documentation.
Every industry and enterprise has its own documentation requirements and software engineers must work within those requirements. In the payment card industry PCI DSS is the big one and has all sorts of documentation and lifecycle requirements to go with it. How to maximize the ROUTE of the documentation in each area is a problem in the domain of enterprise architects to solve.
For each potential piece of documentation ask the following questions:
- Who is responsible for creating the documentation
- What is the documentation skill level of people in that role
- Who are we trying to communicate it to
- What information are we trying to communicate
- Where is the information best kept
- What is the easiest possible way to reference the information
- What format is best for the information
- Are there requirements to communicate it in certain format
- When should it be documented
- How many times will it be referenced
- What is the maintenance lifetime of the document
- Is it practical to maintain
- Why should it be documented
- What would be the impact of not documenting it
The usefulness of a document varies based on the perspective. From the perspective of the project, a document is useful if it gives the designers more in-site or information and is used by a large audience. From the perspective of the audience, a document is useful if they get the information they need from it and return to it many times. A useful document may be reviewed once by many people who are then able to provide feedback. Another useful document is used many times by one person to find the information they need quickly and easily. These differing perspectives have differing needs and likely different documentation forms.
Minimizing the document creation effort requires looking at the requirements for format, formality, completeness and the available creation aids. The effort in creating a formal document can be substantially reduced if there are tools available to assist in the generation. For example the use of document templates or document generation from code or models lowers the effort and allows the designer to focus on content. Simplifying the format is, however, the best way to minimize effort. The documentation format is really a communication format. Simple forms such as spreadsheets, sticky notes, e-mail messages, and white boards may provide the same usefulness with far lower effort.
One very effective way to maximize the ROUTE in software projects is to document the solution design and its constraints in the code. The only place anyone will ever look to understand how something actually works is the code itself. Therefore, this is where the documentation should be not only for the low level design (the code implementation) but also for the higher level patterns being used. Unit tests provide additional documentation of the understanding of the problem that was being solved as well as the constraints on the design chosen. Code is documentation.
Every industry and enterprise has its own documentation requirements and software engineers must work within those requirements. In the payment card industry PCI DSS is the big one and has all sorts of documentation and lifecycle requirements to go with it. How to maximize the ROUTE of the documentation in each area is a problem in the domain of enterprise architects to solve.
Subscribe to:
Posts (Atom)
