Rampant CodeCraft

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:

• When defining the design, the developers aren't in a document, they aren't evaluating the size of the document, they aren't comparing document sections before or after it for page length or content. Their sense of done is soley based on the detail they have inscribed within the wiki page they are focused on.
  
• Wiki pages, images and other resources are versioned, and are versioned better than tracking changes in a document provides.
  
• There is no sense of beginning and end in the wiki. Wiki pages that are related to the page the developer is currently either designing, or constructing software from, is linked to from that page. This puts all the information the developer needs within easy reach.
  
• During development the development, QA and management staff are focused on portions of the document and not the entirety, when the client reads the design in document format they will be able to consume the entirety from beginning to end because the document version provides this.
  
• Wikis are easy for multiple people to edit at the same time. no passing around a document or merging document sections together.
  
• In digital format they are very easy to navigate.
  
• In document format the embeded links to other document sections is inherent and doesn't require one manually entering in the links.