How and Where to Document Common Features
I was in a design session the other day and someone raised the question of where to document common features. By common features I mean features that perform identical actions on 2 or more fairly disparate parts of an application. Here's an example.
Let's say you run a website that aggregates a couple of different services, such as purchasing images and purchasing sound clips. The services, purchasing of images and purchasing of sound clips, bill you separately. There is no combined billing. Granted, that's a terrible user experience but this is just for purposes of illustration.
Before a customer can be billed the billing account needs to be captured and stored. Each service, image purchase and sound clip purchase, stores credit card numbers separately (again not a great design but this is a contrived example). So each service uses a feature to store a credit card number.
The question that came up was how do you document this common feature of storing a credit card number? Should it be captured as a central feature? In this case you'd have a feature of store credit card number, and then document in a list the different services that a credit card number can be stored for. Or should it be captured as a feature of the individual services? In that case you'd include the store credit card number feature with all the other image service features, and also with all the other sound clip service features.
The second option, where a common feature is duplicated in several services, may arise when separate teams are designing and developing individual services. Each team documents an identical feature. Each team is very familiar with the feature and how it works and that it's part of the service. But as time goes on a change to the store credit card number feature made for one service could be detrimental to the other and the teams could be unaware of how the other service uses the feature since that knowledge is kept in silos.
In discussions, documenting the feature in a centralized fashion and listing or cross-referencing that feature into the other services was preferred by most of the team. Most felt that it would be easier to make documentation changes if you only had to make it in one place. I agree with this method. It is crucial that the cross-referencing of the feature is documented. Often new services are based on existing services, and if a cross-reference is missing and the new service doesn't use the feature properly, then critical functionality may be left out.