Document! X 2017
Getting Started / Getting Started with Database Documentation
In This Topic
    Getting Started with Database Documentation
    In This Topic

     

    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 is 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.

    Leverage your existing content

    Document! X will use 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 will use them automatically.

    In addition, you can include specifically formatted comments in your T-SQL code and views. Document! X will extract the comments and use them in the generated sql documentation.

    Example source comments (single line comment style)

    -- ##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
    ...

     

    Example source comments (multi line comment style)

    /* ##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
    ...

    Database Documentation Fundamentals

    Create a new Database Reference Documentation Project

    1. Click the Application Menu button at the top left of the Ribbon;
    2. Select the New page;
    3. Choose Empty Project from the available Project Types;
    4. On the New Project dialog, type a descriptive Project Name for the new project; 
    5. You can optionally choose a specific directory in which to save your project by editing the Project Directory field; the project will by default be saved to a subdirectory of the default New / Save directory which is configurable in the Options editor (Paths page).
    6. Click Ok;

    The new empty documentation project will be created and opened for edit. You can now add the Databases that you would like to document:

    1. Click the Add Database Ribbon button on the Project Ribbon tab.
    2. Use the displayed dialog to define the properties of the Database that you would like to document in this project.
    3. Click Ok;

    The selected Database be added to the Project Explorer under the Databases node. You can expand down through the database node to tick / untick 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 will be 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 will automatically generate.

    Existing content from your database will be automatically used in the generated output where available. Content from the database is displayed in the Content File Editor so you can see at a glance what content is already available from source comments and what requires further authoring.

     

    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).

    Custom Sql Server extended properties

    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 CreationDate. The Xml Tag Name of your custom Content Item Type is used to find the right extended property in Sql Server.

    Tagged source comments

    For database elements with source code (Views, Stored Procedures, Functions) you can also embed specifically tagged source comments that Document! X will then use in the generated output.

    Example

    -- ##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
    ...

    Xsl Transformation

    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.

    Each time you open your documentation project, Document! X will read the current content, so your documentation will always be up to date with content you have authored in the database.

     

    Author content outside of the source code

    If you would like to supplement the content of the pages automatically generated by Document! X outside of the source code, you can do so using the Document! X 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:

    1. Expand the Content Files node on the Project Explorer.
    2. Locate the Content File for the item you wish to author content for.
    3. Right click on the Content File and select Edit.
    4. The Content File will be opened for edit. The tree on the left hand side of the editor shows you a hierarchical view of the item you are documenting.
    5. Drill down and select an item from the tree and the related documentation pages will be shown in the right hand side of the editor.
    6. Type directly in the editable portions of the page on the right hand side of the editor.
    7. Select a specific content type from the toolbar / vertical menu to edit a specific type of content (e.g. Summary, See Also, Keywords).

    Content File Editor Movies

     

    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.

    1. Click the New Topic button on the Project Ribbon tab, or use the Ctrl+T shortcut key.
    2. The new Topic will be created in the currently selected Topic Category on the Project Explorer (or under the (Un-categorized) node if no category is selected) and will be opened for edit.
    3. Type your conceptual content directly in the editable area of the Topic Editor.

    You can find more information on Topic Editing in the Topic Editor topic.

    Conceptual Authoring Movies

     

    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:

    1. Expand the Build Profiles node in the Project Explorer.
    2. Select the Build Profile that you wish to edit.
    3. Right click on the Build Profile and select Edit.
    4. The Build Profile will be opened for edit.

    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.

    To identify undocumented items:

    1. On the Tools Ribbon Tab, click the Undocumented Items button;
    2. If your project contains more than one Build Profile, select the Profile for which you wish to find undocumented items;
    3. Tick the Item Types (e.g. Class, Method, Schema, Column) that you wish to check for undocumented items;
    4. Tick the Content Types that items must have to be considered documented (just Summary by default);
    5. Tick the Content Sources that should be used when checking for content;
    6. Click the Execute button. Any undocumented items will be listed in the results grid.

    See the Undocumented Items topic for more information.

    Find Undocumented Items Movies

     

    Build and deploy Database reference documentation

    Click the  Build Ribbon button on the Project ribbon tab to build your Database reference documentation.

    In a new project, the default Build Profile will be configured to generate output in compiled CHM Html Help 1.x format.

    Refer to the Deployment topic for more information on how to deploy your documentation to other machines.

     

    Movies