Wagging the Dog
Posted by Phillip Jackson in Documentation, System Design, TFS, Wiki on 11 December 2008
The focus of the design iteration is the document. The product of the design iteration is this document. The software is defined by this document. The estimation is created from this document. The sale is secured with this document. Client trust is established by this document. Test cases are made from this document. Who we are as a company is represented by this document.
All wrong.
The focus of the design iteration is the design. The product of the design iteration is the design. The software is defined by this design. The estimation is created from this design. The sale is secured with this design. Client trust is established by this design. Test cases are made from this design. Who we are as a company is represented by this design.
How do we communicate this design to the client? What does the client need? Let's see, the client needs to be able consume this design in its entirety and, if complex, the order in which components of the design are conveyed may need to be structured so as to build ontop of each other to communicate a larger concept, implementation or idea. A document sounds like a good candidate for this. It can be read from beginning to end so consumption of the entirety is straight forward. The order of consumption can be predicted and so the order of component description can be arranged as desired. The document is not the design. It is a representation of the design; an expression of the design selected for it's suitability to the intended audience.
How do we communicate this design to the development team? A document? Turns out that's not working out so well. In this case a document is not really the most suitable form for the audience. We have found in the past that if the design's primary medium is a document it is difficult to maintain, to modify, to update, to change, to track changes, to work on concurrently etc.
So we need to be able to express the design in document form for the client. But this form isn't suitable for the development staff. We need a primary medium for this design to exist that it gives the management, development and QA staff what they need while also being exportable to a document for the client.
We are going to try a Wiki. This should give the development, QA, and management staff the flexible, easily editable format they need while we can programmatically flatten the Wiki into a specification document for the client. Hopefully later we can get out of this upfront design and design things in the wiki right before we need to develop it. Our first step to getting there is to move from a big upfront design (BUFD) to a medium upfront design. The document format is only required for upfront designs. If the client is working with us hand in hand, then they don't ever have to read the design from end to end, they only need to focus on a single feature implementation: one wiki page.
Some advantages of the wiki are:
TFS wants to be the source for the design, but the UI is really difficult to interact with, and the navigation is worse. It is not ready to be used this way yet, so we will use the wiki until TFS is ready.
Event: Requirements Documentation
My company produces software that doesn't break. Our entire reputation is based on that. But behind that software is code that even the original authors have real trouble modifying. Why is that? All software produced everywhere is assigned a version number. Wikipedia has 4000 words on the subject of Software Versioning. Versioning is inherent to software. We know that software will be updated, modified, changed. So this begs the question: If we know that software will need to be modified, then why have we been setting ourselves up to fail by not writing code that can be modified? We've relied on something characteristic of software production for small business: there is no version 2. Problem now is, this is no longer our niche in the market. We have grown and produce software for large corporations now.
We are in the early stages of an event here. Parts of this are changes in the fundamental way my company authors code. Gone are the days of "Git-er-Done however you need cuz the client can't afford a version 2". Now is the time of "Why did this maintenance modification cost more than the original construction?". I could go on, but I mention this only to frame a point. Our move to code creation that is able to afford change is not this singularly great idea for a problem that exists in the development phase. The new concepts and skills can be applied to everything we do here.
In the development phase we produce what the client requests: software that gets a job done and doesn't break. For the past however long, that is all that was required. Our search for efficiency, combined with a track record of software not needing an update because it doesn't break and clients not requesting a second version has resulted in us gaining efficiency by cutting out all real considerations for future extension or modification. Our ability to do this well has resulted in larger clients with larger needs. And now when their large software solutions need an update; when version 2 is requested, we find ourselves in real trouble. This situation not only exists in our development phases of projects. It also exists in the requirements and specification phases.
In the design phase we produce what the client requests: a document that defines the intent, appearance and functionality of the software to be produced. But after development based on that document is over; when the client requests a version 2 and we need to refer back to the document to understand version 1, we find ourselves in real trouble. Why? Because we don't document the changes made to the product during development. We can't keep up, and we have never had a real need to, so we don't. Our specification documents have just enough detail to satisfy the client. The document leaves so much of the technical detail up to the developer coding, that within a matter of weeks what is delivered to QA has diverged from the specification so far that the document is useless and the QA assigned needs the new specification communicated to them directly from the developer before they can begin testing.
What is needed is method of documenting requirements that can be so easily modified that the developers actually do update the documentation as the application is refined, or requirements change or the application design diverges from the original for any reason.
They're Doing it Wrong
Firefighters – Are called in when a project spins into a runaway or fires rage out of control in Production. They are highly skilled, very driven and goal oriented. They are there to fix a problem and do so in short order. They don't answer to you they answer to the stakeholder or your boss's boss's boss, and therefore they often care little about the resulting code. Much like a real firefighter will destroy your house with the fire hose to put out the fire in the kitchen. But hey, it’s not on fire anymore, right.
Pitbulls – Can range from non-technical to very technical. The determining criterion is their incessant need to be an ass. They almost never admit when they are wrong, especially in the face of overwhelming evidence. They are agitators used to force a stakeholder’s desires on the project. They are passive aggressive and Roosters. If a pitbull is the product owner the project will fail. The only way to handle a pit is to not step in the ring, but rather deal directly with the stakeholder holding the leash. They are unhappy about something or feel powerless, that is why they aquired a pitbull. Resolve that problem and the pitbull problem will resolve itself.
Architects – Talk a lot. No really A LOT. The rule is if you can get an architect to stop talking, then they aren’t really an architect. Be wary of the ones with charisma and technical skill. They are very dangerous. Where architects tread, ivory grows: this is their job. Regardless of any other consideration get to know your architect. You can learn a lot from just sitting and listening, just don't make them 100% of your information base. It is when an Architect stops practicing the craft of code writing that they become dangerous.
Skillz
Ability to QA a system
This facilitates the developer being able to catch and resolve issues before they become problems.
Write Effective Unit Tests
There is nothing I know of that enforces good Object Oriented design more potently than Unit Tests. It's not about a specific unit testing program because being able to create unit tests is a fundamental skill. It is a skill that translates across all programs and methodologies. Creating good unit tests is a science, and like any science can be perfected with enough experience and practice. The first thing people find when starting to write unit tests for the first time is that their code is not unit testable. They thought they were object oriented design masters and find that they’re doing it wrong. Unit tests flush out this misconception and force good object oriented design. Raw experience writing unit tests is required before quality code coverage is achieved. I would like to see students write unit tests in the major software project courses and give them this experience, as well as force the code into good OO design.
For more information:
http://en.wikipedia.org/wiki/Unit_test
http://en.wikipedia.org/wiki/Test-driven_development (TDD)
Refactoring
If you work your entire career creating new software for clients that don’t change requirements then you are the one, because no one else gets to. You will have to maintain a code base or adopt a code base or have to modify a code base. Refactoring skill is required; otherwise you’re just fumbling around hoping your changes work out, relying solely on your QA department to catch problems before the client does.
Refactoring is key to the new agile implementations, but again, more importantly the ability to transform existing code into unit testable, object oriented, patterned code is key to a successful career as well as being a chief tenant of any agile implementation. Being able to architect a great pattern-rich, mature solution and code it from the ground up is great. It’s still not simple to do, but when done right is a beautiful thing. More likely than not though you aren’t given that opportunity. You are given an existing code base and are asked to make changes. This can be in the form of a rotten code base written years ago, to an existing code base that is part of an active scrum sprint whose requirements were changed at the end of the last sprint. Either way being a code alchemist, being able to transform existing good or rotten code into the appropriate code is a huge skill. It’s also a fundamental skill that permeates through languages, frameworks and platforms. If this skill was focused on you would see the code that people adopt improve in quality, not just being retro fit in any way possible for the immediate need.
For more information:
Refactoring, Martin Fower, 1999.
Design Patterns
So many fields have achieved greatness today because they build upon the lessons learned in the past. For the vast majority of the Computer Science and software development field we restart from scratch every time. There is little growth. We have many of the same problems today that people in the 70s and 80s had. Design patterns facilitate mature initial design and simple/reliable extendibility later among so many other things. This is a key part to all the new agile implementations, but more importantly this is key to growth of the field, and growth in the field. For those looking for shoulders to stand on, here they are. These patterns reflect over 30 years of design refinement and extension. Software developers are foolish not to implement them. That is assuming they know Design Patterns for software development exist. That’s one of the problems, many are not aware of design patterns. Identifying patterns in use in code they are to maintain, identifying when to apply patterns to a new design, and identifying which pattern to refactor to are all difficult skills to master.
For more information:
Head First Design Patterns, Freeman, Sierra, Bates, 2004.
http://www.dofactory.com/Patterns/Patterns.aspx
Performance Testing
If there is a bottle neck, it has to be found before it can be fixed. There is a skill involved in finding the problem and a whole different skill set involved in improving performance.
Something's Wrong
There is something fundamentally wrong to me about the size of the failure-potential software development has always had and still carries. Maybe I'm crazy but in other professions is this also the case?
We don't follow engineering principles because we claim that they are too rigid and don't take advantage of all of the flexibility the software universe gives us, but if software's failure rate is as high as I think it is then what does the flexibility really give us? Do we need the flexibility simply because we never get it right?
I say 'we' in the all-encompassing profession-of-software-development sense. Because, well, you know 'we' NEVAR fail... ;)
Can all we really hope for is to get lucky project after project, just long enough to get promoted into another role? Do we have to pull out the smoke and mirrors when we don't get lucky on the design in order to fool our bosses and the client into thinking the project was a success? When I switched from mechanical engineering to computer science I wasn't thinking I was going to find the moral clarity of a Peace Corp volunteer, but I also didn't think I would have to cheat and steal to be successful. When we aren’t honest about our work and we make it seem that the troubles we had didn’t exist or were instantly overcome, then we set unrealistic expectations for ourselves, our colleagues and our company.
What is the fundamental problem here (other than the resulting failure)? What is the one desire that supersedes all when an application is done? I feel it every time I release an application: "I wish I could just redesign it", either in part or in whole.
Why do I feel this way? Is it because I screwed up the implementation so bad that I want to go back and fix it? No (well maybe once or twice :). It is because only now, at the end do I understand the business of the client, their needs and the true intent of the software and what functionality the application was supposed to provide. To those who, when done with the application, don’t care when they make the job of 900 users more painful, but rather only care that their bosses and the client business owner buy the illusion that the project was a raving success: I say good luck on somebody else’s team. Because if you are not measuring your application’s success by the positive value you provided to your client’s employees and profit, then you are using the wrong metrics.
Ok so let’s think about this. Why is it that we only know this at the end? Isn't that supposed to be acquired during Requirements gathering / Spec writing etc.? A true understanding only comes from the journey one takes with the client during construction and the feedback given during UAT. You never know if you are right/wrong/close or don't have a clue until you understand thoroughly your operating environment or until the client tells you.
So maybe here is where you fault the developers for not doing their due diligence in extracting this knowledge from the client beforehand. But you'd be, in most cases, wrong. This is because it’s not until the end, after they have taken the journey with you and see the results, that the client has any real understanding either.
Whoa, wait. Doesn’t this fall to the Project Manager/ Tech Lead to set client expectation and ensure that the project’s direction and design provides the client with the software they need?
Yes.
And do the managers/leads do this and correct during development as needed?
Most do.
So what is the problem?
The problem is that the projects in which this occurs invariably run over budget.
So what? The client had to pay more but they are getting the system they need, the system that solves their problem (even though they might not know it yet).
Many people agree with this. In fact, projects going over budget is such a common occurrence that claiming you are going to hit budget is most often perceived as a joke or arrogant. When a project does hit budget and deliver on time that team is immortalized. (See where the motivation to make every project appear to be a success comes from?) While being bedazzled by the efficient delivery, what the client fails to see at the time is that the application is rarely the tool the users need or were promised. Eventually, when the client business owner realizes this… well good luck to you.
Providing the client with the system they need, doesn’t nullify the fact that you told them the system would cost $700K and are now asking them to pay $900K. Ever tried to explain that to the client? Explain that the original design was not going to provide them with the system they needed and that all the time spent in the beginning doing the end to end design and spec writing that you had to assure them wasn’t a waste of money… actually was. Now, not only are they not going to pay the $900K but they also don’t want to pay the $700K either.
So if we only know what they needed once we finish, then how can we possibly build an application that will satisfy their needs the first go round?
UI Design Review
Posted by Phillip Jackson in UI Design on 30 July 2008