Documentation is an essential part of software development. It helps developers understand the purpose and functionality of code, making it easier to maintain and troubleshoot. However, when it comes to contributing to documentation, developers often come up with excuses like “the code is self-documenting” or “there is no established process”. In this article, we will address these concerns and discuss how to improve SQL Server documentation.

The Myth of Self-Documenting Code

While some developers argue that their code is self-documenting, the reality is that even the most well-written code can become complex and obscure over time. SQL, although a relatively simple and descriptive language, can also become difficult to understand, especially during urgent support queries. Therefore, it is important to acknowledge that there is no such thing as self-documenting code.

Establishing a Documentation Process

To ensure consistent and effective documentation, it is crucial for lead developers to establish a documentation process that must be followed by the entire organization. This process should include guidelines for documenting new objects, as well as updating comments for legacy objects. By enforcing this process through peer reviews, developers will be motivated to contribute to the documentation.

Key Documentation Guidelines

• New objects must have brief but clear comments that determine their intent.
• Tables and views should have comments explaining the records they represent.
• Fields in tables should have comments describing their intended use.
• Functions and stored procedures should have comments explaining their purpose and any peculiarities of their use.
• Parameters should have comments stating their intent and valid values.

By following these guidelines, developers can ensure that the documentation is comprehensive and up-to-date.

Keeping Documentation Up-to-Date

One common concern is that code comments and documentation become out-of-date as soon as they are written. While it is true that code comments are not bound to the code itself, the effort should be focused on comments that can be assembled by a documentation tool. It is important to use a web-based documentation tool that allows everyone to access the same version of the documentation. Additionally, an automated process should be implemented to regularly rebuild the documentation, ensuring that it is always up-to-date.

Using Red-Gate SQLDoc 2.0

Red-Gate SQLDoc 2.0 is an inexpensive documentation tool for SQL Server that simplifies the process of generating documentation. It relies on extended properties for objects, which can be easily maintained using SQL Management Studio or SQL scripts. By specifying the connection and project settings, SQLDoc can generate web-based documentation, CHM files, or MS Word documents.

Automating Documentation Generation

To make documentation generation a seamless process, it is recommended to automate it using Windows scheduled tasks. By scheduling regular documentation rebuilds, developers can ensure that the documentation is always up-to-date. Additionally, the documentation can be easily deployed to a web server using simple commands or scripts.

Improving Documentation Accessibility

To improve the accessibility of the documentation, it is important to set up virtual directories for common files such as images, stylesheets, and scripts. This allows for easy customization of the documentation site and ensures that changes to these common files are reflected across all documentation sets.

Marketing the Documentation

Lastly, it is important to promote the documentation within the organization. The documentation should be seen as a valuable resource for developers, business analysts, and other stakeholders. By highlighting the benefits of having comprehensive and up-to-date documentation, developers will be more motivated to contribute to the documentation and utilize it in their work.

Conclusion

Improving SQL Server documentation requires establishing a documentation process, using the right tools, and promoting the value of documentation within the organization. By following these guidelines, developers can ensure that the documentation is comprehensive, up-to-date, and easily accessible. This will ultimately lead to more efficient development and support processes.