Devart Blog

How to automatically generate SQL Server documentation

Posted by on November 2nd, 2016

In this blog post, we will learn how to quickly create a comprehensive documentation of an SQL Server database using dbForge Documenter for SQL Server, a database documentation generator from Devart.

There are a lot of benefits you get when generating database documentation automatically using dbForge Documenter for SQL Server. You don’t have to spend hours retrieving and writing technical information from scratch. Documenter builds an accurate and error-free documentation in just a few minutes. Besides, the documentation tool from Devart provides a rich set of features for customizing documentation output to meet your specific requirements.

Documenter presents documentation in an easy to view format, so you can share it with your boss or clients, other developers, DBAs, testers, project managers, business executives or other related persons.

The following example demonstrates how to generate documentation for the AdventureWorks2012 sample database.

1. Run dbForge Documenter for SQL Server. Click New Documenter… on the Start Page.

Start page of Documenter

2. In the Select Connections dialog box, select one or several existing connections from the list or create a new one. Click Select.

Select connection

3. The Database Documenter project opens.

Cover page

4. The Preview pane initially shows the Cover Page of the documentation, on which you can enable breadcrumb navigation links, add a logo, specify a header, title, and descriptive text of the documentation, specify the author and the date of creation.

In the upper right Style drop-down list, you can select a style defining the appearance of the documentation contents. Documenter contains a number of style templates and also allows to use various Bootstrap themes to change the documentation layout and appearance.

Style of documentation

5. In the search field of the Structure pane, start typing the database name you want to document. For example, type “Adv…”. As you type, Documenter filters out the databases and displays only the matching ones and highlights the relevant letters of the search text.

6. In the Structure pane, click the arrow next to the AdventureWorks2012 to expand the list of database objects. Documenter starts retrieving data from the database and analyzing its structure. Documenter extracts an extensive database info including a wide range of SQL object types, their details, properties, as well as inter-object dependencies and DDL codes.

Retrieving metadata from database

7. After the data have been extracted, the Structure pane displays a tree-view structure of the components available in the database. You can further expand the components by clicking the arrows.

8. Click the checkboxes next to the components you want to include in the documentation. These can be the components at different levels, such as the entire database, or a specific table, or a column of a table.

Documentation structure

9. The right-hand pane shows a preview of the information that will be included in the documentation. The information is represented under the following sections: Description, Object Types, Properties, Options, Database Files, and Sections To Include. These are the database-level sections. Along with that, Documenter allows you to configure elements of documentation on several levels, including:

– servers level;
– server level;
– databases level;
– database level;
– objects group level;
– database object level.

For example, in the Structure pane, click the arrow next to Tables to expand the list of tables in the AdventureWorks2012 database and then select the Person.Address table from the list.

The Documenter shows a preview for the table with individual sections (Description, Properties, Columns, Indexes, Foreign Keys, SQL Script, Depends On, Used By) that will be included in the documentation. You can exclude any of the listed sections and also specific properties (in the Properties section) for the Person.Address table so they will not appear in the generated documentation.

Table structure preview

In the same manner, you can customize the documentation by excluding sections and properties of objects at different levels mentioned above, for example, server, database, views, stored procedures, etc.

10. The descriptive text that is automatically inserted in the Description field for each database object is pulled from the MS_Description extended properties. You can edit the descriptions directly in Documenter.

MS_Description extended properties

11. When you’re all set, click Generate to proceed to the generation of documentation.

Generate button

12. The Generate Documentation dialog box opens, and you are prompt to choose a file format for the documentation. HTML format is suitable, for example, for databases to be published on the web, and PDF is good for distributing to various systems and devices. Both formats are searchable, which is very convenient especially for large databases.

13. Specify the folder to save the generated documentation to. Optionally, you can select to Append timestamp to the file name and to Open documentation after generation.

Documentation format

14. Click Generate to start generating the AdventureWorks2012 documentation. Documenter shows the progress of the generation.

Generation of documentation

15. After successful generation, Documenter will open the generated documentation, if the Open documentation after generation option has been selected. If not, open the destination folder you’ve specified to explore the documentation.

More Features

One of the great features of Documenter is that it integrates seamlessly with SQL Server Management Studio (SSMS). Databases may be documented directly from the Object Explorer of your SSMS solution.

What is more, Documenter is included in dbForge Developer Bundle for SQL Server, an ultimate toolkit from Devart that combines feature-rich functionality allowing to version-control databases, compare schemas and data, optimize database performance, write SQL queries on a fly, generate meaningful test data and much more straight in your favorite IDE.

Conclusion

As you can see, dbForge Documenter for SQL Server fully automates the process of generating documentation and reduces the amount of manual effort applied while yielding a comprehensive nice-looking technical description of an SQL Server database.

3 Responses to “How to automatically generate SQL Server documentation”

  1. Andrey Says:

    The example of document required in this article.

  2. Marshall Stickley Says:

    Is this an accurate statement “Documenter builds an accurate and error-prone documentation in just a few minutes.” If so, not sure I would want the software if it is generating “Error-Prone” documentation.

  3. dbForge Team Says:

    Sorry for this misprint. Of course, Documenter generates error-free documentation.

Leave a Reply