Lecture 4 - The Software Development Life Cycle -> Quick Intro -> Idea -> Product Design -> Coding: Part 1
As a rule, ideas are accumulated into a Marketing Requirements Document (MRD). The gist of the MRD is: “It would be good to have these functionalities on our Web site.“
Then, ideas from the MRD are approved, disapproved, or ignored by the management, and those ideas that were approved are passed on to the product managers (PMs), who create specs based on those ideas.
As a rule, a “manager” is a person who manages other people.
Product managers don’t manage people; instead, they manage products. The “product” is a large or small functional area of a Web site; e.g., at MySpace, there can be a product manager who specialized in the functional area called “communication between members.” If the PM is a good one, his specs are well written and easy to use; if the PM is a bad one, his specs are misleading and bring more chaos than order.
Specs can also be called:
– the PRD (Product Requirements Document)
– the BRD (Business Requirements Document)
– simply the “requirements”
The gist of the specs is: “These are the functionalities that we are going to implement on our Web site.“
We need specs to design the product. The difference between the idea and the design is this:
The idea is a description of the purpose (e.g., “We want to enable people to do this and that”).
The design is a description of the way to reach the purpose (e.g., “In order to enable people to do this and that we have to do the following: …”).
The most effective PMs are those who have:
A. Professional and/or educational backgrounds in the area they specialize in (e.g., if someone is designing banking software, previous banking experience is very helpful).
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 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.
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
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@example.com.
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-level domain formatting.
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
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 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 would just type in the URL of your competitor into his browser’s address bar.
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
– You can provide the filename directly; e.g., https://www.sharelane.com/test_portal.html or
– in certain cases, the Web server would send you the needed file. For example, if you type https://www.sharelane.com/index.html or https://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
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.
– 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.
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
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.”
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 mother’s address to send her a Christmas gift, but his 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
“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!
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
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.
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
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.
Breaking Rule #7: COMPLIANCE WITH BUSINESS PRACTICES
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.”
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.
Will Dr. Rodionoff ever use our services again? No.
Will Dr. Rodionoff ever recommend our company to anyone except his enemies? No.
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 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 to write software code instead of writing specs. I bet your PM would prefer to write specs!
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.
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 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.
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.
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.
If it’s a start-up, then it makes sense to send this email to all developers, testers, and PMs. The reason for this wide distribution is simple: in many cases a PM might not know who already is using previous edition of the spec.
Remember, it’s not possible to live without changes in the approved specs, but by a spec freeze, the introducing the Spec Change Procedure, and a thorough audit of the necessity of each change (with the participation of the management), we can prevent a lot of serious software quality issues.
It’s also a good idea to turn on text editor functionality “Track Changes” every time when approved spec is being changed. In that case, it’s possible to see changes without comparing different versions of file with spec.
Having rules in place doest NOT mean that these rules are being followed. Anyone who has kids knows what I’m talking about. So the idea is not only to have rules, but also to ENFORCE those rules. I’m not talking about smashing keyboards against the culprits’ heads; there are much more civilized methods like, “Sorry dude, no bonus for you this quarter.”
Another important point: If the management supports the introduction of rules, but doesn’t enforce them, those rules have no meaning. How do you make the management get serious about enforcing the rules? There is no universal recipe. The management usually wakes up after a couple of postponed releases and ugly P1 bugs released to customers.
The rules must be concrete and clear so that folks have no problem understanding them.
Talk to the PM manager about introducing and enforcing concrete, clear rules on spec writing and the modification of approved specs.
As you already know, one of the serious problems associated with specs is called misinterpretation; i.e., a situation that occurs when the spec audience (mainly programmers and testers) misunderstand the PM’s words. What’s dangerous about this is that folks who misinterpret something usually:
– are 100% sure they have a clear understanding of that something;
– don’t ask questions, because why ask questions about something when that something is obvious?
Specs are often misinterpreted because of the PM’s failure to present things from different angles. So, it’s very important for PMs to illustrate their specs. Below are the three most common ways to do that:
Illustrations are beneficial for both parties:
– the author who tries to illustrate his ideas gains a better understanding of the those ideas;
– the reader who receives the illustrated ideas has a better chance to fully comprehend whatever the author is trying to say.
Using examples is the most universal and powerful way to explain things. Two ways to create an example are:
– Bring a direct situation to the attention of your audience. For example, when we talked about log files we saw an example of an actual log file (Test Portal>Logs>cc_transaction_log.txt).
– Take a concept and create an analogy. For example, remember the story of my friend who thinks about his soul/body as a software/hardware. An analogy is a marvelous way to create an example, because you can present things from an unexpected perspective and thus invoke another path of thinking for yourself and your audience.
Now, let’s talk about mock-ups. Folk wisdom tells us, “A picture is worth 1000 words,” and “Seeing is believing.” For this reason, it’s a very good idea to attach mock-ups of the UI (User Interface) to the spec. The process of creating mock-ups is pretty simple:
1. During (or after) creating a spec, the PM takes the Web page generator (like Microsoft FrontPage) and by simple manipulation creates a prototype of a Web page with buttons, fields, images, and other details of the UI.
2. Then this Web page
– is published on the Intranet, and a link to it is provided in the spec and/or
– the Web page design is saved as an image (e.g., in a jpeg format), and that image is inserted into the file (e.g., a Microsoft Word file) with the spec.
It’s also a good idea to print out those mock-ups and attach them to the wall in the office.
Here is a description of the UI from the spec #1111, “New User Registration”:
– Page 1 has a field for “ZIP code” and a button “Continue”
– Page 2 has fields for “First Name,” “Last Name,” “Email,” “Password,” “Confirm Password,” and a button “Register”
– Page 3 has a confirmation message.
All fields are required, so if user enters an invalid or null value for any field, the system generates the same page, but with an error message. (Note that for the sake of this example we are not going to elaborate on what constitutes a valid input for each field, but in reality the PM must specify those details).
– The PM creates three mock-ups for Web pages.
– Next he attaches them to the spec as pictures.
– Finally he prints them out and tapes them to the wall in this order:
Page 1-> Page 2-> Page 3
Mock-ups can have different degrees of abstraction; it’s okay not to include elements of the interface that might have no relation to the spec. For example, in the case of mock-ups for registration we might not be interested in seeing the images on the Web pages.
The problem with mock-ups is that their purpose is to show user interface. Mock-ups usually give little clue about the logic behind that interface; i.e., about the algorithm of the program. To fill that gap, we use process flowcharts.
Here is the registration in the form of a process flowchart:
Flowcharts can be created by both the PM and the tester. But no matter who the author of a flowchart is, it’s usually a good idea to include it in the GLOBAL SETUP and ADDITIONAL INFO section of the test suite.
Microsoft Visio is a professional tool to generate flowcharts. You can download a trial version of it -just Google it. You can also create flowcharts using Microsoft Word.
Examples, mock-ups and flowcharts (let’s call these sisters “EMF”) help to:
– prevent software bugs,
– find bugs in the spec
by the following ways:
– The EMF is a description of the subject from different angles that helps different people to better comprehend the subject.
– The EMF creation is a process of rethinking, and rethinking leads to finding errors, i.e., bugs in the spec.
– Mock-ups and flowcharts are visual presentations, and in many cases they allow us to literally see spec errors with our eyes.
Since you’ve heard about mock-ups, but haven’t seen them yet (the purpose of this was to let you feel the difference between reading specs and seeing specs), let me introduce you to the mock-ups for spec #1111, “New User Registration”
Mock-up of Page 1
Mock-up of Page 2
Mock-up of Page 3
Bonus: Mock-up of Page 2 in case of invalid data for email field.
You can see all these mock-ups in action if you try to register on www.sharelane.com!
The mock-up of Page 2 and the bonus mock-up of Page 2 contradict the instructions found in the textual part of the spec:
– Textual part of the spec: “Last Name” is required field.
– Mock-up: There is no indication (asterisk “*”) that the “Last Name” field is required.
Congratulations! We have just found a typical spec bug. And we also saw another illustration how internal conflicts within specs can produce bugs.
If you find a spec bug (remember that EMFs are parts of the spec), you have to file a bug report that requires the PM to fix the problem. In our case, either the textual part must be fixed to be in accord with the mock-ups or vice versa.
BTW, here is what I’d recommend for the bug report summary: “Spec1111: internal spec conflict: not clear if “Last Name” is required.“
Note that we put the spec ID at the beginning of the bug summary. Later on you’ll find out why this is a good practice.
To conclude our short introduction to specs, I’ll leave you with a good idea.
Each software company usually has an Intranet, an internal network for company workers only. The Intranet usually has a Web site for internal information sharing where insiders can:
– read about the ethical standards of the company;
– see pictures from the last party when somebody drank too much beer;
– view instructions of how to set up a wireless access;
– read scary stories about the unfortunate destinies of PMs who secretly change approved specs;
– see contact info of each employee;
– read/see/view/create other useful stuff.
So it’s a good idea to publish ALL specs (from the past and the present) on this Web site. The easiest way to do it is to install some free Wiki program, like MediaWiki (http://www.mediawiki.org) on this Web site. With MediaWiki, a PM can easily create a Web page for every release and place there links to the files with the specs.
There is a free macro called Word2MediaWikiPlus (Google it) that you can use to convert documents from Microsoft Word (with tables, fancy formatting, etc.) to the MediaWiki format. The benefits of converting specs to the Microsoft Word documents into the Wiki format are these:
– We can use an internal MediaWiki search to search inside all converted specs.
– Some developers (e.g., Linux purists) refuse to install Microsoft Word on general principle.
In the future, when I refer to “Wiki” I’ll be referring to an internal company Wiki.
Don’t be shy to report bugs that you find in the specs. If your PM doesn’t understand why you are doing that, explain to him that
– bugs seeded in specs can be transferred into the code and test cases;
– bugs found earlier cost much less than bugs found later (we’ll talk about it in a minute);
– finding and addressing bugs found both in the code and the specs is not your choice, it’s your responsibility.
If your PM has a problem with that even after you explain the three points above, redirect him to your manager, and let your manager deal with the situation.
As you already know, specs, and sometimes ideas for specs, can be buggy. That’s why it’s always a good idea for testers to attend product discussion meetings. The sooner a tester is involved in the Cycle, the better it is for the software. If the PM tells a tester that production discussion meetings are none of tester’s business, that tester should have a really serious talk with that PM’s manager. The tester’s profession is somewhat unique, because quality really depends on EACH participant of the Cycle; in other words, quality is a consequence of a joint effort. So, when a tester gets involved in stages other than “Testing and bug fixes,” it’s a totally natural thing.
BUT, even if a test engineer is actively involved in broader quality topics, the major part of his work is to find bugs in the software code and address those bugs. As you know, bugs can come from specs, and it’s great to prevent/detect bugs before the “Coding” stage! But the product we deliver to users is not specs, but a software code, and that’s why the code to be released is the main focus of tester’s attention.
The next stage of the Cycle is Coding. Coding is performed by developers while testers write test cases to check the code. Next ->
Lecture 4 - The Software Development Life Cycle -> Quick Intro -> Idea -> Product Design -> Coding: Part 1