Press "Enter" to skip to content

Category: Documentation

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.

Leave a Comment

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

All-Caps and Technical Writing

Published 2025-08-18 by Kevin Feasel

Mike Robbins argues against over-capitalization:

In technical writing, letter case affects more than style. It influences tone, readability, and accessibility. Typing in ALL CAPITAL LETTERS might seem like an easy way to add emphasis or style, but it often does more harm than good, affecting how quickly readers process information and how your message is perceived.

If you want your message to be clear, approachable, and accessible, avoiding all caps is usually the best approach.

Read on for the reasons why.

Comments closed

Data Dictionaries in Power BI

Published 2025-08-06 by Kevin Feasel

Ben Richardson builds a dictionary:

Have you ever opened a Power BI report and felt overwhelmed by all the columns, measures, and tables?

It can feel like a guessing game trying to figure out what each field represents.

A well-built data dictionary eliminates that confusion, giving you clarity and confidence when exploring reports.

This is one of those bits of documentation that can be incredibly useful but people rarely keep it up to date.

Comments closed

ReplaceInName in dbatools’ Backup-DbaDatabase

Published 2025-04-21 by Kevin Feasel

Jess Pomfret discovers a new flag:

Recently I was reading the docs for `Backup-DbaDatabase` and found a parameter I didn’t realise existed, but is so useful when you want to automate backups, but keep control of the file names.

Click through to learn more about the specific feature, as well as a reminder that it’s a good idea to read through the documentation. Not all documentation is good, but the work people have put into dbatools means that there is often a good example involving most of the available parameters. It turns out that there are, in fact, two examples that use -ReplaceInName in the documentation for Backup-DbaDatabase, so you get not only a description of the parameter but also two specific examples of how to use it.

Comments closed

Finding Microsoft Fabric Administrative Documentation

Published 2025-03-31 by Kevin Feasel

Nicky van Vroenhoven digs through the docs:

Earlier I wrote about the default domain settings, changes to the default tenant setting value for SQL database and I also covered the (rights of the) Fabric Adminsitrator role. Today I want to talk about a more meta-topic: existing documentation on Microsoft Learn, and of course specifically for Admins.

It turns out that there’s a central link for this documentation within Microsoft Learn. Nicky also includes call to action to fix simple documentation issues (such as typos) that you find.

Comments closed

Keeping Documentation Narrow

Published 2025-03-03 by Kevin Feasel

Lukas Eder advises against expansive feature cross-pollination in documentation:

Every product manager knows this situation:

  • A user works with feature X1.
  • They find a limitation / bug / quirk and want to work around it.
  • The perfect workaround or alternative is feature X2, but without knowing that X2 exists, the user doesn’t find it and spends a lot of time looking for it.
  • The user requests X2 be documented on X1, because that would have saved them a ton of time.

This is such a common pattern, and while it’s perfectly understandable for such a user to request this, it is so terribly wrong to give in to this user’s request. Why is it wrong?

Read on for the answer.

Comments closed

Leaving Good Comments in a Stored Procedure

Published 2023-12-07 by Kevin Feasel

Erik Darling comments on your comments:

Possibly the least helpful, but most humorous, way of leaving comments, is a large block of green text up at the top of a module.

There are all sorts of helpful insights buried in those comments to help me as a consultant understand my audience.

But… 

I agree with a lot of where Erik is going with his thoughts. The area where we probably have some daylight is that I’d rather limit comments to statements of why rather than what. Sure, when I’m pseudo-coding out a procedure, I’ll have a bunch of little “do this thing here” types of comments, but I remove those as I build out the code. Instead, explain why you’re doing something if it isn’t patently obvious, if you rewrote a query in a more complicated to read fashion because it performs much better, that kind of thing.

But in fairness, as long as your comments actually reflect the code, it’s really hard to say any code base is ever over-commented. It’s way easier to go the opposite direction.

Comments closed