So, I'm a tech writer, not a database guy, but I've been asked to develop documentation for my company's databases. This means I have some questions.
It seems obvious to me that there must be some SQL documentation tools out there, but I have no idea what is used for the purpose. I have some ideas of what I think would be useful, but I'm not the target audience, so it's likely I'm missing something.
So there are two things I'd like some help with:
First, if anyone has used any such tools, I'd appreciate any pointers to things you've found useful. My notion is that dynamically generated documentation is better in this case than flat files or hand-coded html or something, and computers do a better job of generating graphic representations of complex relations than I do. My second notion is that I'm probably not the first person to have this idea, so something of this sort probably exists.
My employer is willing to pay for tools, but I don't really know how to evaluate them from a distance, so I could use some guidance.
Second, as a database developer, what information do you most wish you had when you approach a new position or a new project? The documentation is mostly aimed at continuity of business: the "Bob-gets-hit-by-a-bus" scenario, where you have to replace the guy who knows everything on short or no notice, so picture yourself hired to work on a big database with little or no ability to consult with the people who built it.
My instinct is to get the semantics right - what does each table represent? what do the rows represent? - and map the most important relations - where is my entry point? what am I looking for? - but push the hairy details down into the fine print, since presumably once you know the larger structure it's not so hard to fill in the fine detail. Am I on the right track, from your point of view? If not, what am I missing?
Thanks for any thoughts on this.