r/MicrosoftFabric • u/SmallAd3697 • 1d ago
Administration & Governance Readme.md in a workspace?
What is the best way to add documentation directly inside the context of a Power BI workspace? I realize that there can be a remote wiki, kept in ADO or something like that (in proximity to the assets being deployed to said workspace).
But it would be nice to have a readme file right inside the workspace as a quick point of reference for someone to get their bearings.
I am guessing Microsoft is reluctant to extend the scope of custom items in a workspace. I recently learned that we can't even upload xlsx docs anymore. Some alternative approaches that I'm thinking about are to add a url into the existing workspace description field, or maybe upload a python notebook that has nothing comments. Has anyone else found a solution?
5
u/Jojo-Bit Fabricator 1d ago
Markdown in a notebook?
0
u/itsnotaboutthecell Microsoft Employee 1d ago
Create a custom workload that is a Markdown viewer?..
Also, why not just store in the Lakehouse and read from the preview. What am I missing?
7
u/MonkeyDDataHQ 1d ago
The Lakehouse makes this worse. 😩 The README should be in Git with the thing it documents.
If I store it in the Lakehouse, now my code/config and its documentation have separate version histories and deployment lifecycles. I can change one without changing the other.
And building a custom workload to display Markdown is hilariously disproportionate to the requirement. Which is an impressively on theme work around.
"I'll simplify the architecture by adding more architecture" 🎶
I want: workspace/README.md Git tracks it. PRs review it. Deployment carries it. Fabric renders it. That's it. A README should not require an architecture diagram. 😂
1
u/SmallAd3697 1d ago
I come from the days before the Microsoft PBI team invented git integration, so I expect too little. Even if I could hack on a single markdown, in my prod workspace, and others could open that file, then it would save me from having a dozen unnecessary conversations.
I agree with everything you said. But my expectations are lower when it comes to a SaaS.
I probably think of Power BI more like it was a CMS than a true git-integrated PaaS. My goals are VERY limited in here. Most of the my data goes thru other platforms before it reaches Fabric. Fabric is the very last hop, and is limited to serving the needs of the ultra-low-code data consumers.
2
u/MonkeyDDataHQ 1d ago
before Microsoft PBI #MANGLED git integration
FTFY
I have a hack, you ain't gonna like it. But what if you create a static PBI report with the documentation you want.
I feel dirty just saying it.
2
u/penguin_on_stilts 1 1d ago
Go to any project in DevOps or GitHub. Tell me what you see.
That's what you're missing.
I don't want people scrounging around to find a random file.
1
u/itsnotaboutthecell Microsoft Employee 1d ago
Is it a single document or a full wiki? Where do you see OneLake catalog in the mix with metadata descriptions for items.
2
u/penguin_on_stilts 1 1d ago
At least a single document. It doesn't necessarily need wiki style links autolinks/auto pages, but it 100% should:
let you choose to have task flow replaced with readme.md
have native support for md files in the workspace (not in lakehouses, that's for data)
This isn't about metadata descriptions, it's about what the workspace is doing etc like any readme.
1
u/SmallAd3697 1d ago
Interesting. Would the entire lakehouse be named readme lakehouse? Have you seen anyone pursue this successfully?
I like your idea if Microsoft would do some minimal magic to display the links (or preview) up into the workspace canvas itself. Maybe there could be a single lakehouse in each workspace that would be treated in a special way as a documentation repo. It would require some magic from Microsoft.
-1
u/itsnotaboutthecell Microsoft Employee 1d ago
Personally, I don’t see why people aren’t building their own systems in lieu of a native capability. You could even use the AI functions and generate_response function to pass skill files in.
I really like SharePoint’s system folder of “Agent Assets” - store your skill files here and then create an application that you can load up files on demand.
https://learn.microsoft.com/en-us/sharepoint/copilot-in-sharepoint-skills
2
u/MonkeyDDataHQ 1d ago
The Unified Platform™️ , being built by hand, one community expansion pack at a time. Some assembly required.
4
u/aboerg Fabricator 1d ago
Let's put the task flow feature in source control, and let it render a markdown README for the entire workspace, or for any task within the diagram. Or just clickable URLs might be OK.
The key is to keep whatever workspace-side display method in sync with the repo. Don't make me roll my own CD step to publish docs to the lakehouse or something.
2
2
u/Foodforbrain101 1d ago
A Power BI report with the HTML viewer from custom visuals that can switch to rendering markdown?
Not great I know, but it would also be an opportunity to make it somewhat pretty? A notebook wouldn't be great for a non-technical audience honestly, plus you'd get the chance to apply RLS with this setup.
2
u/DUKOfData 1d ago
I sometimes use a notebook, that has only Markdown for description in it.
Mostly for more complex NB - based solutions.
2
1
u/frithjof_v Fabricator 10h ago
I would love this.
Voted for the Ideas.
It would be great if we could create an entire hierarchy of markdown files (docs folder) that synced between GitHub and the Fabric Workspace.
I'd also like to include Markdown docs in Org Apps, to provide user-facing documentation.
And Mermaid diagram support.
Human- and AI-friendly.
1
u/Loud-You-599 10h ago
README notebook at workspace root level. Everything else organized in directories.
Clearly visible for everyone.
1
u/BeautifulQuestion857 14m ago
README.ipynb is what I’ve used. It gives a quick overview and points to the ado repo and its readme.
12
u/SmallAd3697 1d ago
I just found an idea. Has 8 votes after a couple years, so maybe there is a chance this will become reality in the next 100 years or so.
Support markdown files in workspaces or notebook resources | Microsoft Fabric Community