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?