Why LiveDoco?

Background

There are many database documentation tools on the market today, both commercial and free. These tools can generate nicely formatted database documentation or data dictionary from your database. Supported output formats are usually HTML, CHM and Microsoft Word. Some of them allow editing descriptions.

The Problem

All these fine tools are documentation generators. They take a database and generate a data dictionary document. Once generated, the document no longer depends on the source database it was generated from and is essentially read only, even if it is a MS Word document because any changes to it would be lost once it is regenerated.

The solution is to keep these notes in the source database, and there are built-in facilities for that in most modern RDBMS, including SQL Server’s MS_Description Extended Properties.

The problem is that the standard SQL Server Management Studio does not provide a user friendly way to edit them. Installing the above-mentioned tools would address this issue to some extent, but it is still far from ideal.

Commercial tools are feature rich but quite expensive and installing such software on every developer’s and DBA’s PC is usually not feasible.

Both commercial and free tools would also create additional IT admin overhead - installation and maintenance.

Even from user's perspective this solution is suboptimal. Imagine the following scenario: A developer or browses the database documentation and finds an error or an omission. In order to fix it he needs to:

  1. Start the documentation tool (say 20 seconds including connection to the preselected database)
  2. Find the place that needs editing (5 seconds)
  3. Edit it (let's say 20 seconds for a relatively simple edit)
  4. Then trigger the documentation rebuild (another 30-40 seconds or more depending on the database complexity)

That's three extra steps and a full extra minute for something as simple as changing a couple of words in the documentation! And by the way - the rebuild might even fail due to the file locking errors if there are other people using the same document. There's got to be an easier way, right?

How is LiveDoco Different?

What if we had a tool that allowed us to just edit the descriptions in place? Like we would change our Facebook status?

Enter LiveDoco. It does just that - it is not a documentation generator. Instead, it is a web-based front end to your database’s metadata. It renders database object pages directly from the underlying database. The comments on the pages can easily be edited (just click on the pencil icon next to the text). And changes would be immediately visible to all your team members using the same database. The information displayed by LiveDoco is practically never out of sync with the actual state of your database.

LiveDoco is Cost Efficient

It is unlikely that all your technical staff (developers, DBA’s, testers, support etc.) will need to use LiveDoco most of the time, and since LiveDoco license only limits the number of current active connections – this number can be significantly lower than the total number of users.

Furthermore, you can always upgrade your license to a bigger number of connections and still pay the same total amount as if you bought it in one purchase, so this increases cost efficiency by making license connections overprovisioning unnecessary.

"Live" data dictionary

LiveDoco is not just a convenient web-based extended property editor. LiveDoco is like your “personal MSDN and Wiki in one” to your SQL Server databases, A kind of "Live" data dictionary. It supports deep linking down to the sub-object level. So you can literally send an email to your fellow developer with a link to a column in a database where you’ve recently added some useful notes - just as you would send say an MSDN link! There is an example link in the online demo section of this website.

Much effort has been put into providing a fluid, enjoyable user experience. On commodity hardware it usually renders pages under 300-500ms on first hit, subsequent accesses are much faster. On every database object’s page if there is a reference to some other object (for example a table or a stored procedure) or even a sub-object (a column, parameter or check constraint etc.) – it is always represented as a hyperlink and when clicked – not only takes you to the destination page but also momentarily blinks the destination sub-object’s background to attract user’s attention and save few seconds on eyeballing (if it is a sub-object link, of course).

In addition to that there is a flexible search facility allowing users to choose where to look for the match (object names and/or descriptions) and the search type (contains, starts/ends with, exact match).

Most sections in LiveDoco are foldable – so you can hide the ones you are not interested in at the moment. Some less important sections are rendered folded by default - to conserve screen space.

And finally there is a user extensible export facility that allows exporting descriptions to a SQL file that can be used to merge them into another DB of similar structure. Other supported modes are XML (via an optional XSLT transform) and Razor (ASP.NET MVC technology) templates. Export functionality can easily be extended by users by providing their own XSLT or Razor templates along with a simple XML descriptor file. LiveDoco comes with few examples of both.

LiveDoco and Documentation Generators

There are of course cases when you really need an offline data dictionary document – LiveDoco technically could generate a single HTML or PDF file using an export template but currently it does not have such template. A dedicated documentation generator should be used for these purposes. LiveDoco puts notes where most generators would look for them so they organically complement each other.