How to document specific database objects using the SQL documentation software

Applies to

ApexSQL Doc

When there is a need to show new or altered objects to other developers or managers, who don’t have access to a database on which development process is done, it’s helpful to have a way of presenting them as a documentation file. This documentation should contain only these specific objects, rather than including all database objects, as the latter would be time-consuming, unreadable, and tedious.

In this article, the documentation process of the desired schemas and tables will be described using the SQL documentation software tool – ApexSQL Doc.

ApexSQL Doc is a tool used to document SSIS packages, SSAS cubes, SSRS reports, Tableau server sites, and SQL databases. The SQL documentation software can narrow down the documentation process to only the desired object types and the corresponding objects. Selecting a specific object type for the documentation (such as schemas, tables, triggers, views, etc.) can be easily done in a few clicks. This way, generating documentation will be faster, and reading the documentation will be much easier.

In order to explain the database documentation process using ApexSQL Doc, the AdventureWorks2016 database will be used. This database contains multiple schemas and tables, and only one schema (dbo) and three tables (DatabaseLog, ErrorLog, and AWBuildVersion) will be documented.

In the following steps, the complete process will be described:

1. The first step in the database documentation process is adding a database. When the Add database button is clicked from the Home tab, the Add SQL Server dialog will be shown. In this dialog select Server and type of the Authentication and then click the OK button:

   

2. When the database is selected, click on the Database objects tab under the Data sources and objects panel:

   

3. Filtering the specific database object type that will be documented can be done in the Database objects tab in the Object type grid. Since only one schema and three tables will be documented, check the Schemas and Tables in this grid:

   

4. The next part of this process is to select which the schemas and tables options will be documented

   Since only objects for the schemas are needed, check the Objects option in the Schema options grid:

   

5. For the tables, only columns are needed to be documented, so the Columns option will be checked:

   

6. The last step before generating documentation is to check the desired schemas and tables from the Object filter grid, which will be documented

   In this example, one schema will be documented, and it is the dbo schema:

   

7. As for the tables, three tables (DatabaseLog, ErrorLog, and AWBuildVersion) are selected under the dbo schema:

   

8. The final step in the database documentation process is to click the Generate button in order to initiate the documentation process:

   

9. When the process of creating the documentation using SQL documentation software is done, open created documentation. As shown below the dbo schema and only selected tables are documented:

   

With a click on the schema name (dbo) in the documentation, only Objects options are documented for the schema options:

With a click on the Tables, only those tables that were selected for the documentation process will be shown:

Since only columns were selected to document, with a click on the table, only column options will be shown in the documentation:

The above-explained process can be used for any other object from a database.