Press "Enter" to skip to content

Category: Documentation

Documenting Power BI Dataset Measures

Published 2021-11-24 by Kevin Feasel

Gilbert Quevauvilliers thinks about documentation:

One thing that often happens is when users are using a dataset, they want to know which measures are available. And not only that sometimes they want to know the measure definition.

This got me thinking and how best could I give this to the users in my organization to be able to find this information quickly and easily.

In the past this was a manual effort not only to export the measures, but also to maintain a document, so that as measures are added, updated, or deleted I would then need to manually update some document.

Yep, you guessed it I created a Power BI report which has got all the measures and their measure definitions, which will update with the dataset! And I show you how I did this below.

Click through to see how.sfff

Comments closed

Dynamic Parameter Code in Powershell

Published 2021-10-27 by Kevin Feasel

Jeffrey Hicks shows off some Powershell 7 functionality:

One of the topics we’ve discussed in the PowerShell Cmdlet Working Group is a request to make it easier to insert dynamic parameters. I am a bit torn on this. On one hand, I see the value in dynamic parameters. These are parameters that only exist if some condition is met, such as if the current location is in the Windows registry. The downside is that these parameters are difficult to discover and awkward to document. On top of that, the PowerShell code necessary to define a dynamic parameter is complicated and definitely not beginner-level. This is what I think the issue is really all about. So I decided to write my own tooling to make it easier to insert dynamic parameters.

Some of those examples go from “This looks reasonable” to “That’s a lot of code” pretty quickly. In fairness, though, this isn’t the type of thing you’ll write every day.

Comments closed

Generating Markdown from SQL Server Metadata

Published 2021-10-15 by Kevin Feasel

Thomas Williams has built a documentation engine:

Sometimes there’s a need to create database documentation – an old fashioned list of tables, columns, views etc. – as part of delivering a project, or for analysts, project managers and end users.

In these situations I tend to automate. SQL Server is very “meta” in that it contains tables and records that describe, well, other tables and records. Coupled with the MS_Description extended property, it’s a powerful way to keep up-to-date documentation in close proximity to the code itself.

The script below will generate Markdown for database tables, views, stored procedures and functions. Column names and data types are listed for tables. View definitions are output. For stored procedures and functions, only the MS_Description extended property will be output.

Click through for a big disclaimer and a bigger script.

Comments closed

Tools Are Not Documentation

Published 2021-09-28 by Kevin Feasel

Ray Kim has a good reminder for us:

I spoke to the form’s owner (this is where the political part comes in). I explained what I was doing. However, he keeps insisting: “it doesn’t have to be documented, because the form is the documentation.”

He showed me a screen shot of text on the form that explains how the particular request works. The text made a lot of sense, and it would have been ideal to fulfill at least part (if not most) of my needs. I decided that I would create a reference to it. So I looked around the form for it… and could not find it anywhere.

He finally told me that “you had to click a specific button on the form to view the text.”

If you’ve developed a process or product, it’s easy to forget that you have a fuller mental model than anybody else, and so things which are blindingly obvious to you probably aren’t to users.

Comments closed

So You Want Database Documentation

Published 2021-05-24 by Kevin Feasel

Joey D’Antoni gives us a primer on database documentation techniques:

Although writing better queries and building the right indexes are important parts of improving database performance, building clear database documentation can also contribute to this goal by helping you understand your database architecture. Painting a clear picture of the structure of your database gives you insight into your data flows and helps you identify redundant data and clarify business processes.

Let’s take a look at a few approaches you can take to documenting your database and your data, depending on the nature of your application.

I do like the idea of using extended properties for documentation purposes, though for the longest time, the tooling to show those extended properties was fairly limited and it was easy to miss them on scripting.

Comments closed

The Case Against Consistency in Code

Published 2021-05-18 by Kevin Feasel

Mark Seemann takes a contrarian approach:

In this essay, I use the term coding style to indicate a set of rules that governs how code should be formatted. This may include rules about where you put brackets, whether to use tabs or spaces, which naming conventions to use, maximum line width, in C# whether you should use the var keyword or explicit variable declaration, and so on.

As already stated, I can appreciate consistency in code as much as the next programmer. I’ve seen more than one code base, however, where a formal coding style contributed to ossification.

Read on for the argument. In this case, the language is C# but the concept applies across the board.

Comments closed

Managing Powershell Functions with PSFunctionInfo

Published 2021-05-04 by Kevin Feasel

Jeffrey Hicks announces a new tool:

Over the last year, I’ve been working on a solution. I’ve been using it and finding it helpful. My friend Gladys Kravitz was also bemoaning the lack of tools for managing stand-alone functions. And while she had her own approach, I thought my solution might offer more. So I polished it up, setup a Github repository, and published a preview release to the PowerShell Gallery. The module is called PSFunctionInfo. You can find the repository on Github. Because it is a pre-release, you might need to install the newest version of the PowerShellGet module so you have the prerelease parameters.

Click through for more detail on how to use it.

Comments closed

Documenting dm_db_missing_index_group_stats_query

Published 2021-02-24 by Kevin Feasel

Erik Darling does a good deed:

When I was checking out early builds of SQL Server 2019, I noticed a new DMV called dm_db_missing_index_group_stats_query, that I thought was pretty cool.

It helped you tie missing index requests to the queries that requested them. Previously, that took a whole lot of heroic effort, or luck.

This has long been a pain point for index-based query tuning. You can guess what the types of queries can look like based on the suggested columns, but one risk of that guessing is that index order matters but the columns get returned in the order in which they exist on the table, not necessarily the order in which they would be most useful.

Comments closed

Power BI Model Documentation

Published 2021-02-12 by Kevin Feasel

Marc Lelijveld reflects on an overlooked part of development:

I strongly believe that it is key to describe everything that you have built as part of your Power BI model. As we all have a hate-love relationship with documenting our work, the external tool that I build to document your Power BI solutions could come in useful. In particular everything you add and only exists in your model is important to describe properly. This documentation is key once you share your data model with others and they try to understand the goal of a measure, column or anything else. Other than that, documentation also comes in useful if you handover your solution to your colleague or client.

Read on to see what you can currently document.

Comments closed