The Product Management lead says “No one has ever wanted the code to do THAT before. We never designed for that scenario. That’s not a bug – it’s a new feature. The customer will have to wait for an enhancement release. We can’t put enhancements in a maintenance release.”

“But”, argues Tech Support, “the customer is saying that’s a common business practice. That our software should already be doing it and without a code change they will be getting the wrong information and can’t rely on the product. It’s a big deal.”

What to do? Customers don’t want enhancements in their ‘bug fix’ maintenance releases else it makes it difficult for them to quickly and easily upgrade. On the other hand, is this an enhancement if what is being asked is what customers would expect it would do? It wouldn’t be right to classify it as a bug – bugs mean the developers made a mistake and go against their metrics.

There’s a simple solution – add a third classification to your tracking system.

• Bug for true defects – code that doesn’t match the spec.
• Enh for enhancement requests – new features to be spec’d.
• Gap – Add a new classification for the in-between customer requests. We call them “Gaps”. They are holes in the spec, gaps that the Product Manager forgot or didn’t have enough information about to add. But they are items customers consider a bug.

Having a third classification lets all of the groups agree on how to position customer complaints/calls without having arguments.

• It’s in the spec but not the code – it’s a bug.
• It’s not in the spec and definitely a new feature/request – it’s an enhancement request.
• It’s in-between? Those that everyone used to fight about. Is it a bug so it gets top priority fix? or an enhancement that needs to wait for the next major release? If neither, it’s a gap. It can be in a maintenance release or enhancement release. It wasn’t the fault of the developer. The code is correct. Engineering and Tech Support don’t need to battle it out. It’s simply a gap.

Bug/Enh/Gap – BEG. Having three classifications stopped the arguments and clarified who’s responsible for the fix. Even more importantly, if only true bugs are classified as bugs, real developer mistakes where the code doesn’t match the spec, then developers take more responsibility for fixing those when other items (holes, missing specs, new features) aren’t incorrectly classified as bugs. Having three classifications encourages accountability and accountability encourages better teamwork.

You won’t have to “beg” any more.

That let us clearly specify customer complaints as Bugs (don’t match the spec), Enhancement Requests (not in the spec) or “Gaps” (maybe should have been in the spec in the customer’s eyes but were missed. Or spec ambiguities.) That saved us a lot of discussion time in our SDRB (Software Design Review Board) meetings where we reviewed the issue clients and internal support people had with the product. Bugs were things developers missed – the onus was on the Development Managers. “Bad Developers”. Enhancements were things we put in the next major releases. Obviously not negotiable for maintenance releases. Gaps were negotiable but there was no blame on the developers – so yep, good idea, let’s move on it. Meetings were clear. No contention.

So why didn’t everyone want good, ‘as built’ specs?

I was surprised when some companies thought they had ‘as built’ specs – only to find what they were referring to were documents an external tech writer group wrote after the software was released. Those aren’t “as built” specs as much as they are “what we think was built” specs. Since the developers didn’t code to them and QA didn’t test to them in the initial release, they are, always suspect. Those documents are never valid, correct. I would question if any company devotes enough time and money to guarantee that kind of ‘after-the-fact’ documentation is correct.

Whereas it’s so clean and clear if the spec is used as part of the development process and then as part of the QA process that it “IS” the “bible” of the code. How the code was developed. What the code does do. If you have specs like that, you know what’s in the code. Tech Support knows what the product does. Everything is clean. Clear.

But I’ve come to realize that there are roadblocks in companies to why this isn’t as easy as I assumed. But I think I have a solution and am working on it. It’s very cool. I’ve realized that there are real reasons why people feel it’s hard to maintain real as-built DOORS-type specs. I, as a manager, was willing to do the extra work to have as built DOORs specs because I saw the value. But not everyone is as dedicated to the end result.

There has to be a better way.

I think there is … stay tuned. We’re calling it Software 2020 – a software tool for the 21st century “:-)”

My first reaction to this is “What? Trading off Quality?” What does it mean to have a Quality “slider”?

In my years of software management, I’ve always believed there’s “3 fuzzy peas”, not four (the 3 P’s that drive a software project: Plan, People and Product. See my blog on Fuzzy Peas). Related to the sliders above, Plan=Time, People=Budget, and Product =Scope.

The first slider above, Stakeholder Satisfaction, I believe comes from delivering a quality product on time with the features they deem valuable. Team Satisfaction comes from working in an environment where your work is valued by the customers. I don’t think those really are project “sliders” although I imagine someone could argue for some usefulness in having them discussed by the project team.

On the other hand, “Quality” isn’t an item to be traded off.

