The Software Development Life CycleThe Software Development Life Cycle
B. A little bit of a technical knowledge; e.g., understanding the difference between the Web server, application core, and database (we'll learn about this soon)
Part A is simply needed to make sure that the PM knows what he or she is talking about. I wouldn’t be happy about working on banking software with a PM who doesn't understand the difference between debit and credit cards (the first is needed to retrieve your own money, the second is needed to borrow money). Also, a PM should be an educator, because the specs should reflect the product design in a way that let developers and testers completely understand what they are required to develop and test.
Part B enables PMs to speak the same language as developers. I'm not talking about Chinese, English, Hindi, or Russian. I'm talking about the common technical language that’s an essential part of communication inside a software company. It's a bit hard to work with a PM who doesn't know that "IE"
stands for "Internet Explorer."
Each spec should have:
- a title (preferably unique); e.g., "Functional Improvements for the Search"
- a unique ID; e.g., #8765
Specs should be divided into indexed sections and subsections for ease of understanding and reference.
Each spec should have a priority. Usually this is a number from 1 to 4 (inclusive). The P1 spec is the most important. Here is why we need spec priorities:
- We can have a situation where the expected work to implement functionalities from two or more specs exceeds the availability of the engineering resources. For example, the developer and tester will not have enough time to implement and test all of those functionalities. In that case, the
implementation of functionalities from specs with lower priorities (e.g., P2 is lower than P1) can be dropped from the coming release and rescheduled for one of the future releases.
- The developer and tester should always start their programming and testing with functionalities from the spec with the higher priority.
- The functionalities from the spec with a higher priority should be tested more thoroughly than those with a lower priority. We all know that it's impossible to fully test a more or less complex system, but we surely can (and must!) provide special treatment for those specs with higher priorities. That doesn't mean that P4 specs will be tested as though they mean nothing to the company; it simply means that we have to give more love to the testing of a P1 spec than we give to a P4 spec.
The spec priority is assigned to each spec by the PM’s manager or by the PM himself/herself.
The Good, the Bad, and the Ugly Specs
Good specs, like good laws, have the following seven characteristics, or rules:
Rule #1 Clarity of details and definitions.
Rule #2 No room for misinterpretation.
Rule #3 Absence of internal/external conflicts.
Rule #4 Solid, logical structure.
Rule #5 Completeness.
Rule #6 Compliance with laws.
Rule #7 Compliance with business practices.
Problems in specs show up if the PM has broken one or more of these seven rules.
Breaking Rule #1: CLARITY OF DETAILS AND DEFINITIONS Breaking Rule #1: Clarity Of Details And Definitions
Example
Here is an extraction from spec #1111: “New User Registration”:
"1.5. During New User Registration the system should check that the email address entered by the user has good characters and has a global domain name at the end of the address right after the ‘.’ (dot).”
Does this sound clear to you?
What characters are “good”? What is the “global domain name”? What happens if “bad”
characters are entered?
The PM must do three things to clarify what is meant by a valid email address:
1. Specify that the email address contains only one “@” (at) character.
2. Provide a reference to or a complete list of illegal characters for email addresses (in other words, characters that cannot be included in an email address; e.g., “,” (comma)).
3. Provide rules about the format of an email; e.g., there should be at least one alphanumeric (a-z, 0-9) character before the @ character: [email protected].
Next, “global domain names” is not a conventional term. The correct term is "top-level domain." The PM should use the correct term and provide rules about top-lever domain formatting.
BTW
A top-level (or “first-level”) domain has:
- either a generic name with three or more characters; e.g., “com” or “info”
- or a two-character territory code based on the standard ISO-3166; e.g., “ru” for Russia Consequences
The standard practice of a new user registration consists of three stages:
1. The user submits the Web registration form.
2. The Web site sends the user an email with a confirmation link.
3. The user clicks the confirmation link, and his or her registration is complete.
So, if the system doesn’t check email addresses for two or more “@” characters, then if the user erroneously submits a registration form with such an email address (e.g.,
anna_fuente@@sharelane.com), no error message will be displayed, and the user will never receive the email with the confirmation link. The user would wait for a while for an email from your site and then, being tired of waiting, he or she would just type in the URL of your competitor into his or her browser's address bar.
BTW
A URL (Uniform Resource Locator) is unique address of the resource (usually file) on the network;
e.g., on your local company’s network (Intranet) – or on network of networks (Internet). If URL describes location of the file
SL
- You can provide the filename directly; e.g., "http://www.sharelane.com/test_portal.html" or - in certain cases, the Web server would send you the needed file. For example, if you type"http://www.sharelane.com/index.html" or "http://www.sharelane.com", you'll get the same result.
Also, in case of Web pages, you don't need to type "http://" because the Web browser will add it automatically. That's why when somebody tells you URL, they usually start with "double-u double-u double-u dot."
Breaking Rule #2: NO ROOM FOR MISINTERPRETATION Breaking Rule #2: No Room For Misinterpretation
Example
There is a classic comedy act when two people are talking about different things, but don't understand this and keep going on.
Two spouses talking over the phone:
- You know, honey, I'm so sick and tired of spam [“spam” meaning junk mail]
- Too bad, my dear, I'm afraid that you'll be without dinner tonight.
- Why?
- Because we have nothing but Spam in our home [“spam” meaning canned meat]
- So you want me to go hungry?
- No, but you said that you are sick and tired of spam!
(to be continued)
In the above example, this dialog happened only because "the honey" misinterpreted the word "spam"
(not everyone is dealing with computers, you know). The "honey" is not to blame because "the dear"
should’ve known that "the honey" might not understand the intended meaning of "spam" (junk email).
In our everyday communication we have this kind of situation very often, and in some cases it ends up in an ugly way – like "we are not friends anymore" just because someone misinterpreted something
(words, gestures, etc.). Let's remember poor Romeo who misinterpreted Juliet's sleep as a death and finished off himself.
Consequences
If a spec opens the door for misinterpretation, there is the danger that the programmer and/or tester will misunderstand that spec, and thus the code and/or test cases won’t reflect what the PM really meant while writing the spec. It sounds simple – "won’t reflect" – but in reality this can have very serious consequences for the company, especially when big money and important contracts are involved.
The most obvious way to avoid misinterpretation of the specific terms used in the spec is to write down both the terms and their clear definitions in the beginning of the spec.
Later on, we'll talk about taking other measures to prevent spec misinterpretations.
Breaking Rule #3: ABSENCE OF INTERNAL/EXTERNAL CONFLICTS breaking rule #3: absence of internal/external conflicts
Example
Spec #1: "8.1.1. For delivery, user can enter any postal address within lower 48 United States."
Spec #2: "7.3. Delivery must be made only to the billing address."
Consequences
If the conflict between these two specs is not sorted out, we can have the following situation:
- One programmer (following Spec #1) writes code to allow users to enter any address for delivery.
- Another programmer (following Spec #2) writes code to prevent delivery to any address except the billing address (e.g., where the credit card is registered).
What can happen next is that during Checkout a user enters his or her mother’s address to send her a Christmas gift, but his or her mother will never receive that gift because while the software allowed the user to enter any address, it prevented the dude in the warehouse to send the item, because the provided address didn't correspond with billing address.
Breaking Rule #4: Solid, Logical Structure
Breaking Rule #4: SOLID, LOGICAL STRUCTURE Example
"Hey diddle, diddle, The cat and the fiddle;
The cow jumped over the moon.
The little dog laughed to see such fun, And the dish ran away with the spoon."
Thanks to the unknown author of this nursery rhyme for illustrating how disconnected the components of the same “system” can be!
Consequences
Basically, the solid, logical structure of a spec is about the connections between topics, ideas, data, examples, etc. If the items of the spec are mixed and intermingled like spaghetti, this is a sure way to lead spec users (developers, testers, etc.) into confusion, or worse, into misunderstanding.
A confused person usually asks questions, while a person who misunderstood something might not be aware of it. Like Mark Twain said: "It ain't what you don't know that gets you into trouble. It's what you know for sure that just ain't so."
The golden rule for PMs should be: Write your spec like a tutorial, using clear, simple language and an easy-to-follow structure.
Breaking Rule #5: COMPLETENESS Breaking Rule #5: Completeness
Example
In trying to fight credit card fraud, credit card companies introduced a new safety measure called CVV2 (Card Verification Value 2). CVV2 is 3 (all cards except AmEx) or 4 (AmEx only) digits following the card number on the back of the credit card. If for whatever reason the PM failed to include the CVV2 verification code into the spec, the company could get exposed to fraudsters, who usually have all the credit card information except the CVV2 numbers.
Consequences
Many Internet companies, including several online payment systems, ran out of money and died because of Internet fraud. In our age, issues about security cannot be taken lightly, and the failure to
acknowledge the importance of fraud prevention will backfire pretty quickly and severely. Even if your company can deal with the enormous losses caused by Internet fraud, the company's customer support and financial and legal departments will have A LOT of trouble trying to sort out the consequences of security related mistakes.
Bottom line: "Things omitted are often more deadly than errors committed" (Leo F. Buscaglia).
Breaking Rule #6: COMPLIANCE WITH LAWS Breaking Rule #6: Compliance With Laws
Example
Because of an embargo, Cuban cigars cannot be sold in the U.S. So, if somebody sets up a Web site that sells Cuban cigars to customers in the U.S., that person is breaking the law.
Consequences Remember Napster...
Breaking Rule #7: COMPLIANCE WITH BUSINESS PRACTICES Breaking Rule #7: Compliance With Business Practices
Example
Because of the many variables during a money transfer, banks cannot guarantee the exact date when a money transfer will be complete. That's why it’s business practice to inform customers about the approximate number of days in the form of a range: e.g., “three-to-six business days.”
So, if a money transfer usually takes three to six business days, we should not promise our customers that they will get their money on an exact day. It’s much better to just have a nice, simple confirmation message: "Money transfers usually take three-to-six business days."
Consequences
Dr. Rodionoff is sure that on the exact date promised by our company his account will have 300.000 pounds of sterling. He flies to London to participate in an auction of Russian art of the nineteenth century to acquire the dream of his life: a beautiful landscape painting by Ivan Aivazovsky. He bids aggressively and wins the painting for 235.000 pounds. Now it's time to pay. The cashier takes his debit card, and after several futile attempts she says out loud (in the way only cashiers can do) that Dr.
Rodionoff's card has been declined.
First question:
Will Dr. Rodionoff ever use our services again? No.
Second question:
Will Dr. Rodionoff ever recommend our company to anyone except his enemies? No.
Third question:
Which words and expressions will Dr. Rodionoff use from now on if somebody mentions our company? Let's not elaborate on that.
---The last thing I’d like to mention about incorrect specs is this: Some PMs are confident that their specs will provide instructions about purely technical aspects to programmers, like setting up the relationships between tables in the DB or the names of variables to be used in the code. Generally, this is a BAD idea, because even if the PM has a programming background, he or she has zero to vague
understanding about the reality of coding in that particular company. Why? Because it takes full-time involvement and practical coding experience to understand what the heck is going on in the company’s programming scene. So if those technical details are provided in the spec, the tester might write the wrong test cases, because the programmer will most likely ignore PMs poking into the programmer's business.
If a PM in your company doesn't understand all negative consequences of that wicked approach, ask him or her to write software code instead of writing specs. I bet your PM would prefer to write specs!
---Spec Status
Specs have the following status order:
1. During the spec writing, its status is "Draft."
What's going on: the PM is working on the spec.
2. After the spec is finished but before it's approved, its status is "Approval Pending."
What's going on: After the spec is written, the PM sets up a spec review meeting with the
programmers and testers. Sometimes, the spec is just emailed to those programmers and testers who are going to work with it.
3. After approval, the spec's status is "Approved" or "Final."
What's going on: If the spec is accepted by the meeting participants, or if the recipients of the email with the spec have sent positive feedback to the PM, the approved spec is immediately uploaded to the company’s Intranet – available to all those who need to see it. If the spec is not approved, it all goes back to Step 1.
Spec Change Procedure Let's proceed.
After his famous game of chess in 1972 with Bobby Fischer, Boris Spassky was probably thinking, "I should've smashed his damn knight with my queen." However, there was nothing that he could do about his loss because it was in the past, and the past is irreversible. But for some PMs, a spec is not a matter of the past; it's like clay which shape can be changed… anytime. So that PM can wake up in the morning
- with fresh idea about improvement for an already approved spec - with the realization about some omission in the approved spec
After coming into the office, he or she can edit the spec and upload it back to the Intranet server. The next morning everything can start over: an idea about editing, editing, uploading… The next morning…
(we’ll stop right here).
This is what happens next:
Usually programmers and testers print out the spec in order to start working on the functionality described there. Naturally, the spec is being printed out at different times, and if the spec was secretly changed between printings, several people might have several different editions of the spec.
Even if developers* and testers print out the same edition, in the case of the following concealed spec modification, their work might be wasted because they used old spec edition.
*"Programmer" and "developer" are used interchangeably in this Course.
The keyword here is "secretly," and the described situation is about ethics, not about necessity of setting a total ban on modifications of an approved spec. After all, we are imperfect humans and new bright ideas can come to us after "the ship has left the harbor".
In many cases, the PM is asked to change an approved spec by the management.
Example
Here is the situation:
On the morning of November 25, the PM's manager sends an email to the PM with an urgent request to change spec #8337.
One day before (November 24):
- The PM was writing spec #9211 (spec #8337 had been finished and approved several weeks ago);
- The developer was writing code for spec #8222 (the code for spec #8337 has already been finished);
- The tester was writing test cases for spec #8222 (test cases for spec #8337 have already been created);
On the next day (November 25):
Spec #8337 itself, as well as its code and test cases must be changed; i.e., at least three persons must:
- drop their current (and maybe important!) tasks;
- remember spec #8337 and understand the changes;
- spend time for creating modifications of their work
This situation is an ideal environment to bring software bugs to life, because it involves interrupted people who just don't have enough room in their schedule and in their minds to fully dive into all the nuances and realize all the risks which those modifications can introduce. Furthermore, new projects might be
- implemented with less care because of having less time to spend on them;
- excluded from the coming release because of not having enough time to implement them.
So what can we do to prevent all that jazz with changing specs? Well, if management reasonably believes that the spec must be changed and/or the PM "remembered" the really really important thing, then there’s nothing we can do – the spec must be changed. That's a bad, but sometimes inevitable situation, and the person who requires the spec change better have a very solid argumentation for it.
But on the bright side, there IS something that we can do regarding two unpleasant spec changing situations:
- A spec is secretly changed.
- The spec changes are not approved by programmer and tester.
And our answer is: The approved spec edition must be "frozen."
Any Internet company has software to control file versions. In the majority of start-ups, it's the old, free, faithful CVS (Concurrent Version System).
Using the CVS, it's possible to lock a directory so none of the documents in it can be modified.
Here is an example of the spec freeze process:
1. By the specified date all specs for the concrete release must be approved. If the spec is not approved, it's dropped. See you later, alligator.
2. The CVS directory with the approved specs is locked, and nobody can make any changes to those specs, unless the Spec Change Procedure is followed.
BTW
The CVS set up and any other technical aspects of a spec freeze are usually provided by the release engineers (RE).
The spec change procedure usually has these stages:
1. Approval of all changes by the same people who approved the original edition of the spec.
2. Opening the CVS directory to save the new spec edition, then locking that directory again.
3. Sending an email with a list of changes and the names of the people who approved those changes.
3. Sending an email with a list of changes and the names of the people who approved those changes.