Possible SQL Doc Enhancements

mlukas

I have been a long time user of SQL Compare and SQL Data Compare. We have just started using SQL Doc seriously. Although the product works well, the following are some suggested enhancements related to control of the generated documentation.

Our database includes 252 tables, 9 views, 84 functions and 588 stored procedures. Having now invested the time to document all of these objects, when we generate a word document, it is almost 3000 pages. The size of the document makes it difficult to use practically. Additionally, the performance of Word is questionable with large documents.

Having finer control over what is output would allow us to reduce the document down to a manageble size.

1. We have customized the title page by modifying DefaultCoverPage.doc, however, greater flexibility (or at least instructions on what is currently possible) would be appreciated.

2. Each object is currently placed in a different section and each section has its own header. We would prefer one header for the whole document.

3. As a result of each object being in a new section, each object starts on a new page. This results in a lot of empty space and is a large reason why the document is so many pages. A new section for each object class (ie tables, functions, stored procedures, etc) would be sufficient and then just have each object within a section start on the same page.

4. At the begining of each object section, there is a summary of each object which is then followed by the details of each object. The summary is also included in the details and so the information is redundant. The ability to suppress this summary would be helpful.

5. For each table object, there are Properties, Columns, Indexes, Uses and Used By sections. Some of these are of lesser importance. The ability to select what is output would be helpful. There are similar sections for other object types.

chriskelly

Thank you very much for your suggestions.

For some instructions on modifying DefaultCoverPage.doc, see Ben Hall's blog below:
http://blog.benhall.me.uk/2008/12/sql-d ... -page.html
(Have you already seen this?)

Your point about the MS Word document getting very large, and the pitfalls of this, is valid and the changes that you suggest could help to reduce this size. An alternative way to reduce the size of the document is to generate a .html document instead, which will store the data in a more efficient manner.

I have raised your comments concerning greater control of the generated document as an Enhancement Request (SDOC-1431). This will be passed onto our development team for consideration.

Any other comments, observations or improvements that you think could be relevant would be welcome.

mlukas

Thanks

Is there a timetable for a new release? It has been almost two years since SQL Doc 2 was released?

chriskelly

Unfortunately I am not able to give you a definitive answer at the moment. It will be 2011 at the earliest, but there are no definitive dates.

bill.wehnert

1. Dependency graph. A visual representation with a diagram showing all of the entities (color coded by type) that depend on this entity.

2. An Foreign Key graph that shows all related tables. Maybe with an arrow showing which way the dependency is going.

3. I'll also agree that I'd love to see the Diagrams be imported if possible. Don't know if SMO lets you export to an image via the API, but if you could embed that in the help file, that would be huge. I don't care right now if you made the diagram linkable (I click on a table - it takes me to that part of the help) -just having the diagram(s) would be a huge bonus I think.

4. Ability to add other types of data on a table. Basically the ability to create my own Extended properties - maybe define them at a project level and say that they are a Table/Field/Sproc/View/Function/etc property and then the editor would let me fill in the values at the appropriate spot. Even cooler would be to specify the data type and length so that you could have some mask fields available (say for capturing only a date, etc).

5. Ability to store all of the extended properties outside of the database so that if something were to happen and you had to rebuild your docs on a backup or on another server, you'd have all of your information available. This would be helpful too if while you are designing you would rather drop the table and rebuild it to put the fields in the order you want. It's a small thing, but would be helpful to me.

Cody

bill.wehnert wrote:

5. Ability to store all of the extended properties outside of the database so that if something were to happen and you had to rebuild your docs on a backup or on another server, you'd have all of your information available. This would be helpful too if while you are designing you would rather drop the table and rebuild it to put the fields in the order you want. It's a small thing, but would be helpful to me.

Seconded. While another thread has pointed to a script to save and restore these; it would benefit me if the documentation changes could be:

- Stored to a local file/database instead of the descriptions; this way a database can be documented without having to give write access to the schema to documenters.
- Then optionally apply/retrieve those locally saved descriptions TO a database.

I can't believe the original version didn't do things this way. Luckily, I found out during the evaluation period. These are must have's, I'm afraid.

David Atkinson

Thanks for the feedback.

SQL Compare has the concept of a schema snapshot. If we allowed SQL Doc to read in this file format, would this solve the problem?

David Atkinson
Red Gate Software