We have a pretty good solution for portal code interface in our team. We’ve been using a home-grown portal for about a half-dozen years and it has grown to be fairly sophisticated. We have role-based-security, page auth, object auth, data item auth, row level auth, and user attributes. It’s pretty sophisticated.
Now, we have to describe it to another team that wants to understand it. Problem is… it’s homegrown and most folks just use the modules that someone else wrote to do most of the basic things. So it is not that easy to find a concise and descriptive document already in existence.
So we write one… right?
OK… what do we put in it? I’m serious.
If you have a code interface, and you need to describe it from a simple API standpoint, it may be simple enough to extract the documentation using .Net, but if you want to actually ‘describe’ it to a dev team so that they can consider the features of your interface, and perhaps put a few into their product, you need a much richer description than MSDN.
Interaction diagram. Class diagram. Some text describing the use cases. Notes on data structures, dependencies, and type inheritance.
That’s about 6 pages of description for a simple interface… 50 for a complex one. Is that the right level of detail? If you were a developer, and someone else had created an interface and you want to evaluate your tool, figure out how hard it may be to add the features from that interface into your library… how much detail would you want to see?
What about as a set of unit tests?
Among other things.
The most helpful information for me initially would be prose explaining the context and goals for the API. Use cases in particular are valuable.
Class diagrams and the like are okay for dependencies, although I can see the list of fields and methods just as well in an IDE.
The biggest struggle I have in working with unfamiliar interfaces is trying to understand what the developer was thinking (e.g. why’s, design tradeoffs). Was he trying for a set of orthogonal functions or hundreds of convenience functions? What was the reason she chose a value type instead of a reference type? Was the basic design analogy people waiting in line at the teller, or kids at a theme park?
Particularly if one can see the source code, detailed functional descriptions matter less than ensuring the writer and reader/maintainer are working with the same mental model. Diagrams help in some ways, but sometimes well-written prose explains it better.
We developers are as prone to poor thinking as everyone else when we want to be. That is, we can apply our problem-solving skills in a heartbeat when it comes to writing software. But we are just as likely to discard those same skills when we don’t recognize a situation that would best employ them.
Case in point, this question. It can be expressed as a problem, a set of requirements along with a set of resources. An analysis of the requirements is as follows:
1. You have an interface that someone wants to use.
2. They do not know how to use it.
3. They must be told how to use it.
Further analysis of these simple requirements yields the following thoughts:
1. What do they want to use it for? It is possible that the use they want it for will not require a full explanation of every detail, but only the details about what they want to use. This narrows down the scope of the problem.
2. Is this likely to be used by others as well? Here, the question is not so much about the specifics, but about extensibility. Should our explanation be tailored to fit the needs of the many, or the needs of the few? If it can be established that others are not likely to use it, the scope of the problem is constrained to giving an explanation that the audience will understand.
3. Keeping the target audience in mind, it may be possible to target the presentation of the information as well. Different people learn best in different ways, and according to circumstance. Some learn best by doing, others by seeing, and others by hearing.
Other thoughts and ideas might present themselves as well. At any rate, once the problem has been defined, and the various variables that affect the outcome identified, it is a relatively simple matter to tailor a solution to the problem.
I find it odd that we developers are taught to think abstractly about so many things, but often find ourselves in a pickle when it comes to certain other things. There are so many aspects of our lives that could be handled better if we applied our problem-solving and analytical skills to them in the same way that we apply them to our work.
Wow, Kevin! Great reply! I’m honored.