I was happy that in Mike Cohn’s Blog, in every example the quality slider is always in the middle, at “3″. That makes sense – there is a middle ground on ‘reasonable’ quality. You typically don’t need to run a battery of tests that takes every possible path through the system regardless of how obscure it is. I’ve agreed to let a release go out when there was a potential bug in a place a user could only get to if the moon was full, they stood on their head and typed ‘MeMeMeMeMe’ 5000 times in the input box. Well, maybe a little easier to get to than that but some boundary test that goes far beyond any reasonable business case. Or a low-level issue (typos or an issue only an admin user would see and could easily work around). I suppose some could argue those are still ‘bugs’ in the code. Those bugs we list as 3-Low/3-Non-Critical and move them to the “Future” bucket. If we ever run out of work, a someday clean-up pile. On the other hand, if no one will ever encounter them, probably not worth messing with the code to fix them. Every code change is a potential new bug, they say.

But that isn’t what I think when I see a “Quality Slider” on a screen. I think that people may think they can actually move it off of the centerline “3″ position into a lower-quality setting as an up-front project “trade-off”. This isn’t a tool used at the end to help figure out how to get an overdue release out-the-door, it’s an up-front tool. “Let’s add these 3 additional features and we’ll deliver it with a few more bugs.” Yikes.

And I fear (I know) it is common in the software industry to do just that. At Azerity and other places I’ve worked we’ve had a zero-bug policy for releasing a release. Every bug that was identified and classified as a potential user issue had to be resolved and tested in order to release the product. We of course also had an ‘exceptions’ clause (in business, one has to be sensible) and if there were one or a handful of issues found at the very end of the test cycle that were not deemed to be likely to cause any user real problems, or if it may only affect, say, one admin user who could be counseled how to avoid it until a fix were released, we had a sign-off process for those. But, believe it or not, that sign-off wasn’t needed in every release or even most releases. With an appropriate “Plan”, schedule (sufficient “People” for the Plan) and reasonable new features or “Product” size (the 3 P’s), you shouldn’t ever consider quality as something to be traded off.

What does it mean to “slide” the quality slider to the the left (lower quality), from a ’3′ to a ’2′ or even a ’1′? If you ship software with known bugs that clients will find, it impacts tech support, causes escalation issues, client dissatisfaction, and costs more to fix later.

What’s the cost of bugs in delivered code? It’s a proven software fact that if fixing a bug when found in the current release takes the developer an hour (say $100), if instead it’s found by QA it’s $1000 (QA test time, goes back to development, potentially other code is impacted, code re-checked in, re-tested – at least a day total). But if found by the client it could easily end up $10,000 or more. (Tech Support time, trouble-shooting, reproducing it on in-house systems, getting developers on it – diverting them from their work, pulling the old branch to their dev systems to fix, merging code if other changes have occurred since). Ten-fold increase in cost for each development phase the ‘bug’ goes through without being caught. (That is also the argument for good code reviews, unit tests, and skilled developers).

I can see an argument for saying the Quality slider moves right for FDA or satellite software (you often can’t fix ‘bugs’ in space). But that is more of a company-wide process issue (how is the program run, what types of tests are required for delivery), not a Agile project-by-project team “trade-off”. So I still don’t see a reason/purpose for a “Quality” slider.

What bothers me with having “Quality” as a slider is I’ve been in companies where quality actually “is” considered a slider. I’ve been in meetings where engineering VP’s actually say “well, you can’t deliver code without bugs”. People I’ve worked with retort “of course you can – we’ve always done it.” But too often it seems to be a common software industry belief that software inherently has to have bugs. In my experience, that isn’t the case. There needs to be a customer outcry against shoddy software deliveries.

I think having a Quality slider is wrong. While it’s true that in real life quality does get compromised. Requirements keep morphing until there’s no time to finish the job, engineering over-designs software beyond the requirements and then can’t deliver, or management doesn’t come up with the people needed to meet the schedule but the schedule doesn’t move. In those instances, often, as the deadline for releasing the product is fast approaching the decision is to “Ship as is – we’ll fix the bugs in the first maintenance release.” That’s always the wrong decision.

The right approach is to continue, throughout the project, to manage the P’s – Plan, People and Product. If the schedule (Plan) is the most important part and at some point the people you have are all you will have (at some point bringing on new bodies doesn’t help due to ramp-up time), smart managers will start cutting out functionality – quickly. I was always quite draconian with my red pen if releases looked like a release was in trouble. Reduce the load and save the schedule. Or negotiate for more schedule. But that’s at the END of the project cycle, not during the planning phase.

Up front, where the project sliders are used, the test plan needs to be appropriate for the amount of code being implemented/modified.

Quality isn’t a “Trade-Off”.

It reminded me of the decision matrix my husband and I built when we were debating whether to move to Charlotte, North Carolina or not. We were living in Silicon Valley where we moved after college and had lived for several years. Our best friends had moved out from the University of Utah ahead of us and we joined them. We (my husband and I) both had jobs with Ford Aerospace and the company was starting a division in Charlotte to apply a technology built at Ford Motor for finding flaws in windshields – to apply that technology to the textile industry. To find flaws in cloth.

