Product Specifications using Edward Tufte's Principles
In my last entry, I discussed Edward Tufte's work on Data and Information presentations. Great stuff! I want to use it in my own work and, even more, I'd like to see it in presentations that are given to me. In particular, as a manager of a software development organization I spend much time reading, interpreting, studying and dissecting product specifications or requirements documents. These documents are presentations of the information needed to design and build a software application. And, of course, the documents are not just for developers. Many people review specifications; including stakeholders to make sure they accurately record what they need, IT management for scoping and approval, QA so the system can be tested and PR/Marketing/Sales so they know what's coming. It's a critical document for any growing company.
If we can improve on the document; we can improve the feedback and discussion about it, we can increase the efficiency of moving projects through the pipeline, and we can reduce defects because the increased clarity will make it less likely that QA and development will miss details. In this way, the larger group of involved individuals can acquire a deeper understanding of the design and goals. This is better than a methodical checklist and just a few people with true understanding.
Common formats with wordy paragraphs, lengthy bullet lists and multi-dimensional cross-referencing may be effective for the writer. And, if this helps, they should keep doing it. And then they can make a presentation for the rest of us. It may seem like double work, but the gains in the previous paragraph indicate that it would be time well spent. After all, the goal in the end is to build top quality products, not lengthy documents.
Another way to look at it, as Tufte suggests, is that the goal is not just to produce a presentation in as efficient a means as possible, but also to make it efficient to consume the material.
I work mostly in the domain of web development (front-end to backend for both content and transactional systems). Much of the work is driven in units of "web pages". I believe the techniques from Tufte can be applied effectively to this domain. Hopefully, the same will work for functionality that is less grounded in the user interface, but that will be an exercise for the future. Generally, the idea would be to pack all information related to a particular functional component (a web page or set of related web pages and it’s functionality) on to a printed legal size sheet of paper (a "paper page") with high resolution (i.e. high information density).
Mock-ups or wire-frames for the relevant web pages would be printed on the paper along with a sub-flow that shows the web page in the larger navigation or user scenario. In this way, we provide immediate and obvious context for the points that we want consumed and discussed. Business logic would be noted directly on the page with lines linking it to the UI (or data) elements that it is related to. Labels on the lines can indicate the type of relationship. Relationships may be indicated between text notes, as well. E.g. labeling the relationship as "copy" would indicate that the annotation describes the text (or copy) that should go in this location. A label of "graphic design” would indicate that the annotation refers to the visual appearance of the page, etc.
The functionality represented on one paper page should have both high cohesion and low coupling. Concepts which, coincidentally, are key to good object oriented design[http://en.wikipedia.org/wiki/Cohesion_%28computer_science%29]. In short, high cohesion means that the information points on the “paper page” are highly related and focused. And low coupling means that dependencies on other “paper pages” are minimized. The high information density of the paper and adherence to these two concepts will reduce context switching. No need to flip back and fourth through the pages and continually reorient.
Instead of volumes of text, we have a mix of words and images that serve to communicate the ideas in the shortest time possible. This allows for more time to reason about the requirements and less time on complex, possibly flawed interpretation of the material. All information about the page would be right there in a holistic view; no "refer to figure 2.2.3.1a" or questions such as "is this text referring to the screen shot on the previous page or the one on the next page?"
The gains in pipeline efficiency, depth of understanding and quality of the finished product could be huge. A key objective is the ability to faithfully translate the vision into an actual product. This ambition is frequently limited because the developers don’t have as good a picture of what they are creating as the people who requested it. To improve the state of software development, we should do everything possible to reduce this friction.
A couple of practical notes…
Tool Selection
In order to back up my proposal when I brought it the product team, I created a sample based on an old product specification for a small project.
I made my first attempt in an illustration program, Inkscape, which is an open source editor for SVG graphics. I thought this would give me complete flexibility for the page. That was true, but creating multiple pages was cumbersome.
I redid my sample in Excel. Excel, if you don't know, has basic drawing tools for boxes, lines, etc. This worked out quite well. When you print you have to remember to "print all sheets", as each page was a different Excel sheet.
Another option is Visio. And if your spec writers get some PDF printing software, you can distribute PDFs and avoid having to license Visio for the whole company.
These sample documents are confidential to TheLadders.com. However, seeing as the project has already gone live, I'm going to see if I can get permission to make them public. I believe this is the best way to illustrate my points.