I keep running into a problem at work, and I'm hoping that others know a solution either from personal experience or from best practices.
I am not a programmer. I do, however, heavily use RDBMS tables which are populated by code that our programmers write. I also use other products of our developers'. Most often, these products are not documented.
Here's an example (genericized): We have a table that indicates status changes to accounts. I thought it included every time someone attempts the change; turns out, it includes only successful changes, and excludes attempts to change to the status currently held. This greatly affects my queries against that table. But no one had documented it anywhere.
Another example: A JIRA feature-request requested that some cron affect accounts after n days of the accounts' inactivity. Does that mean 24×n hours exactly? Does it mean the difference in dates between the last activity and the cron should be n? Something else, perhaps? Again, the precise definition here affects my queries against the relevant table, but was undocumented.
In both those cases, I had to sit down with the relevant developer, who read through a bunch of code, some of which she herself had written, to determine what the code did. This is a waste of time for the developer, who will have to sit down with another employee a few months later when he/she has the same question and the programmer doesn't remember the answer. And then again a few months later.
What should we do about this? There seems to be some sort of documentation needed. Where should it be? Or is the current situation ideal?
Some ideas I thought of:
- Comment RDBMS tables and columns. (The RDBMS we use allows for this.) Or have separate documentation broken down by RDBMS table. But a developer here correctly told me that
ifwhen a developer fails to document something, people will be relying on outdated documentation, which is worse than the current situation. Also, this would only document the RDBMS; there are, of course, other products of the developers'.
- In any JIRA issue (the vast majority, perhaps all, of our code changes are in JIRA), include the RDBMS table name (and/or other important search terms) and documentation of what was done. That way, people wanting to know about any developers' product have a central location to search, and can read each diff's documentation.
Does anyone have a solution? What do other companies do? What have you seen, or what best practices exist?