Documentation page/section in the model

[edhans]

Is your feature request related to a problem? Please describe

I would like to have a place to do a more comprehensive description of what things were done they way they were in the model, as well as a list of things to complete, technical debt to clear up, etc. Documentation in other words, beyond what we do in descriptions and inside of measures and other objects. The entire model.

Describe the solution you'd like

A single "page" that perhaps supported markdown but if it doesn't that's fine too, where we can just type what we want to and it is stored in the model. I don't know of there is a place to add an attribute to the model itself in the JSON/TMDL that would be safely ignored by the service. Perhaps similar to the way you added folder groupings.

Goals

No response

Background

No response

Additional context

No response

[otykier]

This can definitely be done using annotations/extended properties, which basically allow you to add anything you want, anywhere in the model metadata. It is all ignored by the service. However, for more than just a few lines of text, I wonder if it would be better to keep this in a .txt / .md file next to the model.bim / model.tmdl? The reason is that strings in annotations/extended properties are escaped, and so it would be more difficult to edit such a document when it's embedded in the metadata, if you want to make the edits directly to the files. Source control diffs would also look weird.

I believe there's a Best Practice Rule that looks for "TODO" in expressions/descriptions. That could easily be extended to consider annotations, if you don't want to clutter up your DAX code / object descriptions with various "TODO" comments. However, for a full blown document (with Markdown formatting, etc.), I would personally go with a separate file next to the model.

Curious to hear others thoughts on this as well.

[mlonsk]

Fundamentally the only place to natively edit a documentation document stored in annotations on the model would be Tabular Editor 3. For me that would be a reason to keep it in a separate file as it would allow other users to document the model in the editing tool of their choice.
The second reason for me to keep a separate file is as Daniel pointed out to source control.

On the other hand, the point @edhans made on Twitter, that having it as an annotation would mean the documentation travels with the model and can even be redownloaded independently of the file existing which I think is an important consideration as many users still store their models outside source control and then a file could easily get lost.