Press "Enter" to skip to content

Category: Documentation

Using Database Properties to Assist Generative AI Solutions

Published 2026-02-18 by Kevin Feasel

Brent Ozar makes use of extended properties:

You can add database instructions as extended properties at the database or object level, and when Copilot works with those objects, it’ll read your instructions and use them to shape its advice.

For example, you can add a database-level property called a “constitution” with your company’s coding standards, like this:

Andy Brownsword has another example:

The new Database Instructions are text stored against database objects to add more context about the object and how it should be used. A simple example:

We find a Sales table with a Price column. Is that the price for a single unit or the line total? Does that include or exclude VAT? What about discounts?

This is where context is king, and Database Instructions allow us to annotate these details and remove the ambiguity.

Database properties are a criminally underused part of SQL Server—in part because there wasn’t great tooling around how to display or work with these properties—and if this forces people to be a bit thoughtful in design and after-the-fact documentation on database objects, so much the better.

Leave a Comment

License Types now Workspace Types in Microsoft Fabric

Published 2026-02-17 by Kevin Feasel

Nicky van Vreonhoven notices a change in language:

Just a quick post because I noticed a change in the Fabric UI, specifically in the Workspace settings.

I am working on a demo for my Power BI Gebruikersdagen session, and wanted to switch a workspace to Fabric capacity. I noticed that the setting License type has changed, and is now called Workspace type.

Read on to see where this has changed and a few more notes from Nicky.

Leave a Comment

A Story of Code that Aged Well

Published 2026-02-12 by Kevin Feasel

Hugo Kornelis wrote some code:

The application had clearly been developed by someone who knew just one tool: SQL Server. So he made the database do all kinds of things that really should have been in the application layer. Call external APIs to monitor the primary process of the company. Send fully formatted emails with invoice information. Send formatted HTML and interpret the callback response as a picked menu item. Yes, all that was handled in SQL Server, the frontend app did nothing more than sending query results to the web server and sending HTTP replies back to the database as a parameter into a stored procedure that handled everything.

Read on to see what Hugo was able to do in a one-year timeframe and what it was like coming back to that same code years later.

Leave a Comment

Preventing Legacy Code

Published 2026-02-11 by Kevin Feasel

Deborah Melkin shares some tips on preventing code from becoming “legacy code”:

This is an interesting question. In some ways, it’s hard to say how my code has aged. no one is yelling at me that my code is breaking production, so that’s a good sign. I have definitely talked about times where I wish I could go back and do something differently because it would have been a little bit smarter to do. I’m no longer at some of those companies and one of them doesn’t even exist in that incarnation anymore so I have no clue how that code is being used or if it even got fully implemented. I’ve done a lot of reviews of other people’s code and the most problematic legacy code was the code that would have been problematic at the time it was written but was good enough to get by.

Read on for a couple of broad tips that can help keep your code from becoming “legacy code” in the pejorative sense of the term.

Leave a Comment

Viewing Nested Lists in R with xfun::tabset()

Published 2026-02-10 by Kevin Feasel

Yihui Xie wants to document the contents of nested lists:

Complex nested lists in R can be difficult to explore and understand at a glance. The str() function is helpful for examining structure, but large nested lists can quickly become overwhelming.

While I was writing the documentation for tabsets in litedown, I almost laughed at myself for the support for nested tabsets, because I had no idea why anyone would want this feature. However, I suddenly realized that it can be a very useful tool for exploring nested lists in an interactive way, so I wrote a quick implementation: xfun::tabset().

Click through to see how it works.

Leave a Comment

The Troubles of Documentation: Microsoft Fabric API Edition

Published 2026-02-06 by Kevin Feasel

Rob Sewell walks through a recent experience:

Firstly, an apology to my friends (especially Randolph) in the documentation team at Microsoft. I know how hard you work to produce accurate and useful documentation, and I appreciate your efforts. This is not a criticism of your work, but rather an observation about the challenges I faced.

This is a story about a recent experience and the lessons learned along the way.

Read on for the issue and what Rob had to do. This is a case study in how hard it is to write good documentation, especially around the edges of what is possible.

Leave a Comment

A Data Model for Git

Published 2026-01-09 by Kevin Feasel

Julia Evans updates the Git documentation:

After a while working on the documentation, we noticed that Git uses the terms “object”, “reference”, or “index” in its documentation a lot, but that it didn’t have a great explanation of what those terms mean or how they relate to other core concepts like “commit” and “branch”. So we wrote a new “data model” document!

You can read the data model here for now. I assume at some point (after the next release?) it’ll also be on the Git website.

Click through for the documentation as well as some more thoughts on Git documentation in general and contributing to Git.

Comments closed

Maintaining Microsoft Documentation

Published 2025-12-11 by Kevin Feasel

Steve Jones is a mensch:

One of the things that I like about the SQL Server docs (MS Learn Docs) is that I can fix things I find wrong. For years we had downloaded Books Online from installs, then we have BOL on a site, but those were mostly updated when a new release came.

Now we have MS Learn, and a regularly changing set of docs. If you haven’t taken advantage of these docs for SQL Server, you should. Bookmark: https://learn.microsoft.com/en-us/sql/sql-server/?view=sql-server-ver17&redirectedfrom=MSDN

I help change those. It’s part of my contribution as a Microsoft MVP, but it’s also something that I enjoy because it makes my life easier. This post will look at how I do this.

Some of us sit back and complain. Some of us go and do.

I remain up in the balcony and heckle like my personal heroes, Statler and Waldorf.

Comments closed

Code Blocks and Inline Code in Markdown

Published 2025-09-26 by Kevin Feasel

Mike Robbins continues a series on Markdown:

Technical writers often need to embed code in their articles, whether snippets, configurations, commands, or examples. When presented clearly, code in your articles reinforces understanding and helps readers follow along more easily. When presented poorly, it creates confusion and frustration. This article demonstrates how to use inline code and code blocks effectively in Markdown, ensuring your code is readable, maintainable, and helpful to your audience.

This is, fortunately, a bit of Markdown that is very consistent across platforms.

Comments closed

Building Lists in Markdown

Published 2025-09-16 by Kevin Feasel

Mike Robbins has a list and checks it twice:

In Part 1: Getting Started with Markdown for Technical Writers, I introduced the basics of Markdown, including how to format both ordered and unordered lists. This article builds upon that foundation, providing everything you need to know about using lists in Markdown, from basic syntax to advanced formatting techniques.

As a technical writer, understanding how and why to use lists in Markdown isn’t just about syntax. It’s about clarity, structure, accessibility, and intent.

Read on to see how to create ordered and unordered lists, as well as several tips around when to use each and appropriate nesting of lists.

Comments closed