Mike had been offered the job as Finance Manager working for the new company division’s General Manager. I was given the opportunity to work part time (as I had been doing since taking maternity leave) as software developer. There were only a handful of new employees. A start-up opportunity.

So we crafted our decision matrix.

• Friends
• Area (The south – humid and unknown; California – wonderful)
• Work opportunity (would mean an immediate promotion for Mike)
• Family (ours were all in Utah – NC was much further away)
• Monetary (better salaries were being offered; particularly considering cost-of-living
• Etc.

We weighted (added relative values) to the categories, evaluated them, and added up the results. The results: Don’t move to Charlotte. We sighed, looked at each other. Mike said “But what do you want to do?” I said, “I want to go and give it a try.” He said, “Me, too!”

And off we went. It was a great decision. We met great new friends. Saw an area of the country we never would have. Learned about the South. And our youngest daugher was born there.

All the tools for making decisions help – but in the end, also consider your “gut” reaction. In the end, how much do you want it?

If you REALLY want that feature that the decision matrix says is too big or has other constraints, rather than removing it from the list, a better alternative is to find a cheaper way to deliver the function that’s more streamlined. Maybe your development team’s approach is more “elegant” or “robust” than this feature requires. Maybe all the client wants is a simple button and the team was suggesting an entirely new feature.

An important part of the decision criteria is weighing the technical options. If you want the feature badly enough, there may be a way to get it that is more streamlined and still fits into the plan.

One young Army guy got up to talk about the list of change requests and why they were needed. He listed as a top priority changing the queuing algorithm. Humm. It seemed to me that there were a lot of other items on the list that deserved more attention.

“Let me give an example,” said the Army guy.

“One day we were monitoring communications when all of the front-line systems were attacked. Everything went off-line. The PDP-11 also went down. We brought it back on-line and it started processing messages from the queue.” (This was Desert Storm, remember.)

“A half-hour later it got to the last message that had been posted on the queue. ‘Incoming SKUD!’ It would have been really nice”, he said, pausing for the irony to sink in, “if that had been the first message we received instead of a half-hour later.”

Incoming SKUD? Ah, input received. While the system wasn’t designed for the front-line it had to fill the role when front-line systems went down. Wow. OK then. Priority 1! Change the queuing algorithm!

Sometimes it isn’t clear why clients would want changes and enhancements. It certainly helps to understand your customer!

The Best Reward

While I worked with the Lt. Colonel, I tried hard to understand things from his perspective. It made sense how upset he was with our “perceived” software coverup when one realized he was on his way the next day with the software to Desert Storm and his soldiers depended on our software. That’s a lot of pressure.

A few years later I accepted a job to ASK/Ingres, leaving Ford Aerospace after almost 20 years. The Lt. Colonel was in town for a review meeting and was told that I had resigned. Before our meeting, he caught me in the hall.

One of the initial tasks on his project before I’d come on-board was to convert the software from the Ingres database to Oracle. He stopped me in the hall to say he was glad we had a chance to work together and said “Maybe we went the wrong way” (meaning from Ingres to Oracle instead of visa versa since I had selected to work at Ingres). Having this stalwart army customer believe in my decisions was one of the best indications that I had been hearing the “Voice of the Customer”.

Huh?

That’s a good example of a team that needs a good process. And he wasn’t the only one in the room waiting for an answer. I learned the answer to that question in the early ‘80s. And the lesson was a hard one. ..

I had just been assigned as manager for the Electronic Defense Systems software department for Ford Aerospace. It wasn’t my first management job but was my first position responsible for government customer deliverables rather than internal projects like developing in-house CASE tools or complex algorithms to help the engineers building satellites and ground stations. The five software sections I would manage were each working on separate contracts for different arms of the military. I had met the five supervisors in my new department and their developers but hadn’t officially started work when my boss, Sharon, who headed up all software engineering for Ford Aerospace came to me and said that the customer for one of my new contracts, an Army Lt. Colonel, was going to be giving awards for completing the testing of the release and wanted me to come to the awards ceremony to meet him and see the team get their awards.
It was about 5 PM as we walked across the campus. But as we started up the steps to enter the building the doors opened and young men and women, the developers and testers, came streaming out and down the front steps with tears in their eyes or outright sobs.

“What’s going on?” asked Sharon.

They couldn’t answer and ran by us. The company’s General Manager was hurriedly entering the building. He saw Sharon and said sternly “I was called to a meeting with the Lt. Colonel. You’d better come with me.”
We three went upstairs into a warehouse room where an impromptu meeting was being held. The head of Systems Engineering, Ray (Sharon’s boss) was already there with the Lt. Colonel. The Lt. Colonel was a tall man in full army fatigues. Red flat-top hair with a face as red as his hair. He was livid.
“I normally only give companies one chance. But for you”, he said glaring at our GM, “this is the third strike.”

He saw me and said “Who’s this?”

Sharon told him I was the manager of the software group. He glared at me and said “How are you going to remedy these problems?” Sharon, to my relief, quickly let him know it was my first day as manager. He directed us to find out what was wrong and get it fixed that night or Ford would never have another contract with his division. But, he said, if we want to re-run the test scenarios he was willing to spend the night here but he had to be on a plane, with the verified software by 8 AM in the morning. Sharon said we’d find the problem and run the tests.
We went to the supervisor’s office. The supervisor was a tough, seasoned, ex-Marine used to conflict and discourse, was also crying and said “This is it, I’m through. I quit.”

“What happened?”

“We started the test scenarios and the first test was simply adding a new user. There was a system error. The SETA (Systems Engineering and Technical Assistance) contractor quickly jumped to the conclusion that the code wasn’t complete and we must be hiding problems and issues. The Lt. Colonel blew up, yelled at everyone, and they left in tears. I don’t understand it. We worked long and hard on this release and the tests we ran were perfect.”

A senior programmer, one of Ford’s best, appeared in the doorway. “Excuse me,” he stammered. “I’m afraid I know what is wrong.”

Seems he, at the last minute, had noticed a small issue in the software. Although he was well aware that the process was to first notify the Configuration Manager (CM) before changing anything, and this change wasn’t even needed for this delivery, he thought it was just a simple quick fix. Unfortunately, he failed to realize that that the code was shared by a newly implemented user registration function and his change broke that function. He had reverted the code to the prior version and was sure it would now pass the tests.

The team was rounded back up and were all more than willing to spend the night re-verifying the tests to exonerate themselves. In the morning the tests had all been passed with glowing colors and the Lt. Colonel at 7 AM left the awards to be passed out to the team later in the day.

Ironically, the senior developer who caused the issue was the one who was scheduled to travel with the Lt. Colonel to install the software in Saudi Arabia. The LT. Colonel seemed to take pleasure in telling him before they left that he’d need to shave his beard. “What?” the developer complained. “Well, it’s up to you, but the gas masks don’t fit well over beards.” This was Desert Storm. He shaved.

A good process needs to be both easy to follow and so integrated into the workflow that it’s second nature. It isn’t a burden, just a simple step in the normal activities. And developers have to “buy in” that it’s required, important, and a step that cannot ever, ever be skipped. The issues caused may not be as significant as the story above, but if changes are made to code without a process, there will be issues. This is true for all projects – from major defense software down to little start-ups.

The process we implemented at Azerity was that our SD Tracker tool was the tracking system for every change. Every change to our requirements docs or code needed to be an “SDR” in SD Tracker. Adding an SDR was quick and easy. If a developer wanted to change code for any reason, all they needed to do was enter an SDR saying that. Of course the development managers had guidelines about when and which developers could act immediately on their desire to change other areas of code and when reviews or other conditions were needed to be met. Then QA knew it needed verification and we could confidently tell our clients that our Release Notes listed all areas of code changes which helped reduce their SOX testing on maintenance releases.

Interesting since I’ve been thinking a lot lately about the tortoise and the hare. You know the old adage – where the hare is fast and quick to the finish line but the tortoise wins the race. Initially one has to think about the “Agile” (i.e., hare-like, fast and hoppy) software development methodologies vs. the old school “Waterfall” methods. Yes – the waterfall methods were somewhat like a tortoise but they were worse, more like a tortoise that had to stop every few steps and wait for the gate to open so he could continue on to the next phase of the journey.

The problem I have with “Agile” technologies is the somewhat “gleeful” rejection of any and all documentation. “We are going to be a small team so we’ll just have discussions and come up with the right answers as a team.” Yeh, right. What happens when you need to do updates to your software. Is this “real” software that has users and a next release? What happens then? How does anyone know what the software actually does if it was designed and developed by committee and no document artifacts remain that accurately reflect the software “as built”.

“As built” documents are key to (1) accountability (for marketing, developers, and QA) and (2) an understanding of what the software is supposed to do so that knowledgeable changes can be made and (3) resources so that Technical Support/Customer Services can answer the call about “Is the software supposed to be doing this

I don’t think “Agile” is “Practical”. See our Requirements Management blogs for better ideas about how to really be quick-on-your-feet, focused, and develop high quality and low-cost software !

It’s really an architectural marvel. Such a beautiful design but was quite a construction feat. We took the tour and found out about the history of the building. There was a competition for the design and the design selected was really only a rough sketch. The shells of the competition entry were originally of undefined geometry, but early in the design process the “shells” were perceived as a series of parabolas supported by precast concrete ribs. However, engineers were unable to find an acceptable solution to constructing them.

From 1957 to 1963 the design team went through at least twelve iterations of the form of the shells trying to find an economically acceptable form (including schemes with parabolas, circular ribs and ellipsoids) before a workable solution was completed. Utzon came up with an idea of making all the shells of uniform curvature throughout in both directions which was called a eureka moment.

The idea was that the shells were developed according to a spherical geometry providing a common denominator, the same spherical surface to deal with, with a similar curvature throughout. This was an elegant solution to a construction, which would otherwise have had to be done with a large amount of scaffolding and shuttering, both for the interior and exterior shape of the shells. Now the shells could be sub-divided into ribs, which again could be divided into smaller elements, which could be cast within formwork representing the largest rib-entity. Thus it was possible to pre-cast the concrete-shells in smaller pieces and assemble these pieces on location. Because of the simple and consistent mathematical principles that were applied to the design, construction was both possible and much easier and simpler than it would have been if they had continued with the original parabolic concepts.

Software architecture also benefits from simplicity of design. A simple, uniform design reduces development time, improves maintainability, and makes modifications quicker and easier.

Often developers and software architects think they have an “elegant” design because they have tried to design very generically and/or very object-oriented, used a lot of open software components, and/or tried to plan for yet undefined requirements. But often the result is software that is much more complicated and bulky than needed. Over-designed, bulky software is costly to develop and maintain.

How can you tell if you truly have a good design or not? Here are the five keys to good software design:

1. Is there a simpler approach? In practice, the simplest approach is always the best. This goes against some software architect’s instincts when they feel they need to address unspecified requirements, but if the requirements are not stated yet, second guessing, if it adds complexity, should be avoided. If there are implementation strategies that are smart and brainy but overly complex, scrap those also. Keep it simple.
2. Is it customer-focused? Often design trade-offs are made that make the developer’s life easier but impact the customer negatively. If there is no benefit for the customer, the code should be removed. Less code is always better. (This does not include features that improve maintainability or delivery since they will affect the customer positively. But does include features or technology choices or functions that only make the life of the developer easier).
3. Is it designed for the expected user base? Often developers expect users to be as technically savvy or computer-adept as they are and inadvertently implement software that is not accepted by their user base. This was much of the cause of the downfall of Seibel – what the software did was great. The companies that implemented it though just couldn’t get their sales users to use it regularly. Hence the value of capturing important sales data was not realized. This is particularly true for software that users will need to pick up and use without the benefit of formal training classes. Or for users who don’t use the software very often but need to be able to just sign on and quickly get their job done. Or for users who have other limitations. Remember the old adage “Know your users” and take it to heart.
4. Was performance considered? From top to bottom, software design should always consider the end performance. Performance should be a factor in basic architecture principles as well as 3^rd party tool selection. Nothing impacts usability more than bad performance. Except bugs.
5. Is it reliable, maintainable, supportable? Quality: Clean, simple software tends to be more reliable because there’s less that can go wrong. In the software industry, often there’s complacency about bugs – some people think software always has bugs. Typically though bugs are a result of overly complex design, large/bulky architectures, which result in not enough test time. Simple, clean designs take less time to develop and less time to test. Installable/Upgradable: Especially for applications that need to be installed at a client site, the initial installation and ongoing conversions to the latest releases need to be quick and easy. Desktop software is often quite good at automatic installation and updates; but surprisingly enterprise application software typically needs to be hand-crafted and customized on-site. And each conversion to a newer release can cost companies millions of dollars. There is no real reason why enterprise application software should not be easily installed and upgraded. No customer-focused reason anyway. Although vendors do make more Services and Consulting money that way. Reliable: Most software nowadays, especially enterprise software, quickly becomes mission critical and companies who rely on it need it up and running 24 x 7. That means it must have high quality, be quickly upgradable, and be scalable to meet a company’s growing needs.

Good design separates clean, customer-acceptable software from gorilla software. Why is good software so hard to develop? Companies delivering clean, customer-focused software may not make millions in services fees, but some day (hopefully) customers will start pushing back on the software gorillas who charge millions for every major upgrade. When that happens, companies who know how to develop clean, simple software will be in high demand.

History of enterprise software according to Jan:

• 1970s – Large companies develop their own internal Manufacturing Resource Planning and Finance systems to meet their specific needs. Because these are one-off projects, the cost to continue to address new requirements is costly; many systems become out-of-date and/or costly to maintain.
• 1980’s – Software vendors begin delivering MRP and Finance solutions and some Legacy (internally built) systems are replaced.
• 1990’s – Software vendors combine various application solutions (MRP, Finance, HR, etc.) into one Enterprise Resource Planning (ERP) software package – one size fits all – and more Legacy systems are replaced. The ERP solutions try to address all automation for every industry with a single software offering. Thus the software requires huge customization efforts to meet each company’s needs; installation and upgrades costs increase. Specialized “Systems/Consulting” companies are formed solely for the purpose of installing, customizing, and upgrading the large platform software.
• 2000’s – Software vendors consolidate into a few mammoth gorilla vendors. Large software infrastructure layers are developed to integrate all of the various application pieces from the acquired companies into one single “platform”. Systems became even more complex; software costs for installation and maintenance continue to rise. A few smaller vertical-based vendors still provide clean simple software but competition with the gorillas is fierce. CIOs are convinced by the gorilla software vendors that enterprise software needs to be big and needs to sit on monolithic platforms in order to “integrate” and be “enterprise-worthy”. Yet few, if any, CIOs are able to realize the promise of easy integration using the big monolithic platforms, even if they stay with a single vendor. Implementations and upgrades take years and millions of dollars to complete.
• 2010’s – Companies reject the big vendor approaches. They refuse to pay millions of dollars for each installation and upgrade. Clean, simple software is demanded. The software industry evolves to meet the need.

I was lucky enough during the early ‘80s to have a prime job managing the company’s technology software department which included Research & Development projects in interesting software areas such as Artificial Intelligence, Computer Aided Software Design, and Software Security.  A group of very knowledgeable PhDs worked on the Trusted Software Security project.  They had been working with the government and with Sun Microsystems for several years, pushing the envelope on secure software and had been awarded steady R&D contracts for several years in a row.  The PhDs were well-known in the security circles, often asked to gave briefings at software security conferences.    

At a couple of conferences in a row, they’d encountered a young software engineer who they were very impressed with but who lacked the educational credentials to typically be hired into such a the team.  But they were all so excited by this young man’s abilities that they convinced me to hire him as their assistant with the thought that they’d over time convince him to return to obtain his PhD. 

So Mark, our new Asian security engineer, started working for the team.  He arrived at work wearing the T-Shirts and jeans he’d worn on campus at UC Berkeley.  On one of the first days he was on-board, I spotted Mark at the other end of the aisle of cubicles as I walked towards my office.  But it wasn’t his T-Shirt and jeans that caught my attention,  it was his shock of bright orange hair.   I veered into his supervisor’s office. 

“Did you see Mark today?”  I asked. 

Chagrined Dave said “Yes, orange.  I already talked to him about it but there’s no customers in today so I just told him to wash it out tonight.” 

“Humm,” I muttered and went to my office. 

I didn’t think much else about it since the next day Mark showed up with his normal, although somewhat long, black hair.  And the team’s research was going very well.  They were working hard, long hours but were making great progress.  Then came the day for the big customer review.  An important day to determine how much R&D funding would be awarded for the next year for the project.

The team had decided to have Mark give the demo – he was quicker at the keyboard and the demo flowed very well when he gave it.  I said they’d need to be sure he was dressed appropriately and they said they’d already spoken to him about it and one PhD had given him a tie to wear and Mark had described an appropriate shirt already in his closet.

The day of the demo I arrived at work and, walking to my office, spotted Mark out of the corner of my eye and marched directly into Dave’s office.   Dave didn’t even dare look at me.

“I know, it’s purple.”

Yes indeed – Mark not only was wearing his normal T-Shirt and jeans, today his hair was shocking purple.  Bright purple.  But it was too late for anyone else to learn the demo.  And the Customers, Army Intelligence Officers, had already arrived and were waiting in the conference room.  So nothing to do now but wait for the reports of how it went.

Later in the afternoon the head security PhD came into my office beaming. 

“It went great!”  He said.

I was wary.  “And what about his hair?”

“The customers certainly looked shocked when he entered the room.  But once Mark started in on the demo they forgot all about it.  He was so knowledgeable and answered all their questions with ease.   I’m sure we’ll get our funding next year.”

“But you’d talked to him about his clothes and hair – why did he show up that way?” I said, still concerned that he may just be rebellious which would eventually cause issues. 

Mark had told them that he’d gotten up that morning and put the shirt and tie on, looked in the mirror and felt so out of place and nervous he didn’t think he would be able to give the demo or face the customers.  He panicked.  He was so ill at ease in the uncomfortable clothes.  And whenever he dyed his hair, he felt his shocking hair diverted attention which made him feel comfortable and at ease.  He was so worried about not doing a good job that decided he had to show up looking the only way he felt confident.

The security project was expanding and we’d hired a woman PhD from the East Coast.  She came to start work while her husband and two teenage sons remained back East to wrap up the sale of the house, packing and moving.  One afternoon after a week at work she came into my office looking very upset.  She told me she had just gotten a call from her oldest son and that her husband had had a heart attack and died.  She was worried that she didn’t have any vacation and had just started work.  I assured her that she didn’t need to worry about that.  To go back East and take all the time she needed – that her job would be waiting for her.  I asked her if she needed anything from us and she said she wondered if she could use her office phone to make plane reservations (since at that time calls outside the building were not allowed) but of course, anything she needed.

I stopped by her cubicle during the afternoon and she said that the airlines were very sympathetic and working with her and that she said she’d gotten a flight for that evening.  Mark was in her cubicle helping her – he’d asked Dave if he could make sure she had a flight.  The next day I learned more.  Mark had insisted on driving her home, worrying that she may be too upset to drive safely.  He had cooked her dinner, helped her pack and driven her to the airport.  I then realized he’d jumped in and done more for her than anyone else at the company had – he had shown real compassion while I had been judging him on the color of his hair and clothes he wore.  And I said to Dave, “Tell Mark he can show up with any color hair he wants.” 

Prejudice against purple hair seems like such a small thing but most of us have many prejudices.  Growing up in Utah, I had been prejudiced against blacks without knowing it.  I recognized my prejudices in college and worked hard to overcome them.  One day shortly after I started as a software engineer at Ford Aerospace, I was talking to someone about three Philco computer engineers I met and someone asked me “You mean Emery, the black engineer?”  I had to stop and think because I wasn’t sure any of them was black.  The next day I looked more closely and sure enough, Emery was black.  I was so proud of myself that I hadn’t even noticed.  Now Mark had taught me to also not judge by the color of one’s hair.

When Barack Obama was born, many states considered his parent’s marriage, marriage between a black and a white, illegal.  When we lived in Charlotte, North Carolina in 1978, our company’s black engineer and his blond wife would be yelled at as they walked together down the street or worse – bottles were sometimes thrown at them from passing cars.  They eventually had to move to Colorado where the prejudices weren’t so strong.  

Jumping to November 4, 2008.  Such a wonderful day – where America showed that we have all gotten over so many prejudices during the years.   A day of change, a day where racial prejudices have been set aside,  at least in one of the most important arenas, the Office of the President of the United States.  Yet on the same day California, the most progressive state in the union, voted “Yes” on Prop. 8 to add discrimination to the state constitution.  How ironic that we take one huge step towards acceptance and equality and one huge step backwards.   

Hopefully it won’t be too many years before we can mature to also accept gays and lesbians and their desire to be married and accepted into the mainstream.

All agreed that design documentation maintenance is an unattainable goal. Some were engineers from a big major networking company, one from a mid-sized software company.

But the advantages of having a real “As Built” spec seem so obvious. A spec that is always updated before code changes are made, that is used by QA for testing and used by Tech Support for customer support and questions, a spec that unquestionably contains the use case scenarios and business algorithms implemented by the code. The advantages of having such a spec is so key to producing clean, quality code and so necessary for clear communications between the developers and the customer advocates (Product Marketing, Tech Support) that it seems to me an obvious requirement for effective software.

Yet these software professionals were in agreement that maintaining such a spec is not feasible. Perhaps I shouldn’t have been surprised. When interviewing candidates recently for a VP of Engineering position, I repeatedly found each candidate had a similar story – whether from a small start-up, a major application vendor, or somewhere in-between – each said they had never found a way to successfully document and track requirements to design to code. It wasn’t feasible, each said. Plus others I knew from a mid-sized software application company had same opinion. Product Marketing creates the Marketing Requirements Document in Microsoft Word. Engineering takes that and creates the design and then codes. At the end of the cycle, although the PM team attempts to maintain the MRD in-sync with the code, they say it isn’t ever really possible. Plus because some MRD documents describe enhancements to existing modules, they are “change” documents, and after a few releases there was no complete document defining the complete feature. One solution companies have tried is to assign the task of writing an “As Built” document to the Technical Documentation team after the code is released. Seems like a good idea? It would only be valid if the document were thoroughly tested by QA but that would require double-testing so is never done. Hence it’s only the tech writer’s best guess at specifying what the code is actually doing.

Yet I still thought these companies were anomalies. Even though, my friend and consulting partner, Anita continually encounters the same feedback from the students in her UC Santa Cruz training courses on requirements management, it seemed that these companies must not represent the majority. Surely most companies must have found the solution. Because the solution was not that hard to find.
But to hear again this weekend the wide-spread belief that maintaining design documentation isn’t viable me stop and take notice. I know the “Agile Software” community discusses the advantages of relatively sparse use of documents. But seems to me that the discussion is at the wrong level. By eschewing documentation we are losing a key component of an effective software process.
And what I’m advocating doesn’t need to take more time or effort. In fact, just the opposite. There is a level of documentation that can be easily maintained, aids every organization throughout the software company, and should be as much a part of a normal software development cycle as configuration management tools are. (Hopefully no one reading this blog would tell me they do not believe in checking software into a configuration management tool). Maintaining real, code-synchronous documentation is feasible and just requires the right tools and corresponding processes.

Yes – it’s an easy problem to solve. At Azerity, my company, we proved that having the right process and not only were feasible, the result was reduced headcount needed to design, develop, and maintain code. It was actually amazing at the size and complexity of software we were able to deliver and support with so few people. And a key component was the concept of complete, “as-built”, tested specs describing each application module. These specs became core to our company, our software bible, the key to our IP, and only the code itself was more revered and protected.

Our journey – how we got there. For the first few years as a start-up, we had effective processes for our size company because we had implemented, from day one, our Tracker tool (see Tracker tab) which was much more effective than open source tools like Bugzilla, JIRA or their equivalents. For a team of less than ten with an application still small enough that key individuals could grasp the entirety of the product in their heads, we were able to implement and enhance the application effectively using only SD Tracker, CVS for code management, and MS Word for specs.

But then we got larger quickly as a company and the application grew. We doubled the engineering team. With plans to double the engineering staff once more we had a major expansion of new modules and enhancements being designed by our new Product Marketing team. We were becoming a real software company.

We hired a VP of Engineering and I took on the CTO position. Her first observation upon arriving was that using MS Word for specs wasn’t going to continue to be viable. And it was quickly apparent that she was right. We had a new Product Marketing team that were making spec changes, the developers were having difficulty tracking what changed from revision one, two, three of the Word docs. Some companies try to handle this by checking the Word documents into a code management system but that still doesn’t help the engineers clearly identify the delta between the spec and existing code.

Anita, our new VP, had recently completed a requirements tracking tool comparison at her prior company and Telelogic’s DOORs product (now owned by IBM) was the clear choice. We decided we didn’t need to re-evaluate tools and we purchased DOORs.

The beauty of the DOORs product is that it is similar to using Word so is easy to learn. But most importantly each requirement is automatically tagged with a unique ID that stays with the requirement even if you cut and paste and totally reorganizes the document which isn’t possible with Word or any tool that claims it can export and re-import to/from Word. Each requirement can also be tagged with other attribute columns. For example, we added a Tracker number attribute and other columns. Since DP Tracker was used for change tracking, workflow, developer and QA assignments, and ongoing developer/PM discussions, the Tracker number tied the spec changes to the developer’s work list and the rest of the software process all the way through to QA and deployment. Each time we made a spec revision in DOORs, the latest version was exported to centrally stored HTML files which all developers could access without having to own a DOORs license. Hence although requirements tracking tools are quite pricey, by only having to purchase licenses for the few key individuals that updated the specs, it was still an affordable tool. Tracker also linked to our code management system (CVS) so we had a complete, consistent tracking from specs to completed code to test. I’ve performed a lot of evaluations of similar tools over the years and unfortunately find that most lack some of the key features that made DOORs so effective. Hopefully IBM will continue to support and maintain DOORs. The IBM sales representatives seem to be pushing their Rational tool for software requirements tracking but it is missing key components we found so important.

There were two results of implemented process: (1) Because our tools were linked (DOORs, Tracker, and CVS) the result was a consistent flow from what Marketing was requesting in behalf of the customer, through design, code, test and delivery. In other words, the engineers actually built what the customer wanted and could do so with less time and energy. And (2) DOORs contained true “As Built” specs. QA tested against the DOORs specs as part of their standard testing and so the company was assured that what DOORs contained matched the actual code. Because the DOORs specs were accurate, other teams (Technical Support, Professional Services, Sales) could quickly access (via the HTML exported pages) exactly what the code did or did not do.

The DOORs specs were not design docs in the true sense of the word. No UML or lower-level implementation concepts. DOORs documented the user scenarios (screen shots and descriptive text), business functions, as well as lower-level information (business algorithms, policies enforced, and even database schema). They contained everything needed to communicate organization-wide what the software was supposed to do and did do.

And this approach simplified everything. Engineers were happy because they had clear direction about what to change when. And if a customer reported a “bug”, there was an easy way to tell if it was really a “bug” (developer mistake) or new, previously unidentified need because if it was in DOORs but the code didn’t work that way, it was a bug. Otherwise, not a bug. Code didn’t change without the spec being updated or, if the spec was found to be missing key information, the specs were always updated and tested so always both items, spec and code, were always in sync. The specs were a living, breathing documents. And this streamlined process and total consistency throughout the software life cycle has been proven to improve quality, reduce the delivery time, and enable technical support to provide better customer support with fewer people. Win-win-win.

Contact Jan or Anita if your company does not have a low-cost, high quality software process including a complete set of “as built” specifications for your code. We can help implement the Azerity process and tools at your company to help you sail smoothly through your software development cycles!