Document! X is a combination of an automated database documentation tool and a full documentation authoring environment which can be used to create accurate, professional quality database documentation for SQL Server, Access, or other OLEDB databases.
Document! X is not just an automated database documentation build tool - it also includes a fully-featured documentation authoring environment allowing you to author supplementary content (descriptions of database elements, hyperlinks to related pages or web sites etc.) where required.
Document! X uses the content of Access and SQL Server description properties in the generated database documentation where available. This means that you can continue to use SQL Server Management Tools or the Access Table Designer to define descriptions for your tables, columns, triggers, indexes etc. and Document! X uses them automatically.
In addition, you can include specifically-formatted comments in your T-SQL code and views. Document! X extracts the comments and uses them in the generated SQL documentation.
-- ##SUMMARY This procedure is an example of using various Document! X comment types -- ##REMARKS Single line and multi-line comments can be used and comments can include <strong>HTML Markup</strong> -- ##RETURNS Documents the return type of a procedure CREATE PROCEDURE ExampleTaggedComments @Param1 int = NULL, --##PARAM @Param1 The first parameter @Param2 varchar, --##PARAM @Param2 The second parameter @Param3 tinyint, --##PARAM @Param3 The third parameter AS ...
/* ##SUMMARY This procedure is an example of using various Document! X comment types ##REMARKS Single line and multi-line comments can be used with tagged comments in a single or separate multi line comment blocks and comments can include <strong>HTML Markup</strong> ##RETURNS Documents the return type of a procedure */ /* ##PARAM @Param1 The first parameter ##PARAM @Param2 The second parameter ##PARAM @Param3 The third parameter */ CREATE PROCEDURE ExampleTaggedComments @Param1 int = NULL, @Param2 varchar, @Param3 tinyint, AS ...
Create a New Database Reference Documentation Project
Creating an empty project creates a project without any content. You can customize its settings according to your needs.
To create an empty project:
The project is created at the default directory which is configurable in the Options Editor (Paths page). However, you can optionally choose a specific directory to save your project by browsing the Project Directory field.
The new empty documentation project is created and opened for edit. You can now add the Databases that you would like to document:
The selected Database is added to the Project Explorer under the Databases node. You can expand down through the database node to select / deselect individual database elements in order to include / exclude them from the generated output. Repeat the process above if you would like to include additional Databases in the project.
A Content File is created and added to the project under the Content Files node for each Database you add to the project. You can use this Content File to author additional content in the pages that Document! X automatically generates.
Author Content in the Database
In Access and SQL Server you can use the various database item properties editors in Access or SQL Management Studio to author descriptions directly. In SQL Server you can also use the extended properties stored procedures to do this programmatically (see http://msdn.microsoft.com/en-us/library/ms190243.aspx).
See Author Content using the Content File Editor for authoring content outside of the source code.
For SQL Server, you can define new Content Item Types in Document! X in order to store custom content types in extended properties - e.g. Author or Creation Date. The XML Tag Name of your custom Content Item Type is used to find the right extended property in SQL Server.
For database elements with source code (Views, Stored Procedures, Functions) you can also embed specifically tagged source comments that Document! X then uses in the generated output.
-- ##SUMMARY This procedure is an example of using various Document! X comment types -- ##REMARKS Single line and multi-line comments can be used -- ##RETURNS Documents the return type of a procedure CREATE PROCEDURE ExampleTaggedComments @Param1 int = NULL, --##PARAM @Param1 The first parameter @Param2 varchar, --##PARAM @Param2 The second parameter @Param3 tinyint, --##PARAM @Param3 The third parameter AS ...
Document! X supports transforming source comments and extended properties to HTML using XSLT. Using XSLT to transform your database content allows more complicated and structured source content, the output of which can be customized without making changes to the original content itself.
See Transforming Content Item Type Content for more information.
Author content outside of the source code
If you would like to supplement the content of the pages automatically generated by Document! X and HelpStudio outside of the source code, you can do so using the Document! X and HelpStudio Content File Editor.
The Content File Editor allows you to review and author content for any item for which a reference documentation page is generated.
To open the Content File Editor:
Add Conceptual Topics
Conceptual information is a key part of reference documentation, providing a high level introduction, tutorials, or other conceptual information. You can easily create conceptual topics in Document! X.
You can find more information on Topic Editing in the Topic Editor topic.
Change Database Documentation Settings
The settings that govern Database Documentation generation are defined in the Build Profile editor. In a new project there is a single Build Profile but you can define many build profiles if you want to create multiple outputs with different settings.
To edit Database documentation settings:
In the Build Profile editor, you can find the Database Settings page under the Reference Documentation section.
You can change the Template used for Database documentation (which defines the look and feel of generated pages) on the Templates page.
Identify Undocumented Items
An essential part of delivering a complete documentation set is ensuring that all the items have been documented. Document! X includes the Undocumented Items tool to quickly and easily identify undocumented items.
Build and Deploy Database Reference Documentation
Click the Build button on the Project tab to build your Database reference documentation.
Refer to the Deployment topic for more information on how to deploy your documentation to other machines.