How To Doc
0 Comments
Most of what you’ll find in the “Agile” development methodologies is just common sense. Anyone who’s been in development long enough would agree with most of the principles that the Agilists propose. One of the main areas of real controversy has to do with documentation.
This mostly comes out of a reaction to the heavy, “high-ceremony” methodologies of the 90’s (like Rational Unified Process - designed to sell Rational tools). The Agile folks essentially have dispensed with the UML, the use cases and so forth and gone with the lightest-weight documentation they can get away with, in pursuit of the idea that they should be building software, not documentation.
Well, for companies like AI where 99% of what we build is for our clients, this “no-documentation” doesn’t quite work. This is because:
To fill this gap, some of the Agile methodologies, notably Extreme Programming (XP) recommend an “in-house customer”. This sounds both great and horrible to me for different reasons, but in any case I’ve never known any shop that’s actually been able to pull if off. Our customers are to busy doing other things like, say, running their own business, to sit around in our shop being our resident customer. That means we need to document.
At the same time, we certainly don’t want to go back to the bad old days of high-ceremony. So we’ve endeavored to create a light-weight documentation system built on the attributes of the part of the system being developed.
We have 4 documentation types:
Specifications: Written technical specifications that describe the system, either in paragraphs of text or some times with tables that define data structures.
Wireframes: Simple mock-ups of user interfaces that show the layout of the application to the customer.
Prototypes: Simple, interactive versions of the application which demonstrate the interactivity of the app to the user.
Nothing!: Not everything needs documentation! Sometimes the best approach to document is not not document at all.
These four “directions” form our compass:
(Well - its almost N,S,E,W - instead we have N,S,P,W).
When deciding how do document a feature or part of an application, we’ll want to look at the following criteria:
Linearity: Is this a serial, step-by-step kind of process we’re describing, or is it something that can wander in any direction?
Visibility: Is this a part of the application that is reflected in the UI? Is it something that the user is going to see, or is it strictly behind the scenes?
Interactivity: How interactive is this feature? Is there a lot of back and forth with the user, or does the user just fire off one event and a bunch of stuff happens without further input?
Uniqueness: How unusual is this feature? Is this something that is unique to this app, or unusual in this business space, or is it something that everyone has seen a thousand times before?
These four attributes influence our documentation decisions:
Linearity
The more linear a process is, the more it drives documentation towards a specification. Specifications are particularly good for describing automated, back-end processes. They are less useful for non-linear processes.
Visibility
Visibility in a feature is a good indication that wireframes or prototypes should be used. This is because everyone, including customers and developers, needs to be able to visualize the user interface for the feature.
Interactivity
Interactivity drives towards prototyping. The more back and forth a feature presents with a user, the more inefficient a wireframe is at properly representing it. Instead we need to resort to prototypes - interactive but “hollow” versions of the app that simulate the back-and-forth the real application would provide. This allows the observer to properly understand the interactivity of the feature.
Uniqueness
Unique or notable features require documentation, common and already well-understood ones do not. One option that is always available is to do nothing: to not document the feature. I believe that the driving force here is uniqueness - how notable a feature is. Conversely, common or well-understood features may not require documentation at all.
So how do we use these driving forces? Lets look at a couple of examples.
Lets say our first feature is a complex set of preferences. Choices made by a user may cascade into more choices, and may spawn dialog boxes. Looking at this feature, we can state that it is Visible, Interactive, Nonlinear and Unique. Putting this characterization against our model above, gives us something like the following:
The model has spoken: a prototype of the feature is the best way to document it.
For a very different case, lets say that we have a common print function occurring in the application. Well, everyone has pretty much knows what printing means, so lets call it Invisible, Linear, Non-interactive and Common.
Applying the model, we can see the best thing to do with this feature is to leave it undocumented, everyone already understands it.
This mostly comes out of a reaction to the heavy, “high-ceremony” methodologies of the 90’s (like Rational Unified Process - designed to sell Rational tools). The Agile folks essentially have dispensed with the UML, the use cases and so forth and gone with the lightest-weight documentation they can get away with, in pursuit of the idea that they should be building software, not documentation.
Well, for companies like AI where 99% of what we build is for our clients, this “no-documentation” doesn’t quite work. This is because:
- Documentation is part of the approval cycle, in which our clients let us know if we’re building the right stuff for them.
- Documentation lets our clients know what we’re going to build before we actually build it.
To fill this gap, some of the Agile methodologies, notably Extreme Programming (XP) recommend an “in-house customer”. This sounds both great and horrible to me for different reasons, but in any case I’ve never known any shop that’s actually been able to pull if off. Our customers are to busy doing other things like, say, running their own business, to sit around in our shop being our resident customer. That means we need to document.
At the same time, we certainly don’t want to go back to the bad old days of high-ceremony. So we’ve endeavored to create a light-weight documentation system built on the attributes of the part of the system being developed.
We have 4 documentation types:
Specifications: Written technical specifications that describe the system, either in paragraphs of text or some times with tables that define data structures.
Wireframes: Simple mock-ups of user interfaces that show the layout of the application to the customer.
Prototypes: Simple, interactive versions of the application which demonstrate the interactivity of the app to the user.
Nothing!: Not everything needs documentation! Sometimes the best approach to document is not not document at all.
These four “directions” form our compass:
(Well - its almost N,S,E,W - instead we have N,S,P,W).
When deciding how do document a feature or part of an application, we’ll want to look at the following criteria:
Linearity: Is this a serial, step-by-step kind of process we’re describing, or is it something that can wander in any direction?
Visibility: Is this a part of the application that is reflected in the UI? Is it something that the user is going to see, or is it strictly behind the scenes?
Interactivity: How interactive is this feature? Is there a lot of back and forth with the user, or does the user just fire off one event and a bunch of stuff happens without further input?
Uniqueness: How unusual is this feature? Is this something that is unique to this app, or unusual in this business space, or is it something that everyone has seen a thousand times before?
These four attributes influence our documentation decisions:
Linearity
The more linear a process is, the more it drives documentation towards a specification. Specifications are particularly good for describing automated, back-end processes. They are less useful for non-linear processes.
Visibility
Visibility in a feature is a good indication that wireframes or prototypes should be used. This is because everyone, including customers and developers, needs to be able to visualize the user interface for the feature.
Interactivity
Interactivity drives towards prototyping. The more back and forth a feature presents with a user, the more inefficient a wireframe is at properly representing it. Instead we need to resort to prototypes - interactive but “hollow” versions of the app that simulate the back-and-forth the real application would provide. This allows the observer to properly understand the interactivity of the feature.
Uniqueness
Unique or notable features require documentation, common and already well-understood ones do not. One option that is always available is to do nothing: to not document the feature. I believe that the driving force here is uniqueness - how notable a feature is. Conversely, common or well-understood features may not require documentation at all.
So how do we use these driving forces? Lets look at a couple of examples.
Lets say our first feature is a complex set of preferences. Choices made by a user may cascade into more choices, and may spawn dialog boxes. Looking at this feature, we can state that it is Visible, Interactive, Nonlinear and Unique. Putting this characterization against our model above, gives us something like the following:
The model has spoken: a prototype of the feature is the best way to document it.
For a very different case, lets say that we have a common print function occurring in the application. Well, everyone has pretty much knows what printing means, so lets call it Invisible, Linear, Non-interactive and Common.
Applying the model, we can see the best thing to do with this feature is to leave it undocumented, everyone already understands it.
