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.