docs: Improve homepage documentation clarity and structure #118

jeremydhoover-blip · 2026-01-04T07:57:12Z

Changes

Improved homepage documentation with better headings
Simplified getting started instructions
Enhanced code examples for clarity
Added changie entry for documentation update

Checklist

PR is focused on the related task
Documentation improvements included
Changie entry added (.changes/unreleased/docs-20260104-094108.yaml)

- Reorder sections: Install/Auth before Common Tasks - Remove decorative emojis for better accessibility - Add 'Why use the CLI?' and 'What you can do' sections - Expand 'Common tasks' with practical examples - Add automation examples (GitHub Actions, Azure Pipelines) - Reorganize 'Get help' section with clearer categories - Use sentence case for all headings - Add context to all code blocks - Apply active voice and concise language throughout

docs/index.md

HasanAboShally · 2026-01-05T12:50:42Z

PR Review: Homepage Documentation Improvements

Thanks for working on improving the docs structure!

✅ What's Good

"Why use the CLI?" section is a nice addition
Better structured prerequisites with python --version check
Explicit pip install --upgrade example
fab --version verification step
GitHub-based support links

Also,I agree with @ayeshurun's inline comments. The path syntax issues need to be fixed before this can be merged.

A Few More Notes

1. Fabric CLI Path Syntax

The CLI uses dot-suffix notation — this is a core design principle per the copilot-instructions.md:

"The CLI models Fabric as a filesystem-like hierarchy with a consistent dot (.) entity suffix"

Examples:

✅ MyWorkspace.Workspace/MyPipeline.DataPipeline
✅ Sales.Workspace/Reports.Folder/Q4.SemanticModel
❌ /workspaces/MyWorkspace/pipelines/MyPipeline

2. Local→Remote Copy Not Supported

fab cp is for remote-to-remote operations within OneLake. For local files:

Upload items: fab import ./local/notebook.ipynb "Workspace.Workspace/Notebook.Notebook"
The CI/CD examples need to be reworked to use import

3. Removed Content Worth Preserving

The PR removes these community resources:

Microsoft Form feedback link (https://forms.office.com/r/uhL6b6tNsi)
Fabric Ideas Portal (https://ideas.fabric.microsoft.com/)
Developer Community Forum

Consider adding these back under the "Get help" section.

4. Section Ordering

"Common tasks" (complex examples) appears before "Run your first command" (simple fab ls). Flip these so new users see the simple command first.

Recommendation

Address @ayeshurun's inline comments (they're all correct), consider the additional notes above, and this will be ready to merge!

…ions, add community resources

jeremydhoover-blip · 2026-01-07T13:46:41Z

Thanks for the detailed feedback! I've addressed all the comments:

Fixed all path syntax to use CLI-style dot notation
Removed cd example and used full paths
Changed to import for local-to-remote operations
Reordered sections as suggested
Added back community resources

Ready for another look.

ayeshurun · 2026-01-07T19:22:06Z

docs/index.md

    pip install ms-fabric-cli
    fab auth login -u ${{ secrets.CLIENT_ID }} -p ${{ secrets.CLIENT_SECRET }} --tenant ${{ secrets.TENANT_ID }}
-    fab cp ./artifacts/* /workspaces/Production/lakehouses/Data/Files/
+    fab import Production.Workspace/Data.Lakehouse -i ./artifacts/


Suggested change

fab import Production.Workspace/Data.Lakehouse -i ./artifacts/

fab import Production.Workspace/Data.Lakehouse -i ./artifacts/DataToImport.Lakehouse

Jeremy Hoover added 2 commits December 28, 2025 13:26

docs: Add changie entry for homepage documentation improvements

1705cd7

jeremydhoover-blip requested a review from a team as a code owner January 4, 2026 07:57

Merge branch 'main' into docs/update-homepage

67b8f44

ayeshurun reviewed Jan 5, 2026

View reviewed changes