I like the idea to use Markdown to comment SQL. Markdown documents could be very easy integrated in WIKI documents. It would be easy to combine "normal" WIKI content with automated generated content.
And I had a look on the mindoc. Currently I have no idea how to use this tool to document a complete DWH. It looks like the tool is good for documenting ad-hoc SQL.
BTW, this is one reason why I recommend to users and testers to use Azure Data Studio and their notebooks. This is great to combine ad-hoc queries with descriptions and comments in markdown.
I found this article searching "database documentation to markdown". Normally I use SQL Server extended properties to document most objects. Markdown could also be used in these properties, linebreaks are supported.
I also will try github.com/k1LoW, after I understand how to start. They want to document databases in markdown, why not to use markdown in "comments"? then these formatted comments could be integrated into the documentation.
One more issue is missing support in frontends: For example I document all my tables, columns and measures in SSAS Tabular, but Power BI does not even support line breaks in comments.
But the idea to use Markdown in descriptions should be promoted. It's very easy.
Thanks. I was so focused on making something my team needed that I hadn't elaborated the use. The first "version" was made for documenting single python files used for data pipelines. Because we would use SQL scripts as well for some parts of the ETL pipeline, I figured it would be convenient to use the same package to document .sql files as well as .py files.
I guess there would be SQL specific documentation tools... This mindoc I've made requires a python environment - and I haven't even properly packaged it up yet. Maybe in the near future...
Whether this tool or not, I think using markdown (within comments) to document SQL is useful, at least it has been for my team. Let us know of the documentation landscape within SQL as you test them out (perhaps a blog post here in dev.to!) - I live mainly in Python land and am not knowledgeable.
I like the idea to use Markdown to comment SQL. Markdown documents could be very easy integrated in WIKI documents. It would be easy to combine "normal" WIKI content with automated generated content.
And I had a look on the mindoc. Currently I have no idea how to use this tool to document a complete DWH. It looks like the tool is good for documenting ad-hoc SQL.
BTW, this is one reason why I recommend to users and testers to use Azure Data Studio and their notebooks. This is great to combine ad-hoc queries with descriptions and comments in markdown.
I found this article searching "database documentation to markdown". Normally I use SQL Server extended properties to document most objects. Markdown could also be used in these properties, linebreaks are supported.
I also will try github.com/k1LoW, after I understand how to start. They want to document databases in markdown, why not to use markdown in "comments"? then these formatted comments could be integrated into the documentation.
One more issue is missing support in frontends: For example I document all my tables, columns and measures in SSAS Tabular, but Power BI does not even support line breaks in comments.
But the idea to use Markdown in descriptions should be promoted. It's very easy.
For a very long time I use sqlspec: elsasoft.org/
They allow to use XML in extended properties to generate formatted descriptions. But Markdown is much easier to use than XML.
But the development has stopped, there will be no markdown support. I use it as it is.
Thanks. I was so focused on making something my team needed that I hadn't elaborated the use. The first "version" was made for documenting single python files used for data pipelines. Because we would use SQL scripts as well for some parts of the ETL pipeline, I figured it would be convenient to use the same package to document .sql files as well as .py files.
I guess there would be SQL specific documentation tools... This mindoc I've made requires a python environment - and I haven't even properly packaged it up yet. Maybe in the near future...
Whether this tool or not, I think using markdown (within comments) to document SQL is useful, at least it has been for my team. Let us know of the documentation landscape within SQL as you test them out (perhaps a blog post here in dev.to!) - I live mainly in Python land and am not knowledgeable.
Cheers
one product I found. Look at this example with nice markdown support in the "comments":
schemaspy.org/sample/index